前端移动开发UI组件跨平台【免费下载链接】react-native-bottom-sheetA performant interactive bottom sheet with fully configurable options 项目地址https://gitcode.com/gh_mirrors/re/react-native-bottom-sheet点击查看免费下载本篇指南以 react-native-bottom-sheet 官方 v4 文档中的 Props 章节 为骨架系统梳理BottomSheet组件的全部可配置参数吸附点与初始状态、样式、布局测量、键盘交互、动画、手势、动画节点、回调以及可插拔子组件。读完本文你将掌握每个 Props 的类型约束、默认值、适用场景并能结合仓库源码理解其底层实现从而在实际业务中精准配置一个高性能、可交互的底部面板。BottomSheet是 react-native-bottom-sheet 的核心组件通过 Props 定义 可看到所有配置被划分为 configuration配置、layout布局、keyboard键盘、styles样式、animated nodes动画节点、callbacks回调、components组件等多个区域。一个最小化的使用方式如下完整示例见 usage.mdimport React, { useCallback, useMemo, useRef } from react; import { View, Text, StyleSheet } from react-native; import BottomSheet from gorhom/bottom-sheet; const App () { const bottomSheetRef useRefBottomSheet(null); const snapPoints useMemo(() [25%, 50%], []); const handleSheetChanges useCallback((index: number) { console.log(handleSheetChanges, index); }, []); return ( View style{styles.container} BottomSheet ref{bottomSheetRef} index{1} snapPoints{snapPoints} onChange{handleSheetChanges} View style{styles.contentContainer} TextAwesome /Text /View /BottomSheet /View ); };核心配置吸附点、初始状态与手势开关这一组 Props 决定了面板的基本行为初始停在哪个吸附点、允许吸附到哪些位置、拖拽时的手感以及是否允许下拉关闭。index初始吸附点索引。传入-1可以让底部面板以关闭状态启动。类型默认值必填number0否在 BottomSheet.tsx 中index的解构默认值为0同时内部使用useSharedValue维护当前索引const animatedCurrentIndex useReactiveSharedValue( animateOnMount ? -1 : _providedIndex );注意当animateOnMount为true时索引初始化值会被设为-1关闭态待布局计算完成后再动画到初始索引。开发模式下 usePropsValidator 还会校验index必须落在[-1, snapPoints.length - 1]范围内。snapPoints面板可以吸附的点集合必须按照从底部到顶部的顺序排列。它接受数字、字符串百分比或两者的混合数组也支持SharedValueArraystring | number形式的响应式吸附点。类型必填Arraynumber|string | SharedValueArraystring | number是*⚠️ 除非将enableDynamicSizing设置为true否则该参数必须提供。 ⚠️ 字符串值必须是百分比形式。snapPoints{[200, 500]} snapPoints{[200, 50%]} snapPoints{[100%]}百分比字符串在底层会通过 normalizeSnapPoint 转换为像素值// 百分比吸附点转换为像素 if (typeof normalizedSnapPoint string) { normalizedSnapPoint (Number(normalizedSnapPoint.split(%)[0]) * containerHeight) / 100; } return Math.max(0, containerHeight - normalizedSnapPoint);即50%会被解析为容器高度的一半再换算成面板的顶部偏移位置数值越小面板展开越高。完整的归一化与排序逻辑位于 useAnimatedSnapPoints它会等待容器布局就绪containerHeight不再是初始哨兵值INITIAL_CONTAINER_HEIGHT -999再依次归一化每个吸附点。overDragResistanceFactor定义面板在超出最高吸附点over drag时被刹停的剧烈程度。类型默认值必填number2.5否该默认值定义于 constants.tsDEFAULT_OVER_DRAG_RESISTANCE_FACTOR 2.5。数值越小面板越容易被拖出边界并更难停下来数值越大超出边界的阻力越强。detached定义面板是否脱离屏幕底部。当设置为true时面板不与容器底部贴合常用于实现浮动式detached卡片效果例如示例中的 DetachedExample.tsx。类型默认值必填booleanfalse否从源码看detached会影响关闭位置的计算见 BottomSheet.tsxconst animatedClosedPosition useDerivedValue(() { let closedPosition animatedContainerHeight.value; if ($modal || detached) { closedPosition animatedContainerHeight.value bottomInset; } return closedPosition; }, [animatedContainerHeight, $modal, detached, bottomInset]);即脱离模式下关闭位置会在容器高度基础上再加上bottomInset。enableContentPanningGesture是否启用内容区域的拖拽手势交互。类型默认值必填booleantrue否该参数与enableHandlePanningGesture分别控制内容区和手柄区的拖拽。将其设为false后用户只能通过另一个开关的对应区域来拖拽面板例如自定义按钮触发expand/collapse方法适用于不希望内容区抢占滚动事件的场景。enableHandlePanningGesture是否启用手柄区域的拖拽手势交互。类型默认值必填booleantrue否对应源码常量DEFAULT_ENABLE_HANDLE_PANNING_GESTURE trueconstants.ts。enableOverDrag是否允许面板被拖拽超过最高吸附点。类型默认值必填booleantrue否关闭后面板在最高点会被硬性拦截不会再出现超出边界的弹性效果适合对边界手感有严格要求的场景。enablePanDownToClose是否允许用户通过向下拖拽手势直接关闭面板。类型默认值必填booleanfalse否默认关闭因此如果你希望在snapPoints之外支持拖到底部关闭的交互需要显式打开它。v4 文档还特别提醒不要通过把吸附点设为0或负数来模拟关闭正确做法是使用enablePanDownToClose——usePropsValidator 会直接校验并抛出错误Snap point 0 is invalid. if you want to allow user to close the sheet, Please use enablePanDownToClose prop.enableDynamicSizing是否启用基于内容尺寸的动态尺寸计算作用于内容视图与可滚动内容的高度。类型默认值必填booleanfalse否⚠️ 注意在 v4 文档中该参数默认值为false而在当前仓库源码 constants.ts 中DEFAULT_DYNAMIC_SIZING已更新为true。使用前请以你实际安装的版本为准。开启后的行为需要特别留意它会在你提供的吸附点基础上新增一个吸附点并重新排序这可能影响索引编号。官方文档给出的例子是若提供snapPoints{[100, 1000]}而内容实际高度为500那么最终的吸附点将变为[100, 500, 1000]。底层计算在 useAnimatedSnapPoints 中实现// 基于内容高度计算动态吸附点 const dynamicSnapPoint containerHeight.value - Math.min( contentHeight.value handleHeight.value footerHeight.value, maxDynamicContentSize ! undefined ? maxDynamicContentSize : containerHeight.value ); // 若不存在于已提供的吸附点列表则追加 if (!_normalizedSnapPoints.includes(dynamicSnapPoint)) { _normalizedSnapPoints.push(dynamicSnapPoint); } // 排序并定位动态吸附点的索引 _normalizedSnapPoints _normalizedSnapPoints.sort((a, b) b - a); dynamicSnapPointIndex.value _normalizedSnapPoints.indexOf(dynamicSnapPoint);可以看到动态吸附点的取值是内容高度 手柄高度 页脚高度与maxDynamicContentSize或容器高度二者中的较小值再换算为顶部偏移。因此它不会超过你通过maxDynamicContentSize设定的上限。animateOnMount为true时面板会先以关闭状态挂载待布局测量完成后再动画切换到index指定的初始吸附点。类型默认值必填booleantrue否样式配置从阴影到手柄指示器这一组 Props 用于调整面板各组成部分的视觉样式。style作用于面板容器sheet container的 View 样式也可以是AnimatedStyle。典型用途是给面板添加阴影效果官方配套的阴影实现可参考 adding-shadow.mdx。类型默认值必填ViewStyle | AnimatedStyleundefined否在类型层面types.d.ts 对style做了更严格的约束移除了flexDirection、position、top/left/bottom/right、opacity、transform等由库内部控制的布局属性避免外部样式破坏面板的定位与位移动画。backgroundStyle作用于背景组件background component的 View 样式。类型默认值必填ViewStyleundefined否handleStyle作用于手柄组件handle component的 View 样式。类型默认值必填ViewStyleundefined否handleIndicatorStyle作用于手柄指示器handle indicator即手柄中间那条小横条的 View 样式。类型默认值必填ViewStyleundefined否布局配置吸附点精确计算的前提面板内部需要知道容器、手柄、内容等各部分的尺寸才能把吸附点换算成正确的像素偏移。这些参数决定了计算的精确度与是否需要额外的重新渲染。handleHeight手柄高度用于内部容器与面板布局的计算。当提供了handleComponent时库内部会自动测量其布局但如果你同时显式提供了handleHeight则以你提供的值为准跳过自动测量。类型默认值必填number24否默认值24定义于 constants.ts。若handleComponent传null则内部会把animatedHandleHeight强制置为0见 BottomSheet.tsx。containerHeight容器高度用于内部面板布局计算。如果不提供库内部会自行测量但代价是一次额外的重新渲染。类型默认值必填number0否在 BottomSheet.tsx 中容器高度会被包装为响应式共享值且在 Modal 模式下会自动扣除topInset bottomInset的垂直方向内边距。布局是否就绪的判断条件之一是容器高度不再是初始哨兵值INITIAL_CONTAINER_HEIGHT -999见 isLayoutCalculated。contentHeight内容高度用于动态吸附点的计算。类型默认值必填number | Animated.SharedValuenumberundefined否当enableDynamicSizing开启时它是计算动态吸附点的关键输入。配合 useBottomSheetDynamicSnapPoints 钩子与BottomSheetView的onLayout回调可以自动测量内容尺寸并回填相关用法见 dynamic-sizing.mdx。containerOffset容器偏移用于精确检测容器在屏幕中的偏移位置。类型默认值必填Animated.SharedValueInsetsundefined否类型上要求是SharedValueRequiredInsets含 top/bottom/left/right 四个方向源码中默认使用全零的INITIAL_CONTAINER_OFFSETconstants.ts。topInset添加到面板容器顶部的内边距通常来自react-navigation/stack的useHeaderHeight或react-native-safe-area-context的useSafeArea。类型默认值必填number0否它参与百分比吸附点的换算在 BottomSheet.tsx 中Modal 模式下topInset会从容器高度中扣除从而让100%吸附点不会顶到屏幕最顶端而是避开状态栏与导航栏。bottomInset添加到面板容器底部的内边距。类型默认值必填number0否在detached或 Modal 模式下它同样参与关闭位置与容器高度的计算。maxDynamicContentSize动态内容的最大高度上限用于限制面板在动态尺寸模式下不会超过指定高度。类型默认值必填numbercontainer height否未提供时默认以容器高度为上限见 useAnimatedSnapPoints 中maxDynamicContentSize ! undefined ? maxDynamicContentSize : containerHeight.value的逻辑。键盘配置表单输入场景的三种策略当面板内含TextInput时键盘的弹出会挤压布局。这一组 Props 让你精细控制键盘出现/消失时面板的行为。keyboardBehavior定义键盘弹出时面板的表现。extend面板延伸到最大吸附点。fillParent面板延伸填满父视图。interactive面板按键盘的高度做偏移。类型默认值必填extend | fillParent | interactiveinteractive否对应常量定义于 constants.tsKEYBOARD_BEHAVIOR并在 BottomSheet.tsx 中作为默认值解构。键盘监听逻辑由 useKeyboard.ts 提供。官方的组合用法与动效演示可参考 keyboard-handling.mdx。keyboardBlurBehavior定义键盘收起blur时面板的行为。none不做任何处理。restore恢复面板到键盘弹出前的位置。类型默认值必填none | restorenone否android_keyboardInputMode仅针对Android定义键盘输入模式对应 Android 系统 WindowSoftInputMode 的语义。类型默认值必填adjustPan | adjustResizeadjustPan否动画配置spring 与 timing 二选一animationConfigs面板位移动画配置可通过以下两个官方钩子生成useBottomSheetSpringConfigs生成弹簧动画配置。useBottomSheetTimingConfigs生成时间曲线动画配置。type animationConfigs ( point: number, velocity: number, callback: () void ) number;类型默认值必填functionundefined否在类型定义中animationConfigs实际对应WithSpringConfig | WithTimingConfig见 types.d.ts 的BottomSheetAnimationConfigs。一个完整的 spring 示例import React from react; import BottomSheet, { useBottomSheetSpringConfigs } from gorhom/bottom-sheet; const SheetContent () { const animationConfigs useBottomSheetSpringConfigs({ damping: 80, overshootClamping: true, restDisplacementThreshold: 0.1, restSpeedThreshold: 0.1, stiffness: 500, }); return ( BottomSheet // ... 其他 props animationConfigs{animationConfigs} {CONTENT HERE} /BottomSheet ); };timing 版本则只需提供duration与easingconst animationConfigs useBottomSheetTimingConfigs({ duration: 250, easing: Easing.exp, });值得一提的是仓库在 constants.ts 中内置了平台默认动画iOS 使用弹簧参数damping 500、stiffness 1000、mass 3Android 使用 250ms 的Easing.out(Easing.exp)时间曲线。useBottomSheetSpringConfigs/useBottomSheetTimingConfigs的完整说明见 hooks.md。手势配置与 Gesture Handler 的深度协作面板的拖拽基于 react-native-gesture-handler 的 Pan 手势这组 Props 让你能与其他手势如列表滚动、横向滑动手势协调优先级。waitFor指定等待的手势引用只有当这些手势失败后面板拖拽手势才会激活。类型默认值必填React.Ref | React.Ref[][]否simultaneousHandlers指定可以同时进行的手势引用用于与横向滚动等手势并行识别。类型默认值必填React.Ref | React.Ref[][]否在 types.d.ts 的BottomSheetGestureProps中waitFor被映射为 Pan 手势的requireExternalGestureToFailsimultaneousHandlers被映射为simultaneousWithExternalGesture。activeOffsetX / activeOffsetY指定手势激活所需的水平 / 垂直方向的位移阈值数组。类型默认值必填number[]undefined否failOffsetX / failOffsetY指定手势判定失败所需的水平 / 垂直方向的位移阈值数组。类型默认值必填number[]undefined否例如在 MapExample 等需要同时处理地图拖动与面板拖拽的场景中合理设置activeOffsetY/failOffsetY可以避免手势冲突。gestureEventsHandlersHook自定义钩子用于提供 Pan 手势事件处理器实现对手势处理的深度定制。类型默认值必填GestureEventsHandlersHookTypeuseGestureEventsHandlersDefault否⚠️ 注意这是一个实验性特性钩子签名可能在非主版本更新中发生变化。默认实现位于 useGestureEventsHandlersDefault.tsx它内部通过 UI 线程的 worklet 处理拖拽、吸附点匹配snapPoint.ts与越界阻尼clamp.ts等逻辑。动画节点与回调实时监听面板状态通过传入共享值节点你可以在 UI 线程实时感知面板的索引与位置通过回调则可以在 JS 线程感知状态变化。animatedIndex内部索引节点的回调共享值。类型默认值必填Animated.SharedValuenumbernull否animatedPosition内部位置节点的回调共享值。类型默认值必填Animated.SharedValuenumbernull否传入后你可以在任意 worklet 中通过.value读取实时的索引与位置像素偏移用于驱动例如背景遮罩透明度、内容缩放等联动动画。onChange面板位置吸附点索引发生变化时的回调。type onChange (index: number) void;类型默认值必填functionnull否在当前源码 types.d.ts 中签名扩展为(index: number, position: number, type: SNAP_POINT_TYPE) void即还能拿到具体像素位置与吸附点类型SNAP_POINT_TYPE中的PROVIDED/DYNAMIC见 constants.ts。onAnimate面板即将动画到新位置时的回调。type onAnimate (fromIndex: number, toIndex: number) void;类型默认值必填functionnull否组件插槽自定义手柄、遮罩、背景与页脚面板的每个视觉层都提供了插槽组件你可以注入自定义实现实现完全自定义的视觉与交互。handleComponent放置在手柄位置的组件接收BottomSheetHandleProps。类型默认值必填React.FCBottomSheetHandlePropsBottomSheetHandle否不传时使用内置的 BottomSheetHandle。自定义手柄的完整指南见 custom-handle.mdx示例可参考 CustomHandleExample.tsx。backdropComponent放置在手柄背后的遮罩组件接收BottomSheetBackgroundProps。默认是null不显示遮罩但库内置了BottomSheetBackdrop实现需要你手动传入才会生效。类型默认值必填React.FCBottomSheetBackgroundPropsnull否配套指南见 custom-backdrop.mdx内置实现位于 BottomSheetBackdrop.tsx。backgroundComponent放置为面板背景的组件即面板本身的底板如圆角卡片接收BottomSheetBackgroundProps。类型默认值必填React.FCBottomSheetBackgroundPropsBottomSheetBackground否不传时使用内置的 BottomSheetBackground自定义指南见 custom-background.mdx。footerComponent放置为面板页脚的组件接收BottomSheetFooterProps。类型默认值必填React.FCBottomSheetFooterPropsundefined否页脚高度同样参与动态吸附点计算见上文useAnimatedSnapPoints中footerHeight的参与。官方示例见 FooterExample.tsx 与 custom-footer.mdx。children面板内容可以是Scrollable节点或普通 React 节点。类型默认值必填() React.ReactNode | React.ReactNode[] | React.ReactNodenull是需要强调的是滚动内容请使用库提供的 BottomSheetScrollView、BottomSheetFlatList、BottomSheetSectionList、BottomSheetVirtualizedList 或 BottomSheetFlashList它们与拖拽手势的协调细节见 scrollables.md。默认值速查与开发期校验为便于快速排查问题下表汇总了各 Props 的默认值定义于 constants.tsv4 文档口径Prop默认值index0overDragResistanceFactor2.5detachedfalseenableContentPanningGesturetrueenableHandlePanningGesturetrueenableOverDragtrueenablePanDownToClosefalseenableDynamicSizingfalsev4 文档当前源码为 trueanimateOnMounttruehandleHeight24containerHeight0未提供时内部自动测量topInset / bottomInset0maxDynamicContentSize容器高度keyboardBehaviorinteractivekeyboardBlurBehaviornoneandroid_keyboardInputModeadjustPanwaitFor / simultaneousHandlers[]backdropComponentnull同时开发模式下 usePropsValidator 会对以下规则做运行时校验不满足会抛出invariant错误snapPoints至少提供一个有效点除非开启enableDynamicSizing每个吸附点必须为正数不允许用0或负数模拟关闭应改用enablePanDownToCloseindex类型必须为number且取值范围为-1到snapPoints.length - 1topInset、bottomInset类型必须为number。组合实战键盘、动态尺寸与自定义样式的完整配置将上述参数组合起来可以覆盖绝大多数真实业务场景。以下是一个包含键盘处理、动态内容尺寸、自定义背景与遮罩、以及回调监听的完整示例import React, { useCallback, useMemo } from react; import { View, Text, TextInput, StyleSheet } from react-native; import BottomSheet, { BottomSheetBackdrop, BottomSheetView, useBottomSheetSpringConfigs, } from gorhom/bottom-sheet; const App () { // 弹簧动画 const animationConfigs useBottomSheetSpringConfigs({ damping: 80, overshootClamping: true, restDisplacementThreshold: 0.1, restSpeedThreshold: 0.1, stiffness: 500, }); // 吸附点CONTENT_HEIGHT 占位符由动态尺寸钩子替换 const snapPoints useMemo(() [25%, CONTENT_HEIGHT, 90%], []); const handleSheetChanges useCallback((index: number) { console.log(sheet index changed:, index); }, []); return ( View style{styles.container} BottomSheet index{1} snapPoints{snapPoints} animationConfigs{animationConfigs} onChange{handleSheetChanges} enablePanDownToClose keyboardBehaviorinteractive keyboardBlurBehaviorrestore android_keyboardInputModeadjustResize backdropComponent{props ( BottomSheetBackdrop {...props} disappearsOnIndex{0} appearsOnIndex{1} / )} BottomSheetView style{styles.contentContainer} Text style{styles.title}动态尺寸 键盘交互/Text TextInput placeholder输入文字试试键盘行为 style{styles.input} / /BottomSheetView /BottomSheet /View ); }; const styles StyleSheet.create({ container: { flex: 1, padding: 24, backgroundColor: grey }, contentContainer: { flex: 1, alignItems: center, padding: 16 }, title: { fontSize: 18, fontWeight: 600, marginBottom: 16 }, input: { width: 100%, height: 44, borderWidth: 1, borderColor: #ccc, borderRadius: 8, paddingHorizontal: 12, }, }); export default App;上述配置中enablePanDownToClose支持下拉关闭keyboardBehaviorinteractive让键盘弹出时面板按键盘高度偏移keyboardBlurBehaviorrestore在键盘收起时恢复原位动态吸附点让面板高度跟随内容backdropComponent则提供了可随索引显隐的遮罩。若需进一步控制面板方法expand、collapse、close、forceClose、snapToIndex、snapToPosition可配合 methods.md 中描述的组件引用或useBottomSheet钩子使用。至此react-native-bottom-sheet 的BottomSheet组件 Props 已全部覆盖。实际开发中建议优先参考官方文档中对应的 usage.md 与 props.md并结合仓库源码types.d.ts、BottomSheet.tsx、constants.ts验证版本差异即可获得精确、可预期的配置行为。赞分享前端移动开发UI组件跨平台【免费下载链接】react-native-bottom-sheetA performant interactive bottom sheet with fully configurable options 项目地址https://gitcode.com/gh_mirrors/re/react-native-bottom-sheet点击查看免费下载相关推荐终极语音修复指南3分钟让模糊录音变清晰的神奇AI工具 终极语音修复指南3分钟让模糊录音变清晰的神奇AI工具 你是否曾为模糊不清的会议录音而烦恼或者珍贵的家庭录音因为年代久远而充满杂音别担心现在有了 V前端移动开发UI组件跨平台React Native Bottom Sheet 手势交互与动画实现React Native Bottom Sheet 手势交互与动画实现 本文深入探讨了React Native Bottom Sheet组件的手势交互系统与动画前端移动开发UI组件跨平台Plandex CLI 0.8.2 版本深度解读自定义 Help 体系、survey 交互模块与 OpenAI 端点/组织配置Plandex CLI 0.8.2 版本深度解读自定义 Help 体系、survey 交互模块与 OpenAI 端点/组织配置 本文围绕 Plandex CL前端移动开发UI组件跨平台上一篇最完整ONNX模型校验指南从哈希验证到数字签名实现下一篇Upterm历史记录管理Trie数据结构如何优化命令检索创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考