@gmfe/react 2.14.30-alpha.0 → 2.14.30

package/src/component/dialog/README.md

@@ -0,0 +1,149 @@
+# Dialog
+
+## 简介
+对话框组件 - 用于显示模态对话框，支持 alert、confirm、prompt 三种类型，提供 Promise 风格的 API 调用方式
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Dialog } from '@gmfe/react'
+```
+
+## API
+
+### 静态方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `Dialog.alert(options)` | 显示警告对话框，只有确认按钮 | `options: Object` | `Promise` |
+| `Dialog.confirm(options)` | 显示确认对话框，有取消和确认按钮 | `options: Object` | `Promise` |
+| `Dialog.prompt(options)` | 显示输入对话框，包含输入框 | `options: Object` | `Promise` |
+
+### 静态方法 Options
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| title | 对话框标题 | `string` | `'提示'` | 否 |
+| children | 对话框内容 | `any` | - | 否 |
+| type | 对话框类型 | `'alert' \| 'confirm' \| 'prompt'` | `'confirm'` | 否 |
+| size | 对话框尺寸 | `'lg' \| 'md' \| 'sm'` | `'sm'` | 否 |
+| OKBtn | 确认按钮文字，传 `false` 则不显示 | `string \| false` | `'确定'` | 否 |
+| cancelBtn | 取消按钮文字，传 `false` 则不显示 | `string \| false` | `'取消'` | 否 |
+| onOK | 点击确认按钮的回调，`prompt` 类型下会接收输入框的值作为参数；返回 `false` 可阻止关闭，返回 `Promise` 可显示 loading 状态 | `function(value?: string)` | - | 否 |
+| disableMaskClose | 是否禁止点击遮罩关闭 | `bool` | `false` | 否 |
+| promptDefaultValue | prompt 类型下输入框的默认值 | `string` | - | 否 |
+| promptPlaceholder | prompt 类型下输入框的占位文字 | `string` | - | 否 |
+
+### 组件 Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| show | 是否显示 | `bool` | `false` | 是 |
+| title | 对话框标题 | `string` | `'提示'` | 否 |
+| type | 对话框类型 | `string` | `'confirm'` | 否 |
+| size | 对话框尺寸 | `string` | `'md'` | 否 |
+| children | 对话框内容 | `any` | - | 否 |
+| onCancel | 取消回调 | `func` | - | 否 |
+| onOK | 确认回调 | `func` | - | 否 |
+| promptDefaultValue | prompt 类型下输入框的默认值 | `string` | - | 否 |
+| promptPlaceholder | prompt 类型下输入框的占位文字 | `string` | - | 否 |
+| cancelBtn | 取消按钮文字 | `string \| bool` | `'取消'` | 否 |
+| OKBtn | 确认按钮文字 | `string \| bool` | `'确定'` | 否 |
+| disableMaskClose | 是否禁止点击遮罩关闭 | `bool` | `false` | 否 |
+
+## 示例
+
+### 基础用法 - Alert
+
+```jsx
+Dialog.alert({
+  children: '操作成功！'
+}).then(() => {
+  console.log('确认')
+})
+```
+
+### 确认对话框
+
+```jsx
+Dialog.confirm({
+  title: '确认删除',
+  children: '删除后数据将无法恢复，是否继续？'
+}).then(
+  () => console.log('确认'),
+  () => console.log('取消')
+)
+```
+
+### 输入对话框
+
+```jsx
+Dialog.prompt({
+  title: '请输入名称',
+  promptDefaultValue: '默认值',
+  onOK: value => {
+    console.log('输入值：', value)
+  }
+}).then(
+  value => console.log('确认:', value),
+  () => console.log('取消')
+)
+```
+
+### 异步 Loading 状态
+
+```jsx
+Dialog.confirm({
+  title: '提交确认',
+  children: '确定要提交吗？',
+  onOK: () => {
+    return new Promise(resolve => {
+      setTimeout(() => resolve(), 1000)
+    })
+  }
+}).then(() => {
+  console.log('提交成功')
+})
+```
+
+### 嵌套对话框
+
+```jsx
+// 同步嵌套
+const openDialog1 = () => {
+  Dialog.confirm({
+    title: '对话框1',
+    children: '对话框1内容'
+  }).then(() => {
+    openDialog2()
+  })
+}
+
+// 异步嵌套（需要 setTimeout）
+const openAsyncDialog1 = () => {
+  Dialog.confirm({
+    title: '对话框1',
+    children: '对话框1内容',
+    onOK() {
+      return new Promise(resolve => {
+        setTimeout(() => resolve(), 2000)
+      }).then(() => {
+        setTimeout(() => {
+          // 必须加 setTimeout
+          openDialog2()
+        })
+      })
+    }
+  })
+}
+```
+
+## 注意事项
+
+- **推荐使用静态方法调用**：建议始终使用 `Dialog.alert()`、`Dialog.confirm()`、`Dialog.prompt()` 静态方法，而非以组件形式使用。以组件形式调用时会产生警告信息。
+- **Promise 风格**：静态方法返回 `Promise`，`.then()` 对应确认操作，`.catch()` 或第二个参数对应取消操作。
+- **阻止关闭**：`onOK` 回调返回 `false` 可以阻止对话框关闭。
+- **异步操作**：`onOK` 回调返回 `Promise` 时，确认按钮会自动显示 loading 状态，等待 Promise resolve 后关闭对话框。如果 Promise reject，loading 状态会取消。
+- **嵌套对话框**：异步嵌套打开下一个对话框时，必须在 Promise resolve 后使用 `setTimeout` 包裹，否则可能出现渲染问题。

package/src/component/divider/README.md

@@ -0,0 +1,41 @@
+# Divider
+
+## 简介
+分割线组件 - 用于在内容区域之间插入带文字或不带文字的水平分割线。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import Divider from '@gmfe/react/lib/divider'
+
+<Divider>分割文字</Divider>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| children | 分割线中的内容，传入字符串时使用默认字号，传入 React 元素时自定义渲染 | `any` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+// 带文字的分割线
+<Divider>文字内容</Divider>
+
+// 不带文字的分割线
+<Divider />
+
+// 自定义内容
+<Divider>
+  <span style={{ color: 'red' }}>自定义内容</span>
+</Divider>
+```
+
+## 注意事项
+- children 传入字符串时，会使用 `gm-text-16` 样式类渲染
+- children 传入非字符串（React 元素等）时，会直接渲染原始内容

