npm package: @hadss/react-native-adaptive-sheet
Description: A performant interactive adaptive sheet with fully configurable options 🚀
Latest version: 1.0.0-rc.1

# react-native-adaptive-sheet

## 介绍
`@hadss/react-native-adaptive-sheet` 是一个为 React Native 应用提供多设备弹窗样式的三方库。它可根据不同设备的屏幕宽度动态调整弹窗显示样式。  
该库提供提供底部、全屏、侧边和居中四种样式的弹窗组件。适用于手机、平板等多种终端。 
### 目录结构
```
react-native-adaptive-sheet/
├── components/                                      # 组件目录
│   ├── adaptiveSheet/                               # 统一自适应组件
│   ├── adaptiveBottomSheet/                         # 底部弹窗组件
│   ├── adaptiveSideSheet/                           # 侧边弹窗组件
│   ├── adaptiveCenterSheet/                         # 居中弹窗组件
│   ├── adaptiveSheetBackdrop/                       # 背景遮罩组件
│   ├── adaptiveSheetBackdropContainer/              # 背景遮罩容器
│   ├── adaptiveSheetBackground/                     # 背景组件
│   ├── adaptiveSheetBackgroundContainer/            # 背景容器
│   ├── adaptiveSheetContainer/                      # 主容器组件
│   ├── adaptiveSheetDraggableView/                  # 可拖拽视图组件
│   ├── adaptiveSheetFooter/                         # 底部组件
│   ├── adaptiveSheetFooterContainer/                # 底部容器
│   ├── adaptiveSheetGestureHandlersProvider/        # 手势处理提供者
│   ├── adaptiveSheetHandle/                         # 拖拽手柄组件
│   └── adaptiveSheetHandleContainer/                # 拖拽手柄容器
├── contexts/                                        # Context 上下文
├── hooks/                                           # 自定义 Hooks
├── utilities/                                       # 工具函数
```
## 安装与使用
进入到工程目录并输入以下命令：
**npm**
```bash
npm install @hadss/react-native-adaptive-sheet
```

**yarn**
```bash
yarn add @hadss/react-native-adaptive-sheet
```
## Link
> 本库依赖以下三方库，请查看对应文档

> [@react-native-oh-tpl/react-native-gesture-handler](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/react-native-gesture-handler.md)

> [@react-native-oh-tpl/react-native-reanimated](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/react-native-reanimated.md)

