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 兼容的底部表单。

Android
iOS
Web
Included in Expo Go
Recommended version:
~58.0.15

一个 BottomSheet 组件,API 与 @gorhom/bottom-sheet 兼容。它封装了平台特定的 @expo/ui 原语:在 Android 上使用 Jetpack Compose ModalBottomSheet,在 iOS 上使用 SwiftUI BottomSheet。在网页上,它使用 HTML <dialog> 底部弹出层。

🌐 A BottomSheet component with an API compatible with @gorhom/bottom-sheet. It wraps the platform-specific @expo/ui primitives: Jetpack Compose ModalBottomSheet on Android and SwiftUI BottomSheet on iOS. On web, it uses an HTML <dialog> bottom sheet.

如果你需要对特定平台的样式、修饰符或布局行为进行底层控制,请直接使用原生原语。

🌐 If you need lower-level control over platform-specific styling, modifiers, or layout behavior, use the native primitives directly.

A bottom sheet presented over a dimmed screenA bottom sheet presented over a dimmed screen

安装

🌐 Installation

Terminal
- npx expo install @expo/ui
- yarn expo install @expo/ui
- pnpm expo install @expo/ui
- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

从 @gorhom/bottom-sheet 迁移

🌐 Migrating from @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。为了 API 兼容性,导出了一些相关的属性类型。

基本用法

🌐 Basic usage

BottomSheetExample.tsx
import { useRef } from 'react'; import { Button, Text, useColorScheme, View } from 'react-native'; import BottomSheet, { BottomSheetView } from '@expo/ui/community/bottom-sheet'; export default function BottomSheetExample() { const colorScheme = useColorScheme(); const ink = { color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }; const sheetRef = useRef<BottomSheet>(null); return ( <View style={{ flex: 1 }}> <Button title="打开" onPress={() => sheetRef.current?.snapToIndex(0)} /> <BottomSheet ref={sheetRef} snapPoints={['25%', '50%', '90%']} index={-1} onChange={index => { console.log('onChange', index); }} onClose={() => { console.log('closed'); }} enablePanDownToClose> <BottomSheetView style={{ flex: 1, padding: 24, alignItems: 'center' }}> <Text style={ink}>Sheet content</Text> </BottomSheetView> </BottomSheet> </View> ); }

BottomSheetModal

在从 @gorhom/bottom-sheet 模态 API 迁移时使用 BottomSheetModal。它默认关闭,通过 present() 打开。

🌐 Use BottomSheetModal when migrating from @gorhom/bottom-sheet modal APIs. It starts closed and opens with present().

BottomSheetModalExample.tsx
import { useRef } from 'react'; import { Button, Text, useColorScheme, View } from 'react-native'; import { BottomSheetModal, BottomSheetView } from '@expo/ui/community/bottom-sheet'; export default function BottomSheetModalExample() { const colorScheme = useColorScheme(); const ink = { color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }; const modalRef = useRef<BottomSheetModal>(null); return ( <View style={{ flex: 1 }}> <Button title="现在" onPress={() => modalRef.current?.present()} /> <BottomSheetModal ref={modalRef} snapPoints={['50%', '90%']} enablePanDownToClose> <BottomSheetView style={{ padding: 24 }}> <Text style={ink}>Modal content</Text> <Button title="退出" onPress={() => modalRef.current?.dismiss()} /> </BottomSheetView> </BottomSheetModal> </View> ); }

动态尺寸

🌐 Dynamic sizing

当未提供 snapPoints 时,工作表尺寸默认为适应其内容。使用 BottomSheetView 作为工作表内容封装器。

🌐 When snapPoints is not provided, the sheet sizes to fit its content by default. Use BottomSheetView for the sheet content wrapper.

DynamicBottomSheetExample.tsx
import { useRef } from 'react'; import { Button, Text, useColorScheme, View } from 'react-native'; import BottomSheet, { BottomSheetView } from '@expo/ui/community/bottom-sheet'; export default function DynamicBottomSheetExample() { const colorScheme = useColorScheme(); const ink = { color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }; const sheetRef = useRef<BottomSheet>(null); return ( <View style={{ flex: 1 }}> <Button title="打开" onPress={() => sheetRef.current?.present()} /> <BottomSheet ref={sheetRef} index={-1} enablePanDownToClose> <BottomSheetView style={{ padding: 24 }}> <Text style={ink}>This sheet sizes itself to its content.</Text> </BottomSheetView> </BottomSheet> </View> ); }

可滚动的 React Native 内容

🌐 Scrollable React Native content

