# @devvie/bottom-sheet 中文文档

规范地址：https://npmcn.com/package/%40devvie/bottom-sheet/

版本：0\.5\.0
npm 元数据更新时间：2026-07-04T22:06:38.889Z
中文译文更新时间：2026-11-12T04:36:19.145Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40devvie/bottom-sheet
原文对照：https://npmcn.com/package/%40devvie/bottom-sheet/?lang=original
项目主页：https://github.com/stanleyugwu/react-native-bottom-sheet#readme
源码仓库：https://github.com/stanleyugwu/react-native-bottom-sheet

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：329 kB，172 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18\.2\.0，react-native \>=0\.73\.4
- 首次发布：2023-10-10T09:06:01.522Z
- 最新版本发布：2026-07-04T22:06:38.753Z
- 近 30 天下载量：59003（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 2 个）

## 中文简介

聪明的,小的,和软的底板 你应用的渴望

## 安装

```sh
npm install @devvie/bottom-sheet
```

也可以使用：`pnpm add @devvie/bottom-sheet`、`yarn add @devvie/bottom-sheet`、`bun add @devvie/bottom-sheet`

## README

# 反应原生底表 {}

![GitHub](https://img.shields.io/github/license/stanleyugwu/react-native-bottom-sheet?style=plastic&label=License&color=%23fea9f8) ![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/stanleyugwu/react-native-bottom-sheet/ci.yml?color=%23fea9f8&label=Build) [![runs with expo](https://img.shields.io/badge/Expo-Support-fea9f8.svg?style=platic&logo=EXPO&logoColor=fff)](https://expo.io/) ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/stanleyugwu/react-native-bottom-sheet?color=%23fea9f8&label=Code%20Size) ![npm bundle size (scoped)](https://img.shields.io/bundlephobia/minzip/@devvie/bottom-sheet?style=plastic&logo=npm&color=%23fea9f8&label=Bundle%20Size) ![npm downloads](https://img.shields.io/npm/dm/@devvie/bottom-sheet?style=plastic&logo=npm&color=%23fea9f8&label=Downloads)

聪明的,微小的,灵活的底板 你的应用渴望

* * *

👉🏾 [![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://www.buymeacoffee.com/devvie) 👈🏾

* * *

#### Android & iOS 预览

![Preview for Android & iOS](https://i.ibb.co/Y38XsMr/Combined.gif)

#### 网络预览

![Preview for Web](https://i.ibb.co/2Y7fM7nC/Bottom-sheet-web-preview.gif)

## \* 安装

```sh
npm install @devvie/bottom-sheet
# or
yarn add @devvie/bottom-sheet
```

## 为什么这个底盘?

🚀 **插入和播放** —— 说 `npm install` 说完了 零第三方依赖性,没有 Babel 插件,没有 pock 安装. 完全建立在React Industrial自己的API上.

⌨️ **键盘智能** ——工作表自动检测键盘模式(`adjustPan` 编号 : `adjustResize`),测量自己在屏幕上的活性位置,当文字输入被聚焦时动画会达到安全高度——都没有任何配置或包装组件.

📦 **小脚印** - ~ 4 KB 轻而易举。 极轻又快 几乎不会影响你的体型.

🎯 **坐标点** - 确定休养职位,并配有: `%` 财务报告和审定财务报表 `px` 数值。 坐标点在内部按上升顺序自动排序,指索引 `0` 总是代表最小/相撞位置。 床单在释放时会快速到达最接近的点 并暴露出 `snapToIndex`, (中文(简体) ), `expand`,以及 `collapse` 用于全面方案控制.

📟 **实时道具更新** ——动态变化 `height`, (中文(简体) ), `snapPoints`,或 `containerHeight` 随时,工作表会重新同步它的布局, 夹住它的活性索引, 并自动点火回调.

🌐 **真正的跨平台** ——iOS,Android,Web,和博览会,均出自纯回放原生种. 不需要本地模块 .

🎞 **3个动画类型** 选择 `slide`, (中文(简体) ), `spring`,以及 `fade` 退出,或提供自定义的放松功能。 动画持续时间对于开放和相近的过渡都是完全可以配置的.

📜 **嵌入式滚动** - 与 `FlatList`, (中文(简体) ), `SectionList`,以及 `ScrollView` 在床单内。 拖动手柄来移动工作表; 滚动列表来滚动其内容——没有手势冲突.

🎨 **自定义组件** ——用您自己的动画组件来交换拖动手柄或背景. 两者都得到工作表的动画高度值来进行插值,因此可以构建丰富的交互手柄和相接相.

✨ **模式和非模式** · 使用有背景罩的全模式,或使用有高光阴影的轻量级内衬布。 支持工作表上方或后方的自定义背景组件.

✅ **类型脚本第一** ——有编译时间安全的全打入道具. `height` 财务报告和审定财务报表 `snapPoints` 在类型层面作为相互排斥的形式加以执行.

## 基本实例

必须打开和关闭底页。 通过 a `ref` 到底页并调用 `open()` 或者说 `close()` 方法。 。 .

#### 1\. 单高(默认)

```tsx
import React, { useRef } from 'react';
import BottomSheet, { BottomSheetMethods } from '@devvie/bottom-sheet';
import { Button, Text, View } from 'react-native';

const App = () => {
  const sheetRef = useRef<BottomSheetMethods>(null);
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button title="Open Sheet" onPress={() => sheetRef.current?.open()} />
      <BottomSheet ref={sheetRef} height={300}>
        <Text>
          The smart 😎, tiny 📦, and flexible 🎗 bottom sheet your app craves 🚀
        </Text>
      </BottomSheet>
    </View>
  );
};

export default App;
```

#### 2\. 有坐标点(多高)

```tsx
import React, { useRef } from 'react';
import BottomSheet, { BottomSheetMethods } from '@devvie/bottom-sheet';
import { Button, Text, View } from 'react-native';

const App = () => {
  const sheetRef = useRef<BottomSheetMethods>(null);
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button title="Open Sheet" onPress={() => sheetRef.current?.open()} />
      <BottomSheet
        ref={sheetRef}
        snapPoints={['30%', 450, '90%']}
        index={0}
        onSnap={(index) => console.log('snapped to', index)} // index 0..2, or -1 on close
      >
        <Text>Drag me between snap points 🎯</Text>
      </BottomSheet>
    </View>
  );
};

export default App;
```

### ưμ㼯A

底板组件在内部使用并处理平板手势,以避免卷轴/平板上与其容器的不当行为, **别** 放在一个支持平板的容器内,例如 `ScrollView`你可以把它放在旁边 `ScrollView` 和使用情况 `React Fragment` 或一个 `View` 把它包起来 一切都会好的.

#### 不要这样

```jsx
<ScrollView>
  <BottomSheet>...</BottomSheet>
</ScrollView>
```

#### ~ 做到这一点 ~

```jsx
<>
  <ScrollView>...</ScrollView>

  <BottomSheet>...</BottomSheet>
</>
```

## ++ Propals 软件

底板通过道具高度可配置. 所有道具都为两者服务 `Android` 财务报告和审定财务报表 `iOS` 除前缀外 `android_` 财务报告和审定财务报表 `ios_`,仅用于 `Android` 财务报告和审定财务报表 `iOS` 页:1.

| 财产 | 类型 | 默认 | 说明 | 需求 |
| :-: | :-: | --- | --- | --- |
| `android_backdropMaskRippleColor` | `string | OpaqueColorValue` |  | 按下背景遮罩时的波纹效果颜色( R)**只有机器人**) (中文(简体) ). | 没有 |
| `android_closeOnBackPress` | `boolean` | `true` | 确定设备后按键时工作表是否关闭( Q)**只有机器人**) (中文(简体) ). | 没有 |
| `animationType` | `'slide' | 'spring' | 'fade' | ANIMATIONS` | `'slide'` | 打开和关闭底页时使用的动画 . | 没有 |
| `backdropMaskColor` | `string | OpaqueColorValue` | `'#00000052'` | 浅色或背景面具的颜色 . | 没有 |
| `children` | `ViewProps['children'] | React.FunctionComponent<{_animatedHeight: Animated.Value}>` | `null` | 底层工作表的内容. | 对 |
| `closeDuration` | `number` | `500` | 工作表关闭动画的持续时间 . | 没有 |
| `closeOnBackdropPress` | `boolean` | `true` | 确定下方工作表在按下缩放或背景掩码时是否关闭 . | 没有 |
| `closeOnDragDown` | `boolean` | `true` | 确定底页是否在被拖下时关闭 . | 没有 |
| `containerHeight` | `ViewStyle['height']` | `DEVICE SCREEN HEIGHT` | 底板整体容器高度. | 没有 |
| `customBackdropComponent` | `React.FunctionComponent<{_animatedHeight: Animated.Value}>` | `null` | 自定义工作表的缩写或背景遮罩的组件 . | 没有 |
| `customBackdropPosition` | `"top" | "behind"` | `'behind'` | 确定自定义 scrim或背景组件的位置. `'behind'` 把它放在键盘后面,“上”把它放在键盘上. | 没有 |
| `customDragHandleComponent` | `React.FC<{_animatedHeight: Animated.Value}>` |  | 自定义拖动手柄组件来替换默认底页拖动手柄 . | 没有 |
| `customEasingFunction` | `AnimationEasingFunction` | `ANIMATIONS.SLIDE` | 驾驶表动画的自定义放松功能. | 没有 |
| `disableBodyPanning` | `boolean` | `false` | 防止底盘被拖下/被拉下. | 没有 |
| `disableDragHandlePanning` | `boolean` | `false` | 拖动拖动拖动柄,防止底盘被压倒. | 没有 |
| `dragHandleStyle` | `ViewStyle` |  | 用于拖动控点的额外样式 . | 没有 |
| `height` | `number | string` | `'50%'` | 打开底盘时的高度 。 相对 `containerHeight` 道具 | 没有 |
| `hideDragHandle` | `boolean` | `false` | 当真实时, 隐藏工作表的拖动手柄 . | 没有 |
| `index` | `number` | `0` | 坐标点索引工作表打开到(当 `snapPoints` 已设定). `0` 是最小的一点。 仅是初始位置(不是被动状态). | 没有 |
| `modal` | `boolean` | `true` | 确定工作表是否为模式。 模式表有斜线或背景口罩,而标准(非模式)表则没有. | 没有 |
| `onSnap` | `(index: number) => void` |  | 当工作表在坐标点(道克或程序)上结算时调用; `-1` 关闭. | 没有 |
| `openDuration` | `number` | `500` | 工作表打开动画的持续时间 . | 没有 |
| `snapPoints` | `(number | string)[]` | `undefined` | 休息位置,px数字和 `'%'` 例如,字符串. `['30%', 600]`优先排序 `height`。通过拖放或反射方法进行对齐. | 没有 |
| `style` | `Omit<ViewStyle, 'height' | 'minHeight' | 'maxHeight' | 'transform:[{translateY}]'>` |  | 对底工作表应用的额外样式. | 没有 |

### 反证方法

床单 `ref` 揭露下列方法:

| 方法 | 说明 |
| :-: | :-: |
| `open()` | 打开底页( 到 `index` 道具,如果 `snapPoints` 提供,否则 `height`) (中文(简体) ). |
| `close()` | 关闭底盘 . |
| `snapToIndex(index)` | 动画到坐标点 `index` (尖叫声). `-1` 关闭; 如果工作表关闭则打开. |
| `expand()` | 动到最大起落点. |
| `collapse()` | 动到最小点. |

```tsx
sheetRef.current?.open(); // open sheet
sheetRef.current?.close(); // close sheet
sheetRef.current?.snapToIndex(2); // jump to the 3rd (largest) point
sheetRef.current?.expand(); // largest point
sheetRef.current?.collapse(); // smallest point
```

> 何时 `snapPoints` 这些方法不能解决单一的 `height`所以他们总是安全的打电话.

## 实例

灵活性是这个底层工作表的重点,这些少数例子显示了底层工作表的某些行为,以及调整道具可以实现什么.

### 1:QQ 对键盘弹出和方向变化(默认行为)的智能响应

| 机器人 | iOS系统 |
| :-: | :-: |
| ![Preview for keyboard handling (Android)](https://i.ibb.co/0BfLWYK/Keyboard-Response.gif) | ![Preview for keyboard handling (iOS)](https://i.ibb.co/302ZYBL/Keyboard-Response.gif) |

### 2+Q 处理深层嵌入列表并滚动视图交互( 默认行为)

| 机器人 | iOS系统 |
| :-: | :-: |
| ![Preview for scroll handling (Android)](https://i.ibb.co/kgfPM3w/Nested-Scroll.gif) | ![Preview for scroll handling (iOS)](https://i.ibb.co/rcrJVLc/Nested-List.gif) |

### 3️⃣ 当自动调整布局 `height` 财务报告和审定财务报表 `containerHeight` 道具更改( 默认行为)

![](https://i.ibb.co/3YGXHht/Detect-Height.gif)

### 4️⃣ 滚动内容时延长工作表高度

![](https://i.ibb.co/9W5J2t5/Extend-on-scroll.gif)

### 5- 用作 `SnackBar`

![](https://i.ibb.co/LkMJ255/Snack-Bar.gif)

### 6️⃣自定义拖放动画内插

![](https://i.ibb.co/0yDPQ0W/Drag-Handle-Animation.gif)

### 7-% 自定义相间/ 背面

![](https://i.ibb.co/h9XqBJC/Custom-Scrim.gif)

#### _很快会有更多例子出现..._

## 捐款

见 [贡献指南](https://npmcn.com/package/%40devvie/bottom-sheet/CONTRIBUTING.md) 学习如何为储存库和发展工作流程作出贡献.

## 许可证

麻省理工学院

见 [自由主义](https://npmcn.com/package/%40devvie/bottom-sheet/LICENSE.md)

* * *

## 支助

[![](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20Okpa&emoji=%F0%9F%8D%98&slug=devvie&button_colour=Fea9f8&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/devvie)

</> 与 {} 由 [德维](https://twitter.com/stanleyugwu_) ✌

## 常见问题

### @devvie/bottom-sheet 是什么？

聪明的,小的,和软的底板 你应用的渴望

### 如何安装 @devvie/bottom-sheet？

在项目目录运行 npm install @devvie/bottom-sheet，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.2\.0）、react-native（\>=0\.73\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @devvie/bottom-sheet 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @devvie/bottom-sheet 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @devvie/bottom-sheet 可以商用吗？

@devvie/bottom-sheet 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @devvie/bottom-sheet 的下载量有多少？

根据 npm 官方下载统计，@devvie/bottom-sheet 在 2026/10/12 – 2026/11/10 这 30 天内被下载 59,003 次，日均约 1,967 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @devvie/bottom-sheet 还在维护吗？

最新版本 0\.5\.0 发布于 2026/07/05（4 个月前）；至今共发布 11 个版本，其中过去 12 个月发布了 2 个；首次发布于 2023/10/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。