This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
BottomSheet
一个与 @gorhom/bottom-sheet 兼容的底部弹出面板。
一个与 @gorhom/bottom-sheet API 兼容的 BottomSheet 组件。它封装了平台特定的 @expo/ui 基元:Android 上使用 Jetpack Compose ModalBottomSheet,iOS 上使用 SwiftUI BottomSheet。在 web 上,它使用 vaul 抽屉。
如果你需要对平台特定的样式、修饰器或布局行为进行更底层的控制,请直接使用这些原生基元。
安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
从 @gorhom/bottom-sheet 迁移
-
将导入从:
import BottomSheet, { BottomSheetView } from '@gorhom/bottom-sheet';改为使用
@expo/ui/community/bottom-sheet:import BottomSheet, { BottomSheetView } from '@expo/ui/community/bottom-sheet'; -
此实现不需要来自
react-native-gesture-handler的GestureHandlerRootView。如果你的应用其他部分需要它,也可以保留不变。 -
不支持
BottomSheetBackdrop、BottomSheetHandle、BottomSheetFooter、BottomSheetDraggableView、BottomSheetVirtualizedList、BottomSheetFlashList、useBottomSheetModal、useBottomSheetSpringConfigs和useBottomSheetTimingConfigs等组件与 hook 导出。为了保持 API 兼容性,导出了一些相关的 prop 类型。
基本用法
BottomSheetModal
从 @gorhom/bottom-sheet 的 modal API 迁移时,请使用 BottomSheetModal。它默认处于关闭状态,并通过 present() 打开。
动态尺寸
当未提供 snapPoints 时,底部 sheet 默认会根据内容自适应尺寸。请使用 BottomSheetView 作为 sheet 内容容器。
可滚动的 React Native 内容
底部 sheet 支持将 React Native 的 FlatList 或 ScrollView(或者像 FlashList 或 Legend List 这样的高性能列表)作为子组件,用于可滚动内容。启用 nestedScrollEnabled 后,列表会先滚动自身内容;当滚动到顶部边缘后,剩余的拖拽会移动 sheet。为了兼容 @gorhom/bottom-sheet,BottomSheetFlatList 和 BottomSheetScrollView 也已导出,但它们只是对 React Native 组件的直接重新导出。
平台行为
@gorhom/bottom-sheet 会以内联方式渲染在其父视图底部。这个组件在 Android 和 iOS 上使用原生模态呈现,在 web 上使用抽屉覆盖层。
这种差异是有意为之。@gorhom/bottom-sheet 通过 react-native-gesture-handler 和 react-native-reanimated 控制手势与动画层,而 @expo/ui/community/bottom-sheet 将这些行为委托给 Jetpack Compose、SwiftUI 和 web 抽屉基元。因此,这个组件更适合用于模态底部 sheet 流程,包括使用 BottomSheet API 而不是 BottomSheetModal 的调用场景。
信息 在 iOS 上,如果要在另一个底部 sheet 上方显示一个底部 sheet,应将第二个
BottomSheet嵌套在第一个 sheet 的内容内部,而不是并列放置。这是底层 SwiftUIsheet修饰符的限制。更多信息请参阅 如何展示多个 sheet。
支持的导出
兼容性说明
- 支持
snapPoints、index、onChange、onClose、onDismiss、enablePanDownToClose和enableDynamicSizing。 handleComponent={null}会隐藏原生或 web 的拖拽指示器。自定义 handle 组件不会在原生平台上渲染。backgroundStyle在 web 上会完全生效。在 Android 上,backgroundColor用于原生容器颜色。在 iOS 上,使用系统 sheet 背景。- 动画、过度拖拽、内容拖动、handle 拖动、键盘行为、自定义背景遮罩、自定义背景、自定义页脚、动画值和 detached 属性会被接受以保持 API 兼容性,但不会改变行为。
API
import BottomSheet from '@expo/ui/community/bottom-sheet';
Components
Type: React.Element<BottomSheetProps>
Bottom sheet component. Defaults to index={0} and opens at the first snap point on mount.
Props for the BottomSheet component. API-compatible with @gorhom/bottom-sheet where native platform behavior allows.
boolean • Default: trueWhether the sheet should automatically size to fit its content.
boolean • Default: falseWhether the sheet can be dismissed by panning down.
number • Default: 0Initial snap point index. Set to -1 to start closed.
(index: number) => voidCalled when the current snap point index changes.
() => voidAlias for onClose for BottomSheetModal compatibility.
Type: React.Element<BottomSheetProps>
Modal variant of BottomSheet. Starts closed and opens with present().
Type: React.Element<{
children: React.ReactNode
}>
Provider for BottomSheetModal. It renders children directly for API compatibility.
Type: React.Element<BottomSheetViewProps>
A wrapper for content inside a BottomSheet.
boolean • Default: trueWhether the sheet should automatically size to fit its content.
boolean • Default: falseWhether the sheet can be dismissed by panning down.
number • Default: 0Initial snap point index. Set to -1 to start closed.
(index: number) => voidCalled when the current snap point index changes.
() => voidAlias for onClose for BottomSheetModal compatibility.
Hooks
Returns the imperative methods for the nearest BottomSheet.
BottomSheetMethods