> [@hadss/react_native_breakpoints](https://gitcode.com/openharmony-sig/rn_multidevice_layout_scenepkg/blob/master/packages/react_native_breakpoints/README.md)
## API说明
- `AdaptiveSheet` - 自适应弹窗组件（主组件）
- `SHEET_TYPE` - 弹窗类型枚举
- `SIDE_POSITION` - 侧边弹窗位置枚举
- `AdaptiveSheetMethods` - 弹窗方法类型（用于 ref）
- `AdaptiveSheetProps` - 弹窗属性类型
- `HeaderComponentProps` - 头部组件属性类型（用于自定义头部）
### AdaptiveSheet组件
| 属性名              | 描述                                                                     | 类型                                                             | 是否必填 | 支持平台 |
| ---------------- | ---------------------------------------------------------------------- | :------------------------------------------------------------- | :--: | :--: |
| index            | 初始snap索引，可以设置为 -1 来让sheet初始处于关闭状态，默认值：-1。                              | number                                                         |  否   | All  |
| breakpoints      | 设置横向断点区间，默认：{xs: 320px，sm: 600px, md: 834px, lg: 1440px, xl: Infinity} | Breakpoints                                                    |  否   | All  |
| prefertype       | sheet弹出类型，默认：SHEET_AUTO，根据断点区间展示对应样式                                   | SHEET_TYPE                                                     |  否   | All  |
| bottomSheetProps | 设置底部弹窗参数                                                               | BottomSheetProps                                               |  否   | All  |
| sideSheetProps   | 设置侧边弹窗参数                                                               | SideSheetProps                                                 |  否   | All  |
| centerSheetProps | 设置居中弹窗参数                                                               | CenterSheetProps                                               |  否   | All  |
| children         | sheet主内容                                                               | (() => React.ReactElement)\|React.ReactNode[]\|React.ReactNode |  否   | All  |
| onStateChange    | sheet 状态发生变化的回调（开启和关闭）                                                 | function                                                       |  否   | All  |
| onSizeChange     | sheet 尺寸发生变化的回调                                                        | function                                                       |  否   | All  |

### BottomSheetProps

| 属性名                        | 描述                                                                           | 类型                                 | 是否必填 | 支持平台 |
| -------------------------- | ---------------------------------------------------------------------------- | :--------------------------------- | :--: | :--: |
| topInset                   | 顶部内边距（仅用于 headerMode 为 fixed ）。默认：0px                                        | number                             |  否   | All  |
| snapPoints                 | sheet 默认高度设置，半框样式，默认：'70%'，当 headerMode 为 fixed 并且 snapPoints 为 100% 时为全屏弹窗） | string\|number                     |  否   | All  |
| backgroundStyle            | 背板样式（可设置弹窗颜色）                                                                | ViewStyle                          |  否   | All  |
| enablePanDownToClose       | 支持下滑关闭（全屏样式无效），默认：true                                                       | boolean                            |  否   | All  |
| enableHandlePanningGesture | 支持手柄拖拽（全屏样式无效），默认：true                                                       | boolean                            |  否   | All  |
| enabelDragToClose          | 支持拖拽到 33%以下关闭（全屏样式无效），默认：true                                                | boolean                            |  否   | All  |
| animationConfigs           | 设置动画参数                                                                       | WithSpringConfig\|WithTimingConfig |  否   | All  |
| headerMode<br>             | 设置顶部可拖拽弹窗和顶部不可拖拽弹窗，默认：draggable<br>可设置fixed                                  | string                             |  否   | All  |
| headerComponent            | 固定头部样式的底部弹窗的头部组件设置                                                           | React. ComponentType               |  否   | All  |

**拖拽范围**：
- 最小高度：40%
- 最大高度：90%
- 默认高度：70%
- 100% 时不可拖拽（全屏模式）

### SideSheetProps

| 属性名                        | 描述                                | 类型                                 | 是否必填 | 支持平台 |
| -------------------------- | --------------------------------- | :--------------------------------- | :--: | :--: |
| position                   | 弹窗位置（左侧/右侧）默认：SIDE_POSITION.RIGHT | SIDE_POSITION                      |  否   | All  |
| topInset                   | 顶部内边距。默认：0px                      | number                             |  否   | All  |
| snapPoints                 | sheet 默认高度设置，半框样式，默认：50%          | string\|number                     |  否   | All  |
| backgroundStyle            | 背板样式（可设置弹窗背板颜色）                   | ViewStyle                          |  否   | All  |
| enablePanToClose           | 支持侧滑关闭，默认：true                    | boolean                            |  否   | All  |
| enableHandlePanningGesture | 支持手柄拖拽（全屏样式无效），默认：true            | boolean                            |  否   | All  |
| enabelDragToClose          | 支持拖拽到 33%时关闭弹窗，默认：true            | boolean                            |  否   | All  |
| animationConfigs           | 设置动画参数                            | WithSpringConfig\|WithTimingConfig |  否   | All  |
| showHeader                 | 是否显示头部                            | boolean                            |  否   | All  |
| headerComponent            | 头部自定义组件                           | React. ComponentType               |  否   | All  |

**拖拽范围**：
- 最小宽度：40%
- 最大宽度：85%
- 默认宽度：50%

### CenterSheetProps

| 属性名              | 描述              | 类型                                 | 是否必填 | 支持平台 |
| ---------------- | --------------- | :--------------------------------- | :--: | :--: |
| verticalMargin   | 上下外边距，默认：40px   | number                             |  否   | All  |
| width            | 设置宽度：576px      | string\|number                     |  否   | All  |
| height           | 设置高度：768px      | string\|number                     |  否   | All  |
| contentStyle     | 背板样式（可设置弹窗背板颜色） | ViewStyle                          |  否   | All  |
| animationConfigs | 设置动画参数          | WithSpringConfig\|WithTimingConfig |  否   | All  |
| showHeader       | 是否显示头部          | boolean                            |  否   | All  |
| headerComponent  | 自定义头部组件         | React. ComponentType               |  否   | All  |

### HeaderComponentProps（自定义头部组件属性）

| 属性名              | 描述          | 类型                              | 是否必填 | 支持平台 |
| ---------------- | ----------- | ------------------------------- | ---- | ---- |
| title            | 头部标题        | string                          | 否    | All  |
| height           | 头部高度        | number                          | 否    | All  |
| topInset         | 顶部内边距（自动传入） | number                          | 否    | All  |
| leftButton       | 自定义左侧按钮     | React.ReactNode                 | 否    | All  |
| rightButton      | 自定义右侧按钮     | React.ReactNode                 | 否    | All  |
| onLeftPress      | 左侧按钮点击回调    | function                        | 否    | All  |
| onRightPress     | 右侧按钮点击回调    | function                        | 否    | All  |
| titleStyle       | 标题文本样式      | Style                           | 否    | All  |
| containerStyle   | 容器样式        | Style                           | 否    | All  |
| leftButtonStyle  | 左侧按钮样式      | Style                           | 否    | All  |
| rightButtonStyle | 右侧按钮样式      | Style                           | 否    | All  |
| closeButtonColor | 关闭按钮颜色      | string                          | 否    | All  |
| sheetType        | 弹窗类型（自动传入）  | 'bottom' \| 'side' \| 'center'` | 否    | All  |

**默认关闭按钮位置**：

- 底部弹窗：左侧
- 侧边弹窗：右侧
- 居中弹窗：右侧

### AdaptiveSheetMethods (ref 方法)

| 方法名            | 参数                           | 描述         | 支持平台 |
| -------------- | ---------------------------- | ---------- | ---- |
| snapToIndex    | (index: number)              | 跳转到指定档位    | All  |
| snapToPosition | (position: string \| number) | 跳转到指定位置    | All  |
| expand         | ()                           | 展开到默认高度/宽度 | All  |
| close          | ()                           | 关闭弹窗       | All  |

### SHEET_TYPE枚举

| 属性名    | 描述                                                     | 类型     |
| ------ | ------------------------------------------------------ | :----- |
| AUTO   | 自适应样式，根据断点区间，自动变化样式。[0, sm) 底部，[md, lg) 居中，[lg, +∞) 侧边 | string |
| BOTTOM | 底部样式                                                   | string |
| SIDE   | 侧边样式                                                   | string |
| CENTER | 居中样式                                                   | string |
### SIDE_POSITION 枚举
| 枚举值   | 描述   | 类型     |
| ----- | ---- | :----- |
| LEFT  | 左侧弹窗 | string |
| RIGHT | 右侧弹窗 | string |
## 约束与限制

本示例仅支持标准系统上运行，支持设备：手机、平板、PC。 DevEco Studio版本：5.0.1 Release及以上。 SDK版本：API13及以上。