底部弹出层支持 React Native 的 FlatList 或 ScrollView(或者像 FlashList 或 Legend List 这样的高性能列表)作为可滚动内容的子组件。使用 nestedScrollEnabled 时,列表会先滚动自己的内容。一旦滚动到顶部,剩余的拖动就会移动弹出层。BottomSheetFlatList 和 BottomSheetScrollView 也被导出以兼容 @gorhom/bottom-sheet,但它们只是 React Native 组件的简单重新导出。

🌐 The bottom sheet supports a React Native FlatList or ScrollView (or a high-performance list like FlashList or Legend List) as a child for scrollable content. With nestedScrollEnabled, the list scrolls its own content first. Once it reaches the top edge, the remaining drag moves the sheet. BottomSheetFlatList and BottomSheetScrollView are also exported for @gorhom/bottom-sheet compatibility, but they are plain re-exports of the React Native components.

BottomSheetScrollableExample.tsx
import { useRef } from 'react'; import { Button, FlatList, Text, useColorScheme, View } from 'react-native'; import BottomSheet from '@expo/ui/community/bottom-sheet'; const DATA = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`); export default function BottomSheetScrollableExample() { const colorScheme = useColorScheme(); const ink = { color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }; const sheetRef = useRef<BottomSheet>(null); return ( <View style={{ flex: 1 }}> <Button title="打开" onPress={() => sheetRef.current?.snapToIndex(0)} /> <BottomSheet ref={sheetRef} snapPoints={['50%', '90%']} index={-1} enablePanDownToClose> <FlatList nestedScrollEnabled style={{ flex: 1 }} data={DATA} keyExtractor={item => item} contentContainerStyle={{ padding: 24 }} renderItem={({ item }) => <Text style={{ ...ink, paddingVertical: 16 }}>{item}</Text>} /> </BottomSheet> </View> ); }

平台行为

🌐 Platform behavior

@gorhom/bottom-sheet 会以内联方式显示在其父视图的底部。这个组件在 Android 和 iOS 上使用原生模态呈现,在网页上使用 HTML <dialog>。

这种差异是故意的。@gorhom/bottom-sheet 通过 react-native-gesture-handler 和 react-native-reanimated 拥有手势和动画层,而 @expo/ui/community/bottom-sheet 则将这些行为委托给 Jetpack Compose、SwiftUI 以及网页上的 HTML <dialog>。因此,这个组件最适合用于模态底部面板流程,包括使用 BottomSheet API 而不是 BottomSheetModal 的调用点。

🌐 This difference is intentional. @gorhom/bottom-sheet owns the gesture and animation layer through react-native-gesture-handler and react-native-reanimated, while @expo/ui/community/bottom-sheet delegates those behaviors to Jetpack Compose, SwiftUI, and an HTML <dialog> on web. As a result, this component is best suited for modal bottom sheet flows, including callsites that use the BottomSheet API rather than BottomSheetModal.

功能AndroidiOS网页
展示方式Jetpack Compose 模态底部弹出SwiftUI 弹窗HTML <dialog> 底部弹出
吸附点对应部分和展开状态支持提供的吸附点支持提供的吸附点
无 snapPoints适应内容适应内容适应内容
下滑关闭还支持返回键和遮罩点击关闭也支持背景点击关闭支持叠加层点击、Esc 键和下滑关闭
持久性内联预览不支持不支持不支持

支持的导出

🌐 Supported exports

导出支持备注
BottomSheet在 Android 和 iOS 上为模态,在网页上为 HTML 对话框
BottomSheetModal初始关闭,使用 present() 打开
BottomSheetModalProvider直接呈现子元素以兼容性
BottomSheetView封装表格内容
BottomSheetScrollViewReact Native ScrollView 的重新导出
BottomSheetFlatListReact Native FlatList 的重新导出
BottomSheetSectionListReact Native SectionList 的重新导出
BottomSheetTextInputReact Native TextInput 的重新导出
useBottomSheet从上下文返回工作表引用方法
BottomSheetBackdrop原生表单或 HTML 对话框处理背景
BottomSheetHandle本地表单或 HTML 对话框处理拖动指示器
BottomSheetFooter在此实现中没有对应项

兼容性说明

🌐 Compatibility notes

  • snapPoints、index、onChange、onClose、onDismiss、enablePanDownToClose 和 enableDynamicSizing 受支持。
  • handleComponent={null} 会隐藏原生或网页的拖拽指示器。在原生平台上,自定义的拖拽句柄组件不会被渲染。
  • backgroundStyle 在网页上完全适用。在 Android 上,backgroundColor 用于原生容器颜色。在 iOS 上,使用系统表单背景。
  • 动画、过度拖动、内容平移、句柄平移、键盘行为、自定义背景布、自定义背景、自定义页脚、动画值和分离属性被接受以兼容 API,但不会改变行为。

应用接口

🌐 API

import BottomSheet from '@expo/ui/community/bottom-sheet';

No API data file found, sorry!