@gmfe/react 2.14.29 → 2.14.30

package/src/component/list/README.md

@@ -0,0 +1,96 @@
+# List
+
+## 简介
+列表组件 - 支持单选、多选、分组展示和滚动定位的通用列表
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { List } from '@gmfe/react'
+
+// 基础单选
+<List
+  data={[
+    { value: '南山', text: '南山' },
+    { value: '福田', text: '福田', disabled: true },
+    { value: '龙岗', text: '龙岗' }
+  ]}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 数据源，普通列表格式：`[{value, text, disabled}]`，分组列表格式：`[{label, children: [{value, text, disabled}]}]` | `array` | - | 是 |
+| selected | 选中值，单选为 value，多选为 `[value, value]`。多选请务必提供数组 | `any` | - | 否 |
+| onSelect | 选中回调，单选返回 value，多选返回 `[value, value]` | `function` | `_.noop` | 否 |
+| multiple | 是否多选 | `bool` | `false` | 否 |
+| isGroupList | 数据是否为分组格式 | `bool` | `false` | 否 |
+| renderItem | 自定义列表项渲染，参数为 `(item, index)` | `function` | `(item) => item.text` | 否 |
+| willActiveIndex | 即将激活的索引，用于键盘导航 | `number` | - | 否 |
+| isScrollTo | 是否滚动到选中项 | `bool` | `false` | 否 |
+| getItemProps | 给列表项更多自定义属性，参数为 `(item)` | `function` | `() => ({})` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础单选
+```jsx
+<List
+  data={data}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+```
+
+### 多选
+```jsx
+<List
+  multiple
+  data={data}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+```
+
+### 分组列表
+```jsx
+<List
+  data={groupData}
+  isGroupList
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+```
+
+### 自定义渲染项
+```jsx
+<List
+  data={data}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  renderItem={(item, index) => item.text + index}
+/>
+```
+
+### 滚动到选中项
+```jsx
+<List
+  data={data}
+  selected="罗湖5"
+  onSelect={selected => setSelected(selected)}
+  isScrollTo
+  style={{ maxHeight: '100px' }}
+/>
+```
+
+## 注意事项
+- 多选情况下 `selected` 请务必传递数组类型
+- `data` 中单个项支持 `disabled` 属性来禁用该项

package/src/component/loading/README.md

