This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

一个 BottomSheet 组件，其 API 与 @gorhom/bottom-sheet 兼容。它封装了特定平台的 @expo/ui 原语：在 Android 上使用 Jetpack Compose ModalBottomSheet，在 iOS 上使用 SwiftUI BottomSheet。在 Web 上，它使用 vaul 抽屉。

🌐 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 a vaul drawer.

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

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

Android

iOS

安装

🌐 Installation

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>
  );
}

Android

iOS

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>
  );
}

Android

iOS

动态尺寸

🌐 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>
  );
}

Android

iOS

平台行为

🌐 Platform behavior

@gorhom/bottom-sheet 在其父视图的底部以内联方式呈现。该组件在 Android 和 iOS 上使用原生模态显示，在网页上使用抽屉覆盖显示。

这种差异是刻意为之的。@gorhom/bottom-sheet 通过 react-native-gesture-handler 和 react-native-reanimated 拥有手势和动画层，而 @expo/ui/community/bottom-sheet 则将这些行为委托给 Jetpack Compose、SwiftUI 和网页抽屉原语。因此，该组件最适合用于模态底部表单流程，包括使用 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 the web drawer primitive. As a result, this component is best suited for modal bottom sheet flows, including callsites that use the BottomSheet API rather than BottomSheetModal.

支持的导出

🌐 Supported exports

兼容性说明

🌐 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';

Components

Hooks

Types