This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

模态底部表单

一个 Jetpack Compose ModalBottomSheet 组件，用于从屏幕底部展示内容。

Android

Included in Expo Go

GitHub

npm

更新日志

有关跨平台用法，请参阅通用的 BottomSheet — 它会为每个平台渲染合适的原生组件。

Expo UI ModalBottomSheet 与官方 Jetpack Compose 底部抽屉 API 保持一致，并以从底部滑入的模态底部抽屉形式显示内容。

安装

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.

用法

基础底部抽屉

在卸载组件之前，使用 ref.hide() 通过动画以编程方式关闭底部抽屉。

BasicBottomSheetExample.tsx

import { useRef, useState } from 'react';
import {
  Host,
  ModalBottomSheet,
  Button,
  Column,
  Text,
} from '@expo/ui/jetpack-compose';
import type { ModalBottomSheetRef } from '@expo/ui/jetpack-compose';
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers';

export default function BasicBottomSheetExample() {
  const [visible, setVisible] = useState(false);
  const sheetRef = useRef<ModalBottomSheetRef>(null);

  const hideSheet = async () => {
    await sheetRef.current?.hide();
    setVisible(false);
  };

  return (
    <Host matchContents>
      <Button onClick={() => setVisible(true)}>
        <Text>打开抽屉</Text>
      </Button>
      {visible && (
        <ModalBottomSheet
          ref={sheetRef}
          onDismissRequest={() => setVisible(false)}>
          <Column
            verticalArrangement={{ spacedBy: 12 }}
            modifiers={[paddingAll(24)]}>
            <Text>Hello from bottom sheet!</Text>
            <Text>You can add more content here.</Text>
            <Button onClick={hideSheet}>
              <Text>关闭</Text>
            </Button>
          </Column>
        </ModalBottomSheet>
      )}
    </Host>
  );
}

跳过部分展开状态

设置 skipPartiallyExpanded 时，底部抽屉会直接以完全展开状态打开，而不会先停在半高位置。

SkipPartiallyExpandedExample.tsx

import { useRef, useState } from 'react';
import {
  Host,
  ModalBottomSheet,
  Button,
  Column,
  Text,
} from '@expo/ui/jetpack-compose';
import type { ModalBottomSheetRef } from '@expo/ui/jetpack-compose';
import {
  paddingAll,
  height,
} from '@expo/ui/jetpack-compose/modifiers';

export default function SkipPartiallyExpandedExample() {
  const [visible, setVisible] = useState(false);
  const sheetRef = useRef<ModalBottomSheetRef>(null);

  const hideSheet = async () => {
    await sheetRef.current?.hide();
    setVisible(false);
  };

  return (
    <Host matchContents>
      <Button onClick={() => setVisible(true)}>
        <Text>打开抽屉</Text>
      </Button>
      {visible && (
        <ModalBottomSheet
          ref={sheetRef}
          onDismissRequest={() => setVisible(false)}
          skipPartiallyExpanded>
          <Column
            verticalArrangement={{ spacedBy: 12 }}
            modifiers={[paddingAll(24), height(600)]}>
            <Text>
              此抽屉会跳过部分展开状态。
            </Text>
            <Text>
              它会直接以完全展开状态打开。
            </Text>
            <Button onClick={hideSheet}>
              <Text>关闭</Text>
            </Button>
          </Column>
        </ModalBottomSheet>
      )}
    </Host>
  );
}

初始完全展开状态

当 initialFullyExpanded 为 true 时，底部抽屉会在首次组合时直接以完全展开状态打开，同时仍保留可到达的部分展开状态。与 skipPartiallyExpanded 不同，用户仍然可以向下拖拽到部分展开状态。partialExpand() 方法也仍然可用。

InitialFullyExpandedExample.tsx

import { useRef, useState } from 'react';
import {
  Host,
  ModalBottomSheet,
  Button,
  Column,
  Text,
} from '@expo/ui/jetpack-compose';
import type { ModalBottomSheetRef } from '@expo/ui/jetpack-compose';
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers';

export default function InitialFullyExpandedExample() {
  const [visible, setVisible] = useState(false);
  const sheetRef = useRef<ModalBottomSheetRef>(null);

  const hideSheet = async () => {
    await sheetRef.current?.hide();
    setVisible(false);
  };

  return (
    <Host matchContents>
      <Button onClick={() => setVisible(true)}>
        <Text>打开抽屉</Text>
      </Button>
      {visible && (
        <ModalBottomSheet
          ref={sheetRef}
          onDismissRequest={() => setVisible(false)}
          initialFullyExpanded>
          <Column
            verticalArrangement={{ spacedBy: 12 }}
            modifiers={[paddingAll(24)]}>
            <Text>此抽屉以完全展开状态打开。</Text>
            <Text>
              你仍然可以向下拖拽，将其收起到部分展开状态。
            </Text>
            <Button
              onClick={() => sheetRef.current?.partialExpand()}>
              <Text>收起至部分展开</Text>
            </Button>
            <Button onClick={hideSheet}>
              <Text>关闭</Text>
            </Button>
          </Column>
        </ModalBottomSheet>
      )}
    </Host>
  );
}

