react-native-bottom-sheet是一个RN三方库,是一个高性能的交互式底片组件,适用于React Native应用。它具备完全可配置的特性,并且由Reanimated 2提供技术支持,提供了丰富的快照点。这个组件最初是克隆自一个类似的库,但随后进行了完全重写,以增加其他功能并简化使用方法。 react-native-bottom-sheet的特点包括流畅的互动和捕捉动画,支持FlatList、SectionList、ScrollView和View滚动交互。这使得它在各种滚动场景下都能提供出色的用户体验。
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 16 天前 | ||
| 1 个月前 | ||
| 4 年前 | ||
| 3 年前 | ||
| 5 年前 | ||
| 5 年前 | ||
| 5 年前 | ||
| 5 年前 | ||
| 2 个月前 | ||
| 5 年前 | ||
| 2 个月前 | ||
| 5 年前 | ||
| 5 年前 | ||
| 2 年前 | ||
| 16 天前 | ||
| 4 年前 | ||
| 2 个月前 | ||
| 4 年前 | ||
| 5 年前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 1 个月前 | ||
| 1 个月前 | ||
| 5 年前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 5 年前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 4 年前 | ||
| 4 年前 | ||
| 16 天前 | ||
| 5 年前 | ||
| 5 年前 |
文档模板:v0.4.2
@gorhom/bottom-sheet
本项目基于 react-native-bottom-sheet 开发。
该第三方库的仓库已迁移至 Gitcode,且支持直接从 npm 下载,新的包名为:@react-native-ohos/bottom-sheet 版本所属关系如下:
| 三方库名称 | 三方库版本(npm地址) | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 |
|---|---|---|---|---|---|---|---|
| @react-native-ohos/bottom-sheet | ~ 5.2.0 | Gitcode Releases | 0.82.* | 否 | API12+ | 5.2.14 | sig |
| @react-native-ohos/bottom-sheet | ~ 5.1.7 | Gitcode Releases | 0.77.* | 否 | API12+ | 5.1.6 | br_rnoh0.77 |
| @react-native-ohos/bottom-sheet | ~ 4.6.5 | Gitcode Releases | 0.72.* | 否 | API12+ | 4.6.1 | br_rnoh0.72 |
| @react-native-oh-tpl/bottom-sheet | <= 4.6.4-0.0.2@deprecated | Github Releases(deprecated) | 0.72.* | 否 | API12+ | 4.6.1 | sig |
简介
react-native-bottom-sheet 是一个高性能的交互式底部抽屉组件,提供完全可配置的选项,支持多种吸附点、手势交互、键盘适配等特性 🚀
下载安装
进入到工程目录并输入以下命令:
npm
npm install @react-native-ohos/bottom-sheet
yarn
yarn add @react-native-ohos/bottom-sheet
Link
本库为纯 JS 库,无需 Autolink 或 ManualLink 配置,安装后即可直接使用。
本库鸿蒙侧运行依赖 `react-native-reanimated` 和 `react-native-gesture-handler` 的原生端代码,如已在鸿蒙工程中引入过这两个库,则无需再次引入,可跳过本章节。如未引入请参照 [react-native-reanimated 文档](https://gitcode.com/CPF-RN/usage-docs/tree/master/zh-cn/react-native-reanimated.md)、[react-native-gesture-handler 文档](https://gitcode.com/CPF-RN/usage-docs/tree/master/zh-cn/react-native-gesture-handler.md) 进行引入。
运行
安装完成后,构建并运行项目即可使用。
约束与限制
兼容性
本文档内容基于以下版本验证通过:
- RNOH: 0.82.1; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM: 6.0.0.120 SP7;
权限要求
无特殊权限需求。
使用示例
下面的代码展示了这个库的基本使用场景:
使用时 import 的库名不变。
// bottom-sheet组件
import React, { useCallback, useRef, useMemo } from "react";
import { StyleSheet, View, Text, Button } from "react-native";
import BottomSheet, { BottomSheetView } from "@gorhom/bottom-sheet";
import { GestureHandlerRootView } from 'react-native-gesture-handler';
const App = () => {
// hooks
const sheetRef = useRef<BottomSheet>(null);
// variables
const snapPoints = useMemo(() => ["25%", "50%", "90%"], []);
// callbacks
const handleSheetChange = useCallback((index) => {
console.log("handleSheetChange", index);
}, []);
const handleSnapPress = useCallback((index) => {
sheetRef.current?.snapToIndex(index);
}, []);
const handleClosePress = useCallback(() => {
sheetRef.current?.close();
}, []);
// render
return (
<GestureHandlerRootView style={styles.container}>
<Button title="Snap To 90%" onPress={() => handleSnapPress(2)} />
<Button title="Snap To 50%" onPress={() => handleSnapPress(1)} />
<Button title="Snap To 25%" onPress={() => handleSnapPress(0)} />
<Button title="Close" onPress={() => handleClosePress()} />
<BottomSheet
ref={sheetRef}
snapPoints={snapPoints}
onChange={handleSheetChange}
>
<BottomSheetView>
<Text>Awesome 🔥</Text>
</BottomSheetView>
</BottomSheet>
</GestureHandlerRootView>
);
};
const styles = StyleSheet.create({
container: {
flex: 1,
paddingTop: 200,
},
});
export default App;
// bottom-sheet-modal组件
import React, { useCallback, useMemo, useRef } from 'react';
import { View, Text, StyleSheet, Button } from 'react-native';
import {
BottomSheetModal,
BottomSheetView,
BottomSheetModalProvider,
} from '@gorhom/bottom-sheet';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
const App = () => {
// ref
const bottomSheetModalRef = useRef<BottomSheetModal>(null);
// variables
const snapPoints = useMemo(() => ['25%', '50%'], []);
// callbacks
const handlePresentModalPress = useCallback(() => {
bottomSheetModalRef.current?.present();
}, []);
const handleSheetChanges = useCallback((index: number) => {
console.log('handleSheetChanges', index);
}, []);
// renders
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<BottomSheetModalProvider>
<View style={styles.container}>
<Button
onPress={handlePresentModalPress}
title="Present Modal"
color="black"
/>
<BottomSheetModal
ref={bottomSheetModalRef}
index={1}
snapPoints={snapPoints}
onChange={handleSheetChanges}
>
<BottomSheetView style={styles.contentContainer}>
<Text>Awesome 🎉</Text>
</BottomSheetView>
</BottomSheetModal>
</View>
</BottomSheetModalProvider>
</GestureHandlerRootView>
);
};
const styles = StyleSheet.create({
container: {
flex: 1,
padding: 24,
justifyContent: 'center',
backgroundColor: 'grey',
},
contentContainer: {
flex: 1,
alignItems: 'center',
},
});
export default App;
使用说明
基本使用 - BottomSheet 组件
import BottomSheet, { BottomSheetView } from '@gorhom/bottom-sheet';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
// 创建吸附点
const snapPoints = ['25%', '50%', '90%'];
// 在 GestureHandlerRootView 内使用
<GestureHandlerRootView style={{ flex: 1 }}>
<BottomSheet snapPoints={snapPoints}>
<BottomSheetView>
<Text>Content</Text>
</BottomSheetView>
</BottomSheet>
</GestureHandlerRootView>
Modal 模式
import { BottomSheetModal, BottomSheetView, BottomSheetModalProvider } from '@gorhom/bottom-sheet';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
// 需要包裹 BottomSheetModalProvider
<GestureHandlerRootView style={{ flex: 1 }}>
<BottomSheetModalProvider>
<BottomSheetModal ref={modalRef} snapPoints={['50%']}>
<BottomSheetView>
<Text>Modal Content</Text>
</BottomSheetView>
</BottomSheetModal>
</BottomSheetModalProvider>
</GestureHandlerRootView>
// 通过 ref 控制显示/隐藏
modalRef.current?.present();
modalRef.current?.dismiss();
手势与动画控制
const sheetRef = useRef<BottomSheet>(null);
// 吸附到指定索引
sheetRef.current?.snapToIndex(1);
// 关闭底部表单
sheetRef.current?.close();
// 展开到最大吸附点
sheetRef.current?.expand();
// 收起到最小吸附点
sheetRef.current?.collapse();
接口说明
"Platform"列表示该属性在原三方库上支持的平台。
"OpenHarmony Support"列为 yes 表示 OpenHarmony平台支持 该属性;no 则表示不支持;partially 表示部分支持。使用方法跨平台一致,效果对标 iOS 或 Android 的效果。
组件
| 名称 | 参数类型 | 必填 | 平台 | OpenHarmony平台支持 | 描述 |
|---|---|---|---|---|---|
| BottomSheet | BottomSheetProps | yes | Android / iOS | yes | 底部抽屉组件 |
| BottomSheetModal | BottomSheetModalProps | yes | Android / iOS | yes | 底部抽屉模态框组件 |
| BottomSheetView | ViewProps | No | Android / iOS | yes | 底部抽屉内容视图组件 |
| BottomSheetBackdrop | BottomSheetBackdropProps | No | Android / iOS | yes | 背景幕组件 |
| BottomSheetScrollView | ScrollViewProps | No | Android / iOS | yes | 可滚动视图组件 |
| BottomSheetFlatList | FlatListProps | No | Android / iOS | yes | 列表组件 |
| BottomSheetSectionList | SectionListProps | No | Android / iOS | yes | 分组列表组件 |
| BottomSheetTextInput | TextInputProps | No | Android / iOS | yes | 文本输入组件 |
| BottomSheetFlashList | BottomSheetFlashListProps | No | Android / iOS | yes | 高性能列表组件 |
| BottomSheetVirtualizedList | BottomSheetVirtualizedListProps | No | Android / iOS | yes | 虚拟化列表组件 |
| BottomSheetHandle | BottomSheetHandleProps | No | Android / iOS | yes | 手柄组件 |
| BottomSheetFooter | BottomSheetFooterProps | No | Android / iOS | yes | 页脚组件 |
| BottomSheetModalProvider | { children?: ReactNode } | No | Android / iOS | yes | 模态框 Provider,使用 BottomSheetModal 时必须包裹 |
| BottomSheetDraggableView | BottomSheetDraggableViewProps | No | Android / iOS | yes | 可拖拽视图组件 |
属性
Bottom Sheet
Configuration
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| index | 初始吸附索引。你也可以提供 -1 来使底部表单初始处于关闭状态。 | number | 0 | No | Android / iOS | Yes |
| snapPoints | 底部表单吸附的点,点应从底部到顶部排序。接受数字、字符串或混合类型的数组。 | Array<number|string>| SharedValue<Array<string | number>> | - | Yes | Android / iOS | Yes |
| overDragResistanceFactor | 定义在过度拖动时必须如何强制停止表单。 | number | 2.5 | No | Android / iOS | Yes |
| detached | 定义底部表单是否附着在底部。 | boolean | false | No | Android / iOS | Yes |
| enableContentPanningGesture | 启用内容拖动手势交互。 | boolean | true | No | Android / iOS | Yes |
| enableHandlePanningGesture | 启用手柄拖动手势交互。 | boolean | true | No | Android / iOS | Yes |
| enableOverDrag | 启用表单的过度拖动。 | boolean | true | No | Android / iOS | Yes |
| enablePanDownToClose | 启用向下拖动手势以关闭表单。 | boolean | false | No | Android / iOS | Yes |
| enableDynamicSizing | 为内容视图和可滚动内容尺寸启用动态调整大小。 | boolean | false | No | Android / iOS | Yes |
| animateOnMount | 这将初始时以关闭状态挂载表单,当挂载并计算布局后,它将吸附到初始吸附点索引。 | boolean | false | No | Android / iOS | Yes |
| overrideReduceMotion5.1.7+ | 覆盖用户的减少动画辅助功能设置。 | ReduceMotion.System | ReduceMotion.Always | ReduceMotion.Never | - | No | Android / iOS | Yes |
Styles
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| style | 应用于表单容器的视图样式,也可以是 AnimatedStyle。这有助于向表单添加阴影。 | ViewStyle | AnimatedStyle | - | No | Android / iOS | Yes |
| containerStyle | 应用于容器的视图样式。 | ViewStyle | - | No | Android / iOS | Yes |
| backgroundStyle | 应用于背景组件的视图样式。 | ViewStyle | - | No | Android / iOS | Yes |
| handleStyle | 应用于手柄指示器组件的视图样式。 | ViewStyle | - | No | Android / iOS | Yes |
| handleIndicatorStyle | 应用于手柄指示器组件的视图样式。 | ViewStyle | - | No | Android / iOS | Yes |
Layout Configuration
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| containerHeight | 容器高度有助于计算内部表单布局。如果未提供 containerHeight,库将在内部计算它,但这会导致额外的重新渲染。5.2.0版本已废弃,请使用 containerLayoutState 替代。 | number | SharedValue<number> | - | No | Android / iOS | Yes |
| containerOffset | 容器偏移量有助于准确检测容器偏移量。5.2.0版本已废弃,请使用 containerLayoutState 替代。 | SharedValue<Required<Insets>> | - | No | Android / iOS | Yes |
| containerLayoutState5.2.0+ | 容器布局状态对象,用于计算容器高度与偏移量,合并了原 containerHeight 与 containerOffset。如未提供,库将使用默认的容器布局状态。 | SharedValue<ContainerLayoutState> | - | No | Android / iOS | Yes |
| topInset | 要添加到底部表单容器的顶部插入距离,通常来自 @react-navigation/stack 的钩子 useHeaderHeight 或来自 react-native-safe-area-context 的钩子 useSafeArea。 | number | 0 | No | Android / iOS | Yes |
| bottomInset | 要添加到底部表单容器的底部插入距离。 | number | 0 | No | Android / iOS | Yes |
| maxDynamicContentSize | 最大动态内容尺寸高度,用于限制底部表单高度不超过提供的尺寸。 | number | - | No | Android / iOS | Yes |
Keyboard Configuration
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| keyboardBehavior | 定义键盘出现行为;extend: 将表单扩展到其最大吸附点;fillParent: 将表单扩展以填充父视图;interactive: 根据键盘大小偏移表单。 |
'extend' | 'fillParent' | 'interactive' | 'interactive' | No | Android / iOS | Yes |
| keyboardBlurBehavior | 定义键盘失焦行为;none: 不执行任何操作;restore: 恢复表单位置 | 'none' | 'restore' | 'none' | No | Android / iOS | Yes |
| android_keyboardInputMode | 仅定义 Android 的键盘输入模式。 | 'adjustPan' | 'adjustResize' | 'adjustPan' | No | Android | No |
| enableBlurKeyboardOnGesture5.1.7+ | 当用户开始拖动底部表单时启用模糊化键盘。 | boolean | false | No | Android / iOS | Yes |
Animation Configuration
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| animationConfigs | 动画配置。 | function | - | No | Android/iOS | Yes |
Gesture Configuration
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| waitFor | - | React.Ref | React.Ref[] | - | No | Android/iOS | Yes |
| simultaneousHandlers | - | React.Ref | React.Ref[] | - | No | Android/iOS | Yes |
| activeOffsetX | - | number[] | - | No | Android/iOS | Yes |
| activeOffsetY | - | number[] | - | No | Android/iOS | Yes |
| failOffsetX | - | number[] | - | No | Android/iOS | Yes |
| failOffsetY | - | number[] | - | No | Android/iOS | Yes |
| gestureEventsHandlersHook | 用于提供拖动手势事件处理程序的自定义钩子,这将允许对拖动手势进行高级和自定义处理。 | GestureEventsHandlersHookType | - | No | Android/iOS | Yes |
Animated Nodes
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| animatedIndex | 用作内部索引节点回调的动画值。 | Animated.SharedValue<number> | - | No | Android/iOS | Yes |
| animatedPosition | 用作内部位置节点回调的动画值。 | Animated.SharedValue<number> | - | No | Android/iOS | Yes |
Callbacks
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| onChange | 当表单位置改变时的回调。 | function | - | No | Android/iOS | Yes |
| onAnimate | 当表单即将动画到新位置时的回调。 | function | - | No | Android/iOS | Yes |
| onClose | 当表单关闭时的回调。 | function | - | No | Android/iOS | Yes |
Components
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| handleComponent | 作为表单手柄放置的组件。 | React.FC<BottomSheetHandleProps> | - | No | Android/iOS | Yes |
| backdropComponent | 作为表单背景幕放置的组件,默认设置为 null,但库也提供了背景幕的默认实现 BottomSheetBackdrop,不过你需要手动提供它。 | React.FC<BottomSheetBackgroundProps> | - | No | Android/iOS | Yes |
| backgroundComponent | 作为表单背景放置的组件。 | React.FC<BottomSheetBackgroundProps> | - | No | Android/iOS | Yes |
| footerComponent | 作为表单页脚放置的组件。 | React.FC<BottomSheetFooterProps> | - | No | Android/iOS | Yes |
| children | 作为表单内容放置的可滚动节点或 React 节点。 | () => React.ReactNode | React.ReactNode[] | React.ReactNode | - | No | Android/iOS | Yes |
Bottom Sheet Modal
底部表单模态框继承了所有 [底部表单属性](#bottom-sheet),除了 containerHeight 和 onClose,并且它还引入了自己的属性
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| name | 模态框名称,用于后续识别模态框。 | string | - | No | Android/iOS | Yes |
| stackBehavior | 定义模态框挂载时的堆栈行为。'switch' 为最小化当前模态框后挂载新的模态框。 | 'push' | 'switch' | 'replace' | 'switch' | No | Android/iOS | Yes |
| enableDismissOnClose | 在模态框关闭时将其解除,这将卸载模态框。 | boolean | true | No | Android/iOS | Yes |
| onDismiss | 当模态框被解除(卸载)时的回调。 | function | - | No | Android/iOS | Yes |
| containerComponent | 作为底部表单容器放置的组件,当使用来自 React Native Screens 的 FullWindowOverlay 时,这用于将底部表单放置在应用程序的最顶层。 | React.ComponentType | - | No | Android/iOS | Yes |
BottomSheetBackdrop
BottomSheetBackdrop 是库提供的默认背景幕实现,通过 BottomSheet 的 `backdropComponent` 属性传入。自定义背景幕组件需实现 `BottomSheetBackdropProps` 接口。
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| animatedIndex | 当前表单吸附索引(由 BottomSheet 自动注入) | SharedValue<number> | - | No | Android/iOS | Yes |
| animatedPosition | 当前表单位置(由 BottomSheet 自动注入) | SharedValue<number> | - | No | Android/iOS | Yes |
| opacity | 背景幕不透明度 | number | 0.5 | No | Android/iOS | Yes |
| appearsOnIndex | 背景幕出现的吸附点索引 | number | 1 | No | Android/iOS | Yes |
| disappearsOnIndex | 背景幕消失的吸附点索引 | number | 0 | No | Android/iOS | Yes |
| enableTouchThrough | 启用触摸穿透背景幕 | boolean | false | No | Android/iOS | Yes |
| pressBehavior | 按压背景幕的行为:'none' 不执行操作;'close' 关闭表单;'collapse' 收起表单;数字值表示吸附到指定索引 | 'none' | 'close' | 'collapse' | number | 'close' | No | Android/iOS | Yes |
| onPress | 按压背景幕时的回调 | function | - | No | Android/iOS | Yes |
| style | 应用于背景幕的视图样式 | ViewStyle | - | No | Android/iOS | Yes |
| children | 背景幕子组件 | ReactNode | ReactNode[] | - | No | Android/iOS | Yes |
BottomSheetHandle
BottomSheetHandle 是库提供的默认手柄实现,通过 BottomSheet 的 `handleComponent` 属性传入。自定义手柄组件需实现 `BottomSheetHandleProps` 接口。
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| animatedIndex | 当前表单吸附索引(由 BottomSheet 自动注入) | SharedValue<number> | - | No | Android/iOS | Yes |
| animatedPosition | 当前表单位置(由 BottomSheet 自动注入) | SharedValue<number> | - | No | Android/iOS | Yes |
| style | 应用于手柄容器的视图样式 | ViewStyle | - | No | Android/iOS | Yes |
| indicatorStyle | 应用于手柄指示器的视图样式 | ViewStyle | - | No | Android/iOS | Yes |
| children | 手柄指示器下方的内容 | ReactNode | ReactNode[] | - | No | Android/iOS | Yes |
BottomSheetFooter
BottomSheetFooter 是库提供的默认页脚实现,通过 BottomSheet 的 `footerComponent` 属性传入。自定义页脚组件需实现 `BottomSheetFooterProps` 接口。
| 名称 | 描述 | 类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|---|---|
| animatedFooterPosition | 页脚的动画位置(由 BottomSheet 自动注入),用于实现页脚跟随表单动画 | SharedValue<number> | - | No | Android/iOS | Yes |
| bottomInset | 页脚底部安全区域距离,通常来自 react-native-safe-area-context | number | 0 | No | Android/iOS | Yes |
| style | 页脚容器样式 | ViewStyle | - | No | Android/iOS | Yes |
| children | 页脚子组件 | ReactNode | ReactNode[] | - | No | Android/iOS | Yes |
Hooks
useBottomSheet
获取当前 BottomSheet 实例的方法和状态,必须在 <BottomSheet> 内部使用。
返回值:
| 名称 | 描述 | 类型 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|
| snapToIndex | 吸附到指定的吸附点索引 | (index: number, animationConfigs?) => void | Android/iOS | Yes |
| snapToPosition | 吸附到指定位置 | (position: number | string, animationConfigs?) => void | Android/iOS | Yes |
| expand | 展开到最大吸附点 | (animationConfigs?) => void | Android/iOS | Yes |
| collapse | 收起到最小吸附点 | (animationConfigs?) => void | Android/iOS | Yes |
| close | 关闭底部表单 | (animationConfigs?) => void | Android/iOS | Yes |
| forceClose | 强制关闭底部表单 | (animationConfigs?) => void | Android/iOS | Yes |
| animatedIndex | 当前表单吸附索引 | SharedValue<number> | Android/iOS | Yes |
| animatedPosition | 当前表单位置 | SharedValue<number> | Android/iOS | Yes |
useBottomSheetModal
获取当前 BottomSheetModal 的方法,必须在 <BottomSheetModalProvider> 内部使用。
返回值:
| 名称 | 描述 | 类型 | 平台 | HarmonyOS平台支持 |
|---|---|---|---|---|
| dismiss | 关闭指定模态框,传入 key 关闭指定模态框,不传则关闭最顶层模态框,返回是否成功关闭 | (key?: string) => boolean | Android/iOS | Yes |
| dismissAll | 关闭所有模态框 | () => void | Android/iOS | Yes |
useBottomSheetSpringConfigs
生成弹簧动画配置,返回值传给 BottomSheet 的 animationConfigs 属性或命令式方法的 animationConfigs 参数。
参数:
| 名称 | 描述 | 类型 | 必填 |
|---|---|---|---|
| configs | Reanimated 弹簧动画配置(不含 velocity) | Omit<WithSpringConfig, 'velocity'> | Yes |
返回值: 传入的 configs 对象原样返回,类型为 Omit<WithSpringConfig, 'velocity'>。
useBottomSheetTimingConfigs
生成时间动画配置,返回值传给 BottomSheet 的 animationConfigs 属性或命令式方法的 animationConfigs 参数。
参数:
| 名称 | 描述 | 类型 | 默认值 | 必填 |
|---|---|---|---|---|
| duration | 动画持续时间(毫秒) | number | 250 | No |
| easing | 动画缓动函数 | EasingFunction | EasingFunctionFactory | Easing.out(Easing.exp) | No |
| reduceMotion | 减少动画模式 | ReduceMotion | - | No |
返回值: { duration: number, easing: EasingFunction | EasingFunctionFactory, reduceMotion?: ReduceMotion },未提供的字段使用默认值。
工具函数
createBottomSheetScrollableComponent
创建自定义可滚动组件,用于将第三方列表组件(如 FlashList、LegendList 等)集成到 BottomSheet 中。
签名: createBottomSheetScrollableComponent<T, P>(type, ScrollableComponent)
参数:
| 名称 | 描述 | 类型 | 必填 |
|---|---|---|---|
| type | 可滚动组件类型 | 'UNDETERMINED' | 'VIEW' | 'FLATLIST' | 'SCROLLVIEW' | 'SECTIONLIST' | 'VIRTUALIZEDLIST' | Yes |
| ScrollableComponent | Reanimated Animated 包装后的滚动组件 | any | Yes |
返回值: 一个 forwardRef 包装的 React 组件,支持 BottomSheet 的滚动协调和手势交互。
使用示例:
import { createBottomSheetScrollableComponent } from '@gorhom/bottom-sheet';
import Animated, { createAnimatedComponent } from 'react-native-reanimated';
import FlashList from '@shopify/flash-list';
const AnimatedFlashList = createAnimatedComponent(FlashList);
const BottomSheetFlashList = createBottomSheetScrollableComponent(
'FLATLIST',
AnimatedFlashList
);
API
| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | OpenHarmony平台支持 | 描述 |
|---|---|---|---|---|---|---|---|
| snapToIndex | function | number | / | No | Android/iOS | Yes | 吸附到指定的吸附点索引。 |
| snapToPosition | function | number | string | / | No | Android/iOS | Yes | 吸附到指定的位置(不在预定义的吸附点中)。 |
| expand | function | / | / | No | Android/iOS | Yes | 展开到最大吸附点。 |
| collapse | function | / | / | No | Android/iOS | Yes | 收起到最小吸附点。 |
| close | function | / | / | No | Android/iOS | Yes | 关闭底部表单。 |
| forceClose | function | / | / | No | Android/iOS | Yes | 强制关闭底部表单,防止中断。 |
| present | function | data | / | No | Android/iOS | Yes | 挂载并显示模态框。(仅 BottomSheetModal) |
| dismiss | function | / | / | No | Android/iOS | Yes | 关闭并卸载模态框。(仅 BottomSheetModal) |
遗留问题
其他
无
目录结构
/react-native-bottom-sheet # 项目根目录
├── src # RN代码
│ ├─ index.ts # 入口文件
│ ├─ components # 组件目录
│ │ ├─ bottomSheet # BottomSheet 核心组件
│ │ ├─ bottomSheetBackdrop # 背景幕组件
│ │ ├─ bottomSheetHandle # 手柄组件
│ │ ├─ bottomSheetModal # 模态框组件
│ │ ├─ bottomSheetModalProvider # 模态框 Provider
│ │ ├─ bottomSheetScrollable # 可滚动组件(FlatList/ScrollView/SectionList 等)
│ │ ├─ bottomSheetView # 内容视图组件
│ │ ├─ bottomSheetFooter # 页脚组件
│ │ ├─ bottomSheetTextInput # 文本输入组件
│ │ └─ touchables # 触摸组件
│ ├─ contexts # 上下文目录
│ ├─ hooks # 自定义 Hooks
│ ├─ utilities # 工具函数
│ └─ constants.ts # 常量定义
├── lib # 编译输出目录
│ ├─ commonjs # CommonJS 模块
│ ├─ module # ES Module
│ └─ typescript # TypeScript 类型声明
├── example # 示例工程
│ └─ harmony # 鸿蒙示例工程
├── docs # 文档目录
├── mock.js # Mock 文件
├── package.json # 包配置
├── LICENSE # 开源协议
├── README_EN.md # 英文安装使用方法
├── README_ZH.md # 中文安装使用方法
└── README.md # 英文安装使用方法
贡献代码
使用过程中发现任何问题都可以提交 Issue,当然,也非常欢迎提交 PR。
开源协议
本项目基于 The MIT License (MIT) ,请自由地享受和参与开源。
项目介绍
react-native-bottom-sheet是一个RN三方库,是一个高性能的交互式底片组件,适用于React Native应用。它具备完全可配置的特性,并且由Reanimated 2提供技术支持,提供了丰富的快照点。这个组件最初是克隆自一个类似的库,但随后进行了完全重写,以增加其他功能并简化使用方法。 react-native-bottom-sheet的特点包括流畅的互动和捕捉动画,支持FlatList、SectionList、ScrollView和View滚动交互。这使得它在各种滚动场景下都能提供出色的用户体验。
定制我的领域