package/src/component/drawer/README.md

@@ -0,0 +1,83 @@
+# Drawer
+
+## 简介
+抽屉组件 - 从页面底部滑出的全宽内容面板，支持自定义样式和遮罩层
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Drawer } from '@gmfe/react'
+```
+
+## API
+
+### 组件 Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| children | 抽屉内容 | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| onHide | 关闭回调 | `func` | `_.noop` | 否 |
+| opacityMask | 是否使用半透明遮罩 | `bool` | `false` | 否 |
+
+### 静态方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `Drawer.render(props)` | 命令式渲染抽屉 | `props: Object` | - |
+| `Drawer.hide()` | 隐藏抽屉 | - | - |
+
+## 示例
+
+### 基础用法 - 命令式渲染
+
+```jsx
+import { Drawer } from '@gmfe/react'
+
+// 显示抽屉
+Drawer.render({
+  children: (
+    <div style={{ padding: 20 }}>
+      <h3>抽屉标题</h3>
+      <p>抽屉内容区域</p>
+      <button onClick={() => Drawer.hide()}>关闭</button>
+    </div>
+  )
+})
+
+// 隐藏抽屉
+Drawer.hide()
+```
+
+### 自定义样式
+
+```jsx
+Drawer.render({
+  style: {
+    maxHeight: '50vh'
+  },
+  className: 'custom-drawer',
+  children: <div>自定义样式的抽屉</div>,
+  onHide: () => Drawer.hide()
+})
+```
+
+### 半透明遮罩
+
+```jsx
+Drawer.render({
+  opacityMask: true,
+  children: <div>带半透明遮罩的抽屉</div>
+})
+```
+
+## 注意事项
+
+- Drawer 推荐使用静态方法 `Drawer.render()` 和 `Drawer.hide()` 进行命令式调用，而非作为 React 组件直接使用。
+- 按下 `Esc` 键可以关闭抽屉（通过 `onHide` 回调）。
+- 点击遮罩层区域也会触发关闭操作。
+- `opacityMask` 设置为 `true` 时，遮罩变为半透明样式，同时抽屉内容区域会显示边框和底部阴影。
+- Drawer 内容区域滚动时会触发 `DRAWER_SCROLL` 事件，可用于联动其他组件。

package/src/component/drop_down/README.md

@@ -0,0 +1,105 @@
+# DropDown
+
+## 简介
+下拉菜单组件 - 点击触发弹出下拉列表，支持普通模式和分割按钮模式。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { DropDown, DropDownItem, DropDownItems } from '@gmfe/react/lib/drop_down'
+
+<DropDown
+  popup={
+    <DropDownItems>
+      <DropDownItem onClick={() => console.log('选项1')}>选项1</DropDownItem>
+      <DropDownItem onClick={() => console.log('选项2')}>选项2</DropDownItem>
+    </DropDownItems>
+  }
+>
+  <Button>下拉菜单</Button>
+</DropDown>
+```
+
+## API
+
+### DropDown Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| popup | 弹出层内容 | `ReactElement` | - | 是 |
+| split | 是否为分割按钮模式 | `bool` | `false` | 否 |
+| right | 弹出层是否右对齐（非 split 模式有效） | `bool` | - | 否 |
+| cartClassName | 分割按钮的触发按钮类名（split 模式有效） | `string` | - | 否 |
+| children | 触发下拉菜单的元素 | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### DropDownItem Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| active | 是否激活状态 | `bool` | - | 否 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| onClick | 点击回调 | `() => void` | - | 是 |
+| children | 菜单项内容 | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### DropDownItems Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| children | 菜单项列表（DropDownItem 组件） | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<DropDown
+  popup={
+    <DropDownItems>
+      <DropDownItem onClick={() => console.log('选项1')}>选项1</DropDownItem>
+      <DropDownItem onClick={() => console.log('选项2')}>选项2</DropDownItem>
+    </DropDownItems>
+  }
+>
+  <span>下拉菜单</span>
+</DropDown>
+```
+
+### 分割按钮模式
+```jsx
+<DropDown
+  split
+  popup={
+    <DropDownItems>
+      <DropDownItem onClick={() => console.log('选项1')}>选项1</DropDownItem>
+      <DropDownItem onClick={() => console.log('选项2')}>选项2</DropDownItem>
+    </DropDownItems>
+  }
+>
+  <Button>主要操作</Button>
+</DropDown>
+```
+
+### 禁用菜单项
+```jsx
+<DropDown
+  popup={
+    <DropDownItems>
+      <DropDownItem onClick={() => {}}>正常选项</DropDownItem>
+      <DropDownItem disabled onClick={() => {}}>禁用选项</DropDownItem>
+      <DropDownItem active onClick={() => {}}>激活选项</DropDownItem>
+    </DropDownItems>
+  }
+>
+  <Button>下拉菜单</Button>
+</DropDown>
+```
+
+## 注意事项
+- DropDown 底层使用 Popover 组件实现
+- 普通模式下，点击弹出层内的内容会自动关闭弹出层
+- 分割按钮模式下，触发按钮和下拉箭头是分开的
+- DropDownItem 设置 `disabled` 后，点击不会触发 onClick 回调

package/src/component/drop_select/README.md

@@ -0,0 +1,146 @@
+# DropSelect
+
+## 简介
+下拉选择面板组件 - 带表格结构的下拉选择组件，支持多列展示、自定义渲染、键盘导航和操作按钮等功能。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import DropSelect from '@gmfe/react/lib/drop_select'
+
+<DropSelect
+  show={isVisible}
+  data={{
+    loading: false,
+    list: [{ id: 1, name: '张三', age: 25 }, { id: 2, name: '李四', age: 30 }],
+    columns: [
+      { field: 'name', name: '姓名' },
+      { field: 'age', name: '年龄' }
+    ],
+    actions: [{ text: '删除', onClick: (row) => handleDelete(row) }]
+  }}
+  onHide={() => setVisible(false)}
+  onEnter={(index) => handleEnter(index)}
+>
+  <input type="text" placeholder="请输入..." />
+</DropSelect>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| show | 是否显示下拉面板 | `bool` | - | 是 |
+| data | 下拉面板数据 | `object` | - | 否 |
+| onEnter | 键盘回车回调，参数为当前激活的列表索引 | `(index: number) => void` | `() => console.log(...)` | 否 |
+| onHide | 隐藏下拉面板回调（点击外部区域或按 Esc 键时触发） | `() => void` | - | 否 |
+| children | 触发元素（如 input） | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+
+### data 对象结构
+
+| 字段 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| loading | 是否加载中 | `bool` | `false` |
+| list | 数据列表 | `array` | `[]` |
+| columns | 列配置 | `array` | `[]` |
+| actions | 操作按钮配置 | `array` | `[]` |
+
+#### columns 数组项
+
+| 字段 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| field | 对应 list 中的字段名 | `string` | 否 |
+| name | 列标题 | `string` | 否 |
+| render | 自定义单元格渲染，参数为 `(value, rowData, rowIndex)` | `(value, rowData, rowIndex) => ReactNode` | 否 |
+
+#### actions 数组项
+
+| 字段 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| text | 按钮文字 | `string` | 否 |
+| onClick | 点击回调，参数为当前行数据 | `(rowData) => void` | 否 |
+| getDisabled | 判断按钮是否禁用 | `(rowData, rowIndex) => bool` | 否 |
+| className | 按钮自定义类名 | `string` | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+const [visible, setVisible] = useState(false)
+
+<DropSelect
+  show={visible}
+  data={{
+    list: [
+      { id: 1, name: '张三', age: 25 },
+      { id: 2, name: '李四', age: 30 }
+    ],
+    columns: [
+      { field: 'name', name: '姓名' },
+      { field: 'age', name: '年龄' }
+    ]
+  }}
+  onHide={() => setVisible(false)}
+  onEnter={(index) => {
+    const item = list[index]
+    // 处理回车选中
+  }}
+>
+  <input type="text" placeholder="请输入..." />
+</DropSelect>
+```
+
+### 带操作按钮
+```jsx
+<DropSelect
+  show={visible}
+  data={{
+    list: dataList,
+    columns: [
+      { field: 'name', name: '姓名' },
+      { field: 'age', name: '年龄' }
+    ],
+    actions: [
+      {
+        text: '查看',
+        onClick: (rowData) => viewDetail(rowData)
+      },
+      {
+        text: '删除',
+        onClick: (rowData) => handleDelete(rowData),
+        getDisabled: (rowData) => rowData.isDefault
+      }
+    ]
+  }}
+  onHide={() => setVisible(false)}
+>
+  <input type="text" />
+</DropSelect>
+```
+
+### 加载状态
+```jsx
+<DropSelect
+  show={true}
+  data={{
+    loading: true,
+    list: [],
+    columns: []
+  }}
+  onHide={() => {}}
+>
+  <input type="text" />
+</DropSelect>
+```
+
+## 注意事项
+- 点击下拉面板外部区域会自动隐藏面板并触发 `onHide`
+- 按 Esc 键也会触发 `onHide`
+- 支持键盘导航：上/下方向键切换激活项，回车键确认选择
+- 当前列表项为空时，键盘导航无效
+- 激活的列表项会自动滚动到可视区域（`scrollIntoViewIfNeeded`）
+- `onEnter` 默认只会在控制台打印 index，建议传入自定义处理函数