自定义颜色

使用 containerColor、contentColor 和 scrimColor 自定义底部抽屉的外观。

CustomColorsExample.tsx

import { useRef, useState } from 'react';
import {
  Host,
  ModalBottomSheet,
  Button,
  Column,
  Text,
} from '@expo/ui/jetpack-compose';
import type { ModalBottomSheetRef } from '@expo/ui/jetpack-compose';
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers';

export default function CustomColorsExample() {
  const [visible, setVisible] = useState(false);
  const sheetRef = useRef<ModalBottomSheetRef>(null);

  const hideSheet = async () => {
    await sheetRef.current?.hide();
    setVisible(false);
  };

  return (
    <Host matchContents>
      <Button onClick={() => setVisible(true)}>
        <Text>打开彩色底部抽屉</Text>
      </Button>
      {visible && (
        <ModalBottomSheet
          ref={sheetRef}
          onDismissRequest={() => setVisible(false)}
          containerColor="#1a1a2e"
          contentColor="#e0e0e0"
          scrimColor="#6200EE80">
          <Column
            verticalArrangement={{ spacedBy: 12 }}
            modifiers={[paddingAll(24)]}>
            <Text>自定义样式的底部抽屉。</Text>
            <Text>深色容器和紫色遮罩层。</Text>
            <Button onClick={hideSheet}>
              <Text>关闭</Text>
            </Button>
          </Column>
        </ModalBottomSheet>
      )}
    </Host>
  );
}

自定义拖拽把手

使用 ModalBottomSheet.DragHandle 插槽提供自定义拖拽把手，或者设置 showDragHandle={false} 将其完全隐藏。

CustomDragHandleExample.tsx

import { useRef, useState } from 'react';
import {
  Host,
  ModalBottomSheet,
  Button,
  Column,
  Box,
  Text,
} from '@expo/ui/jetpack-compose';
import type { ModalBottomSheetRef } from '@expo/ui/jetpack-compose';
import {
  background,
  clip,
  fillMaxWidth,
  height,
  padding,
  Shapes,
  width,
} from '@expo/ui/jetpack-compose/modifiers';

export default function CustomDragHandleExample() {
  const [visible, setVisible] = useState(false);
  const sheetRef = useRef<ModalBottomSheetRef>(null);

  const hideSheet = async () => {
    await sheetRef.current?.hide();
    setVisible(false);
  };

  return (
    <Host matchContents>
      <Button onClick={() => setVisible(true)}>
        <Text>打开带自定义把手的底部表单</Text>
      </Button>
      {visible && (
        <ModalBottomSheet
          ref={sheetRef}
          onDismissRequest={() => setVisible(false)}>
          <ModalBottomSheet.DragHandle>
            <Column
              horizontalAlignment="center"
              modifiers={[fillMaxWidth(), padding(0, 12, 0, 8)]}>
              <Box
                modifiers={[
                  width(60),
                  height(6),
                  clip(Shapes.Circle),
                  background('#6200EE'),
                ]}
              />
            </Column>
          </ModalBottomSheet.DragHandle>
          <Column
            verticalArrangement={{ spacedBy: 12 }}
            modifiers={[padding(16, 16, 16, 16)]}>
            <Button onClick={hideSheet}>
              <Text>关闭</Text>
            </Button>
          </Column>
        </ModalBottomSheet>
      )}
    </Host>
  );
}

底部抽屉中的 React Native 内容

使用 RNHostView 将可交互的 React Native 视图嵌入 Compose 底部抽屉中。这样你就可以混合使用 Compose 布局与 Pressable 和 Text 等 RN 组件。

RNContentBottomSheetExample.tsx