@@ -0,0 +1,116 @@
+# Loading
+
+## 简介
+加载中组件 - 提供多种加载状态展示方式，包含基础旋转加载、区域块加载和全屏加载三种模式
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Loading, LoadingChunk, LoadingFullScreen } from '@gmfe/react'
+```
+
+## API
+
+### Loading 组件 Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| text | 加载文字 | `string` | - | 否 |
+| size | 加载图标尺寸（像素） | `number` | `40` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### LoadingChunk 组件 Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| loading | 是否显示加载状态 | `bool` | `false` | 否 |
+| children | 加载区域内容 | `any` | - | 否 |
+| text | 加载文字 | `string` | - | 否 |
+| size | 加载图标尺寸（像素） | `number` | `50` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### LoadingChunk 静态方法
+
+无静态方法，仅作为组件使用。
+
+### LoadingFullScreen 静态方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `LoadingFullScreen.render(props)` | 显示全屏加载 | `props: Object` | - |
+| `LoadingFullScreen.hide()` | 隐藏全屏加载 | - | - |
+
+#### LoadingFullScreen Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| text | 加载文字 | `string` | - | 否 |
+| size | 加载图标尺寸（像素） | `number` | `50` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础旋转加载
+
+```jsx
+<Loading />
+```
+
+### 自定义大小
+
+```jsx
+<Loading size={100} />
+```
+
+### 带文字的加载
+
+```jsx
+<Loading text="正在加载中..." />
+```
+
+### 区域块加载（LoadingChunk）
+
+```jsx
+<LoadingChunk loading size={60}>
+  <div style={{ height: '100px' }}>
+    这是被遮罩的内容区域
+  </div>
+</LoadingChunk>
+```
+
+### 区域块加载带文字
+
+```jsx
+<LoadingChunk loading size={60} text="拼命加载中...">
+  <div style={{ height: '100px' }}>
+    被遮罩的内容
+  </div>
+</LoadingChunk>
+```
+
+### 全屏加载
+
+```jsx
+// 显示全屏加载
+LoadingFullScreen.render({
+  text: '拼命加载中...'
+})
+
+// 3秒后自动关闭
+setTimeout(() => {
+  LoadingFullScreen.hide()
+}, 3000)
+```
+
+## 注意事项
+
+- `Loading` 是基础的旋转加载图标组件，可嵌入到任何容器中。
+- `LoadingChunk` 在内容区域上叠加一层遮罩和加载图标，适合包裹在卡片、表格等局部区域使用。不传 `children` 时会自动生成一个高度为 `size` 的占位区域。
+- `LoadingFullScreen` 使用命令式调用，显示全屏加载遮罩时会自动在 `document.body` 上添加 `gm-loading-body-overflow` 类以禁止页面滚动，隐藏时自动移除。
+- 全屏加载默认图标尺寸为 50px，大于基础 Loading 的默认 40px。
+- `LoadingChunk` 的 `loading` 属性默认为 `false`，需要手动设置为 `true` 才会显示加载状态。

package/src/component/mask/README.md

@@ -0,0 +1,62 @@
+# Mask
+
+## 简介
+遮罩层组件 - 提供可自定义透明度的半透明黑色遮罩层，适用于覆盖在内容上方
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Mask } from '@gmfe/react'
+```
+
+## API
+
+### Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| opacity | 遮罩透明度，取值范围 0~1 | `number` | `0.5` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+
+```jsx
+<Mask />
+```
+
+### 自定义透明度
+
+```jsx
+// 较浅的遮罩
+<Mask opacity={0.2} />
+
+// 较深的遮罩
+<Mask opacity={0.8} />
+
+// 完全透明（仅作为覆盖层）
+<Mask opacity={0} />
+```
+
+### 配合定位使用
+
+```jsx
+<div style={{ position: 'relative' }}>
+  <div>被遮罩的内容</div>
+  <Mask
+    style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 }}
+    opacity={0.6}
+  />
+</div>
+```
+
+## 注意事项
+
+- Mask 组件仅渲染一个 `div` 元素，不会自动铺满父容器，需要通过 CSS 定位（如 `position: absolute`）来控制覆盖范围。
+- `opacity` 通过 `rgba(0,0,0, opacity)` 设置背景色，值越大遮罩越深。
+- 遮罩层会透传其他 HTML 属性（通过 `...rest`），可以绑定 `onClick` 等事件。
+- 如需带关闭功能的遮罩层，建议使用 Modal 或 Drawer 组件。

package/src/component/modal/README.md