package/src/component/dropper/README.md

@@ -0,0 +1,55 @@
+# Dropper
+
+## 简介
+文件拖放组件 - 支持拖放上传和点击选择文件
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Dropper } from '@gmfe/react'
+
+<Dropper
+  onDrop={(files, e) => console.log(files)}
+  accept="image/*"
+>
+  <div>点击或拖拽文件到此处上传</div>
+</Dropper>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| multiple | 是否支持多文件选择 | `bool` | `false` | 否 |
+| onDrop | 文件放置/选择后的回调，参数为 `(files, event)`，`files` 数组中每项包含 `preview` 属性（blob URL） | `function` | - | 是 |
+| accept | 接受的文件类型，同 `<input type="file">` 的 accept 属性 | `string` | - | 否 |
+| children | 自定义内容区域 | `any` | - | 否 |
+| className | 自定义内容区域的类名，默认使用 `gm-dropper-default` | `string` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<Dropper onDrop={(files) => handleFiles(files)}>
+  <div>点击或拖拽文件到此处</div>
+</Dropper>
+```
+
+### 多文件上传
+```jsx
+<Dropper
+  multiple
+  onDrop={(files) => handleFiles(files)}
+  accept="image/*"
+>
+  <div>支持多文件图片上传</div>
+</Dropper>
+```
+
+## 注意事项
+- 在微信浏览器中 `multiple` 属性无效，会自动禁用
+- 每个文件对象会自动添加 `preview` 属性，值为 `URL.createObjectURL(file)` 生成的 blob URL
+- 使用完毕后建议手动释放 blob URL 以避免内存泄漏

package/src/component/editable_text/README.md

@@ -0,0 +1,68 @@
+# EditableText
+
+## 简介
+可编辑文本组件 - 点击文本切换为编辑模式，支持确认和取消操作
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { EditableText } from '@gmfe/react'
+
+<EditableText
+  content="可编辑的文本"
+  onOk={value => console.log('确认:', value)}
+  onCancel={() => console.log('取消')}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| content | 组件显示的文本内容 | `string` | - | 是 |
+| onOk | 确认回调，参数为编辑后的文本值 | `function` | - | 否 |
+| onCancel | 取消回调 | `function` | - | 否 |
+| disabled | 是否禁用编辑 | `bool` | - | 否 |
+| children | 自定义显示内容，优先级高于 `content` | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<EditableText
+  content="可编辑的文本"
+  onOk={value => setContent(value)}
+/>
+```
+
+### 禁用编辑
+```jsx
+<EditableText
+  content="不可编辑"
+  onOk={value => setContent(value)}
+  disabled
+/>
+```
+
+### 自定义显示内容
+```jsx
+<EditableText onOk={value => setContent(value)} content={content}>
+  <Popover
+    showArrow
+    top
+    type="hover"
+    popup={<div className="gm-border gm-padding-5">来源：{content}</div>}
+  >
+    <div className="gm-inline-block">{content}</div>
+  </Popover>
+</EditableText>
+```
+
+## 注意事项
+- 按回车键可确认编辑
+- 点击确认按钮或输入框失焦时触发取消操作（失焦有 300ms 延迟以避免与按钮点击冲突）
+- 禁用状态下不会显示编辑图标