import { useRef, useState } from 'react';
import {
  Host,
  ModalBottomSheet,
  Button,
  Column,
  RNHostView,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import type { ModalBottomSheetRef } from '@expo/ui/jetpack-compose';
import { padding } from '@expo/ui/jetpack-compose/modifiers';
import { Pressable, Text as RNText, View } from 'react-native';

export default function RNContentBottomSheetExample() {
  const colors = useMaterialColors();
  const [visible, setVisible] = useState(false);
  const sheetRef = useRef<ModalBottomSheetRef>(null);

  const hideSheet = async () => {
    await sheetRef.current?.hide();
    setVisible(false);
  };

  return (
    <Host matchContents>
      <Button onClick={() => setVisible(true)}>
        <Text>打开含 RN 内容的抽屉</Text>
      </Button>
      {visible && (
        <ModalBottomSheet
          ref={sheetRef}
          onDismissRequest={() => setVisible(false)}
          skipPartiallyExpanded={false}>
          <Column
            verticalArrangement={{ spacedBy: 16 }}
            modifiers={[padding(16, 16, 16, 16)]}>
            <Text>在底部抽屉中混合使用 Compose 和 RN</Text>
            <RNHostView>
              <View>
                <RNText
                  style={{
                    fontSize: 18,
                    fontWeight: 'bold',
                    marginBottom: 8,
                    color: colors.onSurface,
                  }}>
                  React Native 内容
                </RNText>
                <Pressable
                  style={{
                    backgroundColor: '#007AFF',
                    padding: 12,
                    borderRadius: 8,
                    alignItems: 'center',
                  }}
                  onPress={hideSheet}>
                  <RNText
                    style={{ color: 'white', fontWeight: '600' }}>
                    关闭
                  </RNText>
                </Pressable>
              </View>
            </RNHostView>
          </Column>
        </ModalBottomSheet>
      )}
    </Host>
  );
}

带弹性布局的 React Native 内容

不使用 matchContents 的 RNHostView 可以让 RN 视图填充底部抽屉中剩余的空间。将其与父级 Column 上固定的 height 修饰符结合使用，以控制底部抽屉尺寸。

FlexRNContentExample.tsx

import { useRef, useState } from 'react';
import {
  Host,
  ModalBottomSheet,
  Button,
  Column,
  RNHostView,
  Text,
} from '@expo/ui/jetpack-compose';
import type { ModalBottomSheetRef } from '@expo/ui/jetpack-compose';
import {
  height,
  padding,
} from '@expo/ui/jetpack-compose/modifiers';
import { Text as RNText, View } from 'react-native';

export default function FlexRNContentExample() {
  const [visible, setVisible] = useState(false);
  const sheetRef = useRef<ModalBottomSheetRef>(null);

  const hideSheet = async () => {
    await sheetRef.current?.hide();
    setVisible(false);
  };

  return (
    <Host matchContents>
      <Button onClick={() => setVisible(true)}>
        <Text>打开弹性内容抽屉</Text>
      </Button>
      {visible && (
        <ModalBottomSheet
          ref={sheetRef}
          onDismissRequest={() => setVisible(false)}
          skipPartiallyExpanded>
          <Column
            modifiers={[height(400), padding(16, 16, 16, 16)]}>
            <Text>带有 flex: 1 的 RN 视图</Text>
            <RNHostView>
              <View
                style={{
                  flex: 1,
                  backgroundColor: '#9B59B6',
                  borderRadius: 10,
                }}>
                <RNText
                  style={{
                    color: 'white',
                    fontSize: 18,
                    fontWeight: 'bold',
                    padding: 16,
                  }}>
                  React Native 内容（flex: 1）
                </RNText>
              </View>
            </RNHostView>
          </Column>
        </ModalBottomSheet>
      )}
    </Host>
  );
}

可滚动的 React Native 内容

使用 RNHostView 将可滚动的 React Native 列表（例如 FlatList、ScrollView，或高性能列表如 FlashList 或 Legend List）嵌套到抽屉中。为可滚动组件设置 nestedScrollEnabled，使其优先滚动自身内容。滚动到顶部边缘后，剩余的拖拽操作会移动抽屉。如果未设置 nestedScrollEnabled，列表会消耗手势，抽屉则保持不动。

ScrollableContentBottomSheetExample.tsx

import { useState } from 'react';
import {
  Host,
  ModalBottomSheet,
  Button,
  Column,
  RNHostView,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import {
  fillMaxHeight,
  padding,
} from '@expo/ui/jetpack-compose/modifiers';
import { FlatList, Text as RNText } from 'react-native';

const DATA = Array.from({ length: 50 }, (_, i) => `项目 ${i + 1}`);

export default function ScrollableContentBottomSheetExample() {
  const colors = useMaterialColors();
  const [visible, setVisible] = useState(false);

  return (
    <Host matchContents>
      <Button onClick={() => setVisible(true)}>
        <Text>打开可滚动抽屉</Text>
      </Button>
      {visible && (
        <ModalBottomSheet
          onDismissRequest={() => setVisible(false)}>
          <Column
            modifiers={[fillMaxHeight(), padding(16, 16, 16, 16)]}>
            <RNHostView>
              <FlatList
                nestedScrollEnabled
                style={{ flex: 1 }}
                data={DATA}
                keyExtractor={item => item}
                renderItem={({ item }) => (
                  <RNText
                    style={{
                      paddingVertical: 16,
                      color: colors.onSurface,
                    }}>
                    {item}
                  </RNText>
                )}
              />
            </RNHostView>
          </Column>
        </ModalBottomSheet>
      )}
    </Host>
  );
}

不可关闭的底部抽屉

结合 properties、sheetGesturesEnabled 创建一个只能通过编程方式关闭的底部抽屉。

NonDismissibleExample.tsx

import { useRef, useState } from 'react';
import {
  Host,
  ModalBottomSheet,
  Button,
  Column,
  Text,
} from '@expo/ui/jetpack-compose';
import type { ModalBottomSheetRef } from '@expo/ui/jetpack-compose';
import { paddingAll } from '@expo/ui/jetpack-compose/modifiers';

export default function NonDismissibleExample() {
  const [visible, setVisible] = useState(false);
  const sheetRef = useRef<ModalBottomSheetRef>(null);

  const hideSheet = async () => {
    await sheetRef.current?.hide();
    setVisible(false);
  };

  return (
    <Host matchContents>
      <Button onClick={() => setVisible(true)}>
        <Text>打开不可关闭的底部抽屉</Text>
      </Button>
      {visible && (
        <ModalBottomSheet
          ref={sheetRef}
          onDismissRequest={() => setVisible(false)}
          sheetGesturesEnabled={false}
          properties={{
            shouldDismissOnBackPress: false,
            shouldDismissOnClickOutside: false,
          }}>
          <Column
            verticalArrangement={{ spacedBy: 12 }}
            modifiers={[paddingAll(24)]}>
            <Text>
              此抽屉无法通过滑动、按返回键或点击外部关闭。
            </Text>
            <Text>只有下面的按钮可以将其关闭。</Text>
            <Button onClick={hideSheet}>
              <Text>关闭</Text>
            </Button>
          </Column>
        </ModalBottomSheet>
      )}
    </Host>
  );
}

API

import { ModalBottomSheet } from '@expo/ui/jetpack-compose';

Constants

`BottomSheet.ModalBottomSheet`

Android

Type: ModalBottomSheetComponent

Props

`children`

Android

Type: ReactNode

The children of the ModalBottomSheet component. Can include a ModalBottomSheet.DragHandle slot for a custom drag handle.

`containerColor`

Android

Optional • Type: ColorValue

The background color of the bottom sheet.

`contentColor`

Android

Optional • Type: ColorValue

The preferred color of the content inside the bottom sheet.

`initialFullyExpanded`

Android

Optional • Type: boolean • Default: false

Opens the sheet fully expanded on first composition. Ignored when skipPartiallyExpanded is true.

`modifiers`

Android

Optional • Type: ModifierConfig[]

Modifiers for the component.

`onDismissRequest`

Android

Type: () => void

Callback function that is called when the user dismisses the bottom sheet (via swipe, back press, or tapping outside the scrim).

`properties`

Android

Optional • Type: ModalBottomSheetProperties

Properties for the modal window behavior.

`ref`

Android

Optional • Type: Ref<ModalBottomSheetRef>

Can be used to imperatively hide the bottom sheet with an animation.

`scrimColor`

Android

Optional • Type: ColorValue

The color of the scrim overlay behind the bottom sheet.

`sheetGesturesEnabled`

Android

Optional • Type: boolean • Default: true

Whether gestures (swipe to dismiss) are enabled on the bottom sheet.

`showDragHandle`

Android

Optional • Type: boolean • Default: true

Whether to show the default drag handle at the top of the bottom sheet. Ignored if a custom ModalBottomSheet.DragHandle slot is provided.

`skipPartiallyExpanded`

Android

Optional • Type: boolean • Default: false

Immediately opens the bottom sheet in full screen.

Types

`ModalBottomSheetProperties`

Android

Property	Type	Description
shouldDismissOnBackPress(optional)	`boolean`	Whether the bottom sheet can be dismissed by pressing the back button. Default:`true`
shouldDismissOnClickOutside(optional)	`boolean`	Whether the bottom sheet can be dismissed by clicking outside (on the scrim). Default:`true`

`ModalBottomSheetRef`

Android

Property	Type	Description
expand	`() => Promise<void>`	Programmatically expands the bottom sheet to full height with an animation.
hide	`() => Promise<void>`	Programmatically hides the bottom sheet with an animation. The returned promise resolves after the dismiss animation completes.
partialExpand	`() => Promise<void>`	Programmatically collapses the bottom sheet to partially expanded (~50%) state. Only works when `skipPartiallyExpanded` is `false`.