@@ -0,0 +1,155 @@
+# Modal
+
+## 简介
+模态框组件 - 用于在页面中显示模态对话框，支持多种尺寸和展示样式，包含标准模态框、右侧抽屉式模态框和简洁模态框三种变体
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Modal, RightSideModal, CleanModal } from '@gmfe/react'
+```
+
+## API
+
+### Modal 组件 Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| show | 是否显示 | `bool` | - | 是 |
+| type | 模态框类型，设置后使用简化样式，不设置则为标准模态框 | `string` | - | 否 |
+| title | 标题 | `string` | - | 否 |
+| size | 尺寸 | `'lg' \| 'md' \| 'sm'` | `'md'` | 否 |
+| children | 内容 | `any` | - | 否 |
+| onHide | 关闭回调 | `func` | `_.noop` | 否 |
+| onOk | 确认回调（type 模式下使用） | `func` | - | 否 |
+| onCancel | 取消回调（type 模式下使用） | `func` | - | 否 |
+| disableMaskClose | 是否禁止点击遮罩关闭 | `bool` | `false` | 否 |
+| opacityMask | 是否使用半透明遮罩 | `bool` | `false` | 否 |
+| noContentPadding | 是否取消内容区内边距 | `bool` | `false` | 否 |
+| noCloseBtn | 是否隐藏关闭按钮 | `bool` | `false` | 否 |
+| okBtnClassName | 确认按钮的自定义 className（type 模式下使用） | `string` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### Modal 静态方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `Modal.render(props)` | 通过命令式渲染模态框 | `props: Object` | - |
+| `Modal.hide()` | 隐藏命令式渲染的模态框 | - | - |
+
+> 注意：`Modal.confirm`、`Modal.info`、`Modal.success`、`Modal.warning` 已废弃，请使用 `Dialog` 组件替代。
+
+### RightSideModal 静态方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `RightSideModal.render(props)` | 从右侧滑入显示模态框 | `props: Object` | - |
+| `RightSideModal.hide()` | 隐藏右侧模态框 | - | - |
+
+#### RightSideModal Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| show | 是否显示 | `bool` | - | 是 |
+| onHide | 关闭回调 | `func` | `_.noop` | 否 |
+| disableMaskClose | 是否禁止点击遮罩关闭 | `bool` | `false` | 否 |
+| size | 尺寸 | `'lg' \| 'md' \| 'sm'` | `'md'` | 否 |
+| title | 标题 | `string` | - | 否 |
+| okBtnClassName | 确认按钮的自定义 className | `string` | - | 否 |
+| noContentPadding | 是否取消内容区内边距 | `bool` | `false` | 否 |
+
+### CleanModal 静态方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `CleanModal.render(props)` | 显示简洁样式的模态框（无阴影边框） | `props: Object` | - |
+| `CleanModal.hide()` | 隐藏简洁模态框 | - | - |
+
+#### CleanModal Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| show | 是否显示 | `bool` | - | 是 |
+| onHide | 关闭回调 | `func` | `_.noop` | 否 |
+| disableMaskClose | 是否禁止点击遮罩关闭 | `bool` | `false` | 否 |
+| size | 尺寸 | `'lg' \| 'md' \| 'sm'` | `'md'` | 否 |
+| title | 标题 | `string` | - | 否 |
+| okBtnClassName | 确认按钮的自定义 className | `string` | - | 否 |
+| noContentPadding | 是否取消内容区内边距 | `bool` | `false` | 否 |
+
+## 示例
+
+### 标准模态框 - 命令式渲染
+
+```jsx
+// 显示
+Modal.render({
+  show: true,
+  title: '标题',
+  children: <div>模态框内容</div>,
+  onHide: () => {
+    Modal.hide()
+  }
+})
+
+// 隐藏
+Modal.hide()
+```
+
+### 右侧抽屉式模态框
+
+```jsx
+// 显示
+RightSideModal.render({
+  show: true,
+  title: '详情',
+  children: <div>右侧抽屉内容</div>,
+  onHide: () => {
+    RightSideModal.hide()
+  }
+})
+
+// 隐藏
+RightSideModal.hide()
+```
+
+### 简洁模态框
+
+```jsx
+// 显示
+CleanModal.render({
+  show: true,
+  title: '编辑信息',
+  children: <div>简洁模态框内容</div>,
+  onHide: () => {
+    CleanModal.hide()
+  }
+})
+
+// 隐藏
+CleanModal.hide()
+```
+
+### 禁止遮罩关闭
+
+```jsx
+Modal.render({
+  show: true,
+  disableMaskClose: true,
+  title: '不可关闭',
+  children: <div>点击遮罩不会关闭</div>,
+  onHide: () => Modal.hide()
+})
+```
+
+## 注意事项
+
+- Modal 是 Dialog 组件的底层依赖，一般情况下建议优先使用 `Dialog` 组件的静态方法。
+- Modal 的静态方法 `confirm`、`info`、`success`、`warning` 已被标记为废弃（Deprecated），调用时会在控制台输出警告。
+- 按下 `Esc` 键可以关闭模态框（通过 `onHide` 回调）。
+- `RightSideModal` 使用 `fade-in-left` 动画从右侧滑入。
+- `CleanModal` 提供无阴影、无边框的简洁展示风格。
+- `opacityMask` 设置为 `true` 时，遮罩将变为半透明样式，同时模态框会显示边框和底部阴影。

package/src/component/more_select/README.md

@@ -0,0 +1,185 @@
+# MoreSelect
+
+## 简介
+增强选择组件 - 支持单选、多选、分组列表、搜索过滤（含拼音搜索）和远程搜索等功能。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { MoreSelect } from '@gmfe/react'
+
+const list = [
+  { value: 1, text: '南山' },
+  { value: 2, text: '福田' },
+  { value: 3, text: '罗湖' }
+]
+
+<MoreSelect
+  data={list}
+  selected={selected}
+  onSelect={item => setSelected(item)}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 选项数据，格式 `[{value, text}]` | `array` | - | 是 |
+| selected | 当前选中的项（单选为 item 对象，多选为 item 数组） | `object \| array` | - | 否 |
+| onSelect | 选择回调，单选返回 item，多选返回 item 数组 | `func` | - | 是 |
+| multiple | 是否多选 | `bool` | - | 否 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| disabledClose | 单选时禁止显示清除按钮 | `bool` | - | 否 |
+| placeholder | 占位文字 | `string` | - | 否 |
+| searchPlaceholder | 搜索框占位文字 | `string` | - | 否 |
+| onSearch | 搜索回调，支持同步（直接返回过滤后的数据）或异步（返回 Promise） | `func` | - | 否 |
+| delay | 搜索防抖延迟（毫秒） | `number` | `500` | 否 |
+| renderListFilter | 自定义过滤函数，参数为 (data, searchValue) | `func` | - | 否 |
+| renderListFilterType | 过滤类型，default 为默认文本匹配，pinyin 为拼音匹配 | `'default' \| 'pinyin'` | `'default'` | 否 |
+| renderSelected | 自定义已选项渲染函数，参数为 item | `func` | `item => item.text` | 否 |
+| renderListItem | 自定义列表项渲染函数，参数为 item | `func` | `item => item.text` | 否 |
+| listHeight | 列表高度 | `string` | `'180px'` | 否 |
+| isGroupList | 是否分组列表 | `bool` | - | 否 |
+| popoverType | 弹出层触发方式 | `'focus' \| 'realFocus'` | `'focus'` | 否 |
+| isInPopup | 是否在弹出层中 | `bool` | - | 否 |
+| isEnableChineseCheck | 是否开启中文输入检查 | `bool` | - | 否 |
+| isKeyboard | 是否启用全键盘操作 | `bool` | - | 否 |
+| onKeyDown | 键盘事件回调 | `func` | `_.noop` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| popupClassName | 弹出层自定义类名 | `string` | - | 否 |
+
+### 方法（通过 ref 调用）
+| 方法 | 说明 |
+|------|------|
+| apiDoFocus | 聚焦到选择框 |
+| apiDoSelectWillActive | 选择键盘高亮的当前项 |
+
+## 示例
+
+### 单选
+```jsx
+const list = [
+  { value: 1, text: '南山' },
+  { value: 2, text: '福田' },
+  { value: 3, text: '罗湖' }
+]
+
+<MoreSelect
+  data={list}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+```
+
+### 多选
+```jsx
+<MoreSelect
+  multiple
+  data={list}
+  selected={mulSelected}
+  onSelect={selected => setMulSelected(selected)}
+/>
+```
+
+### 禁用状态
+```jsx
+<MoreSelect
+  disabled
+  data={list}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+```
+
+### 拼音搜索
+```jsx
+<MoreSelect
+  data={list}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  renderListFilterType='pinyin'
+/>
+```
+
+### 远程搜索（异步）
+```jsx
+<MoreSelect
+  data={list}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  onSearch={searchValue => {
+    return new Promise(resolve => {
+      setTimeout(() => {
+        resolve(list.filter(item => item.text.includes(searchValue)))
+      }, 1000)
+    })
+  }}
+/>
+```
+
+### 远程搜索（同步）
+```jsx
+<MoreSelect
+  data={list}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  onSearch={searchValue => {
+    // 同步直接返回过滤后的数据
+    return list.filter(item => item.text.includes(searchValue))
+  }}
+/>
+```
+
+### 分组列表
+```jsx
+const groupData = [
+  {
+    label: '南山',
+    children: [
+      { value: 1, text: '科技园' },
+      { value: 2, text: '大冲' }
+    ]
+  },
+  {
+    label: '宝安',
+    children: [
+      { value: 21, text: '西乡' },
+      { value: 22, text: '固戍' }
+    ]
+  }
+]
+
+<MoreSelect
+  isGroupList
+  data={groupData}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+```
+
+### 自定义占位文字
+```jsx
+<MoreSelect
+  data={list}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  placeholder='请选择'
+  searchPlaceholder='搜索...'
+/>
+```
+
+## 注意事项
+- `selected` 传入的是 item 对象（包含 value 和 text），而非 value 值，这是为了解耦 selected 和 data 的关系
+- `onSelect` 回调单选时返回单个 item 对象，多选时返回 item 数组
+- `onSearch` 支持同步和异步两种模式：直接返回数组为同步，返回 Promise 为异步
+- `renderListFilterType='pinyin'` 时支持中文拼音搜索（全拼和首字母）
+- `isEnableChineseCheck` 开启后会监听中文输入法的 composition 事件，避免拼音输入时触发搜索
+- 默认搜索防抖延迟为 500ms，可通过 `delay` 属性调整
+- 分组列表数据格式为 `[{ label, children: [{value, text}] }]`
+- `disabledClose` 仅在单选模式下有效，用于隐藏清除按钮
+- 列表打开时会自动滚动到当前选中项