@gmfe/react 2.14.30-alpha.0 → 2.14.31

package/src/component/icon_down_up/README.md

@@ -0,0 +1,43 @@
+# IconDownUp
+
+## 简介
+上下箭头图标组件 - 带有激活状态动画的下拉/上拉箭头图标
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { IconDownUp } from '@gmfe/react'
+
+<IconDownUp active={isOpen} />
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| active | 是否激活（旋转 180 度） | `bool` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<IconDownUp active={isOpen} />
+```
+
+### 自定义样式
+```jsx
+<IconDownUp
+  active={isOpen}
+  className="custom-icon"
+  style={{ fontSize: '12px' }}
+/>
+```
+
+## 注意事项
+- 这是纯图标组件，通常配合 `Popover`、`Selection` 等组件使用
+- 激活状态时箭头会旋转 180 度，通过 CSS transition 实现平滑过渡

package/src/component/image_preview/README.md

@@ -0,0 +1,57 @@
+# ImagePreview
+
+## 简介
+图片预览组件 - 全屏模态框展示大图，支持左右切换、缩略图导航和键盘操作
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { ImagePreview } from '@gmfe/react'
+
+// 点击按钮触发预览
+<button onClick={() => {
+  ImagePreview({
+    images: ['url1.jpg', 'url2.jpg', 'url3.jpg'],
+    thumbnails: ['thumb1.jpg', 'thumb2.jpg', 'thumb3.jpg'],
+    index: 0
+  })
+}}>
+  预览图片
+</button>
+```
+
+## API
+
+### 参数
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| images | 图片 URL 数组 | `array` | - | 是 |
+| thumbnails | 缩略图 URL 数组，底部展示缩略图列表 | `array` | - | 否 |
+| index | 初始展示的图片索引 | `number` | - | 是 |
+
+## 示例
+
+### 基础用法
+```jsx
+ImagePreview({
+  images: ['img1.jpg', 'img2.jpg', 'img3.jpg'],
+  index: 0
+})
+```
+
+### 带缩略图
+```jsx
+ImagePreview({
+  images: ['img1.jpg', 'img2.jpg', 'img3.jpg'],
+  thumbnails: ['thumb1.jpg', 'thumb2.jpg', 'thumb3.jpg'],
+  index: 1
+})
+```
+
+## 注意事项
+- `ImagePreview` 不是 React 组件，而是一个函数调用，内部使用 `CleanModal` 渲染全屏模态框
+- 支持键盘左右箭头键切换图片
+- 缩略图多于一行时，会自动显示左右滚动按钮
+- 点击模态框右上角的关闭按钮可关闭预览

package/src/component/img_uploader/README.md

@@ -0,0 +1,91 @@
+# ImgUploader
+
+## 简介
+图片上传组件 - 支持多图上传、预览、删除和替换，提供统一的图片上传管理能力。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { ImgUploader } from '@gmfe/react'
+
+const handleUpload = files => {
+  // 调用上传接口
+  return Promise.resolve(['https://example.com/image.png'])
+}
+
+<ImgUploader
+  data={['https://example.com/image1.png']}
+  onChange={data => setImageData(data)}
+  onUpload={handleUpload}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 图片 URL 数组 | `array` | - | 是 |
+| onChange | 图片列表变化回调，参数为新的 URL 数组 | `func` | - | 是 |
+| onUpload | 上传回调，参数为 files，需返回 Promise resolve 回 [url] | `func` | - | 是 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| accept | 接受的图片类型 | `string` | `'image/*'` | 否 |
+| multiple | 添加按钮是否支持多图选择 | `bool` | - | 否 |
+| contentSize | 图片尺寸配置 | `shape` | - | 否 |
+| contentSize.width | 图片宽度 | `string` | `'64px'` | 否 |
+| contentSize.height | 图片高度 | `string` | `'64px'` | 否 |
+| desc | 描述文本 | `string` | - | 否 |
+| imgRender | 自定义图片渲染，参数为图片 URL，返回 ReactElement | `func` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+const handleUpload = files => {
+  return Promise.resolve([
+    'https://example.com/image.png'
+  ])
+}
+
+<ImgUploader
+  data={imageList}
+  onUpload={handleUpload}
+  onChange={data => setImageList(data)}
+  accept='image/*'
+  desc='图片尺寸720*720像素，大小小于1M'
+  multiple
+/>
+```
+
+### 禁用状态
+```jsx
+<ImgUploader
+  disabled
+  data={imageList}
+  onUpload={handleUpload}
+  onChange={data => setImageList(data)}
+/>
+```
+
+### 自定义图片尺寸
+```jsx
+<ImgUploader
+  data={imageList}
+  onUpload={handleUpload}
+  onChange={data => setImageList(data)}
+  contentSize={{ width: '100px', height: '100px' }}
+/>
+```
+
+## 注意事项
+- `onUpload` 回调必须返回一个 `Promise`，`resolve` 的结果为上传后的 URL 数组
+- `data` 属性存储的是图片 URL 数组，不是 File 对象
+- 点击已有图片可替换该图片
+- 每张图片右上角有关闭按钮，点击可删除（禁用状态下不显示）
+- `multiple` 属性仅控制"添加"按钮是否支持多选，不影响已有图片
+- 默认图片尺寸为 64px x 64px
+- 图片尺寸和文件大小的验证需在使用时自行处理

package/src/component/input/README.md

@@ -0,0 +1,49 @@
+# Input
+
+## 简介
+输入框组件 - 基于原生 input 封装，添加了 `gm-input` 类名以配合 UI 库的样式。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Input } from '@gmfe/react'
+
+<Input type='text' placeholder='请输入' />
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| className | 自定义类名 | `string` | - | 否 |
+
+除上述属性外，支持原生 input 的所有属性（如 `value`、`onChange`、`placeholder`、`type`、`disabled` 等），会直接透传到原生 input 元素上。
+
+## 示例
+
+### 基础用法
+```jsx
+<Input type='text' placeholder='请输入用户名' />
+```
+
+### 配合 Form 使用
+```jsx
+<FormItem label='名字' required>
+  <Input type='text' value={name} onChange={e => setName(e.target.value)} />
+</FormItem>
+```
+
+### 自定义类名
+```jsx
+<Input className='my-custom-input' placeholder='自定义样式' />
+```
+
+## 注意事项
+- 该组件是对原生 `<input>` 的轻量封装，主要添加了 `gm-input` CSS 类名
+- 所有原生 input 属性均可直接使用
+- 支持 `forwardRef`，可通过 ref 获取原生 input DOM 元素
+- 组件本身不包含样式，需要配合 `@gmfe/react` 的样式体系使用
+- 在 Form 中使用时，FormItem 会自动为 input 添加 `form-control` 类名

package/src/component/input_number/README.md

@@ -0,0 +1,93 @@
+# InputNumber
+
+## 简介
+数字输入框组件 - 限制用户只能输入合法数字，支持精度控制、最大最小值限制和负数输入。提供 `InputNumber`（旧版）和 `InputNumberV2`（推荐）两个版本。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { InputNumberV2 } from '@gmfe/react'
+
+<InputNumberV2
+  value={value}
+  onChange={setValue}
+/>
+```
+
+## API
+
+### InputNumberV2（推荐）
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| value | 当前值 | `number` | `null` | 否 |
+| onChange | 值变化回调 | `func` | 是 | 是 |
+| max | 最大值 | `number` | - | 否 |
+| min | 最小值 | `number` | - | 否 |
+| precision | 精确度，保留几位小数 | `number` | `2` | 否 |
+| placeholder | 占位文字 | `string` | - | 否 |
+| forceInnerValue | 修复场景：删除 1.09 会将 .0 一起删除的问题 | `bool` | `false` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### InputNumber（旧版）
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| value | 当前值 | `number \| string` | - | 否 |
+| onChange | 值变化回调 | `func` | 是 | 是 |
+| max | 最大值 | `number` | - | 否 |
+| min | 最小值 | `number` | - | 否 |
+| precision | 精确度，保留几位小数 | `number` | `2` | 否 |
+| minus | 是否支持输入负数 | `bool` | `false` | 否 |
+| placeholder | 占位文字 | `string` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<InputNumberV2
+  value={value}
+  onChange={setValue}
+/>
+```
+
+### 设置精度
+```jsx
+<InputNumberV2
+  value={value}
+  onChange={setValue}
+  precision={3}
+/>
+```
+
+### 设置最大最小值
+```jsx
+<InputNumberV2
+  value={value}
+  onChange={setValue}
+  min={0}
+  max={100}
+/>
+```
+
+### 旧版支持负数
+```jsx
+import { InputNumber } from '@gmfe/react'
+
+<InputNumber
+  value={value}
+  onChange={setValue}
+  minus
+/>
+```
+
+## 注意事项
+- 推荐使用 `InputNumberV2`，它有更好的状态管理和精度处理
+- `InputNumberV2` 的 `onChange` 回调参数为 `number` 类型（空值时为 `null`）
+- `InputNumber`（旧版）的 `onChange` 回调参数可能是 `string` 或 `number`
+- 两个版本都使用中文句号（`。`）自动转换为小数点（`.`）
+- 在 Form 中使用时，FormItem 会自动为其添加 `form-control` 类名
+- `forceInnerValue` 属性用于修复输入过程中删除字符时的边界情况，如有异常输入行为可尝试开启

package/src/component/layout_root/README.md

@@ -0,0 +1,181 @@
+# LayoutRoot
+
+## 简介
+层级根容器组件 - 管理应用中的弹出层（Popup）、抽屉（Drawer）、模态框（Modal）、提示（Tip）、全屏加载（FullLoading）和顶部进度条（NProgress）等层级组件的统一挂载容器。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import LayoutRoot from '@gmfe/react/lib/layout_root'
+
+// 在应用根节点渲染
+class App extends React.Component {
+  render() {
+    return (
+      <div>
+        {/* 页面内容 */}
+        <LayoutRoot />
+      </div>
+    )
+  }
+}
+
+// 在其他组件中弹出层
+LayoutRoot.setComponent(LayoutRoot.TYPE.DRAWER, <Drawer>内容</Drawer>)
+LayoutRoot.removeComponent(LayoutRoot.TYPE.DRAWER)
+```
+
+## API
+
+### 静态方法
+
+#### `LayoutRoot.setComponent(type, component)`
+设置单例层级组件。
+
+| 参数 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| type | 组件类型 | `TYPE` 枚举值 | 是 |
+| component | React 元素 | `ReactElement` | 是 |
+
+#### `LayoutRoot.removeComponent(type)`
+移除单例层级组件。
+
+| 参数 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| type | 组件类型 | `TYPE` 枚举值 | 是 |
+
+#### `LayoutRoot._setComponentPopup(id, component)`
+添加 Popup 弹出层组件（支持多个同时存在）。
+
+#### `LayoutRoot._removeComponentPopup(id)`
+移除指定 id 的 Popup 弹出层组件。
+
+#### `LayoutRoot._setComponentTip(id, component)`
+添加 Tip 提示组件（支持多个同时存在）。
+
+#### `LayoutRoot._removeComponentTip(id)`
+移除指定 id 的 Tip 提示组件。
+
+#### `LayoutRoot._removeComponentTipAll()`
+移除所有 Tip 提示组件。
+
+### TYPE 枚举
+
+| 值 | 说明 |
+|------|------|
+| `DRAWER` | 抽屉 |
+| `_POPUP` | 弹出层（内部使用） |
+| `MODAL` | 模态框 |
+| `_TIP` | 提示信息（内部使用） |
+| `FULLLOADING` | 全屏加载 |
+| `NPROGRESS` | 顶部进度条 |
+
+## 示例
+
+### 基础用法 —— 在应用入口挂载
+
+```jsx
+import React from 'react'
+import { render } from 'react-dom'
+import LayoutRoot from '@gmfe/react/lib/layout_root'
+import App from './App'
+
+render(
+  <div>
+    <App />
+    <LayoutRoot />
+  </div>,
+  document.getElementById('root')
+)
+```
+
+### 显示全屏加载
+
+```jsx
+import { LayoutRoot, LoadingFullScreen } from '@gmfe/react'
+
+// 显示全屏加载
+LayoutRoot.setComponent(LayoutRoot.TYPE.FULLLOADING, <LoadingFullScreen />)
+
+// 关闭全屏加载
+LayoutRoot.removeComponent(LayoutRoot.TYPE.FULLLOADING)
+```
+
+### 配合异步操作使用
+
+```jsx
+import React from 'react'
+import { LayoutRoot, LoadingFullScreen } from '@gmfe/react'
+
+function SaveButton() {
+  const handleSave = async () => {
+    LayoutRoot.setComponent(LayoutRoot.TYPE.FULLLOADING, <LoadingFullScreen />)
+    try {
+      await api.saveData(formData)
+      Tip.show('保存成功')
+    } catch (e) {
+      Tip.show('保存失败')
+    } finally {
+      LayoutRoot.removeComponent(LayoutRoot.TYPE.FULLLOADING)
+    }
+  }
+
+  return <button onClick={handleSave}>保存</button>
+}
+```
+
+### 使用自定义弹窗内容
+
+```jsx
+// 使用 LayoutRoot 弹出自定义模态框
+LayoutRoot.setComponent(LayoutRoot.TYPE.MODAL, (
+  <Modal
+    title="确认操作"
+    onOK={() => {
+      // 处理逻辑
+      LayoutRoot.removeComponent(LayoutRoot.TYPE.MODAL)
+    }}
+    onHide={() => {
+      LayoutRoot.removeComponent(LayoutRoot.TYPE.MODAL)
+    }}
+  >
+    <div>确定要执行此操作吗？</div>
+  </Modal>
+))
+
+// 关闭模态框
+LayoutRoot.removeComponent(LayoutRoot.TYPE.MODAL)
+```
+
+### 使用 Popup 多实例
+
+```jsx
+// 添加多个 Popup（支持同时存在）
+LayoutRoot._setComponentPopup('popup-1', <Popover target={ref1}>内容1</Popover>)
+LayoutRoot._setComponentPopup('popup-2', <Popover target={ref2}>内容2</Popover>)
+
+// 移除指定 Popup
+LayoutRoot._removeComponentPopup('popup-1')
+```
+
+### 使用 Tip 多实例
+
+```jsx
+// 添加多个 Tip
+LayoutRoot._setComponentTip('tip-1', <Tip>操作成功</Tip>)
+LayoutRoot._setComponentTip('tip-2', <Tip>数据已更新</Tip>)
+
+// 移除指定 Tip
+LayoutRoot._removeComponentTip('tip-1')
+
+// 移除所有 Tip
+LayoutRoot._removeComponentTipAll()
+```
+
+## 注意事项
+- LayoutRoot 必须在应用初始化时挂载，否则调用静态方法时会输出警告：`LayerRoot is uninitialized`
+- 组件有层级关系，从上到下依次为：Popup > Drawer > Modal > Tip > FullLoading > NProgress
+- Popup 和 Tip 支持多个同时存在，Drawer、Modal、FullLoading、NProgress 为单例模式
+- 下划线开头的类型（`_POPUP`、`_TIP`）为内部使用，一般不应直接调用

package/src/component/lazy_img/README.md

@@ -0,0 +1,59 @@
+# LazyImg
+
+## 简介
+懒加载图片组件 - 监听指定容器的滚动事件，当图片进入可视区域时才加载真实图片
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { LazyImg } from '@gmfe/react'
+
+<div id="scroll-container" style={{ height: '500px', overflowY: 'auto' }}>
+  <LazyImg
+    src="real-image.jpg"
+    placeholder="placeholder.jpg"
+    targetId="scroll-container"
+  />
+</div>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| src | 真实图片地址 | `string` | - | 否 |
+| placeholder | 占位图片地址，图片未加载时显示 | `string` | - | 否 |
+| targetId | 指定监听滚动的 DOM 元素的 ID | `string` | - | 是 |
+| delay | 滚动事件防抖延迟时间（毫秒） | `number` | `100` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<div id="scroll-area" style={{ height: '500px', overflowY: 'auto' }}>
+  <LazyImg
+    src="https://example.com/large-image.jpg"
+    placeholder="https://example.com/placeholder.jpg"
+    targetId="scroll-area"
+  />
+</div>
+```
+
+### 自定义防抖延迟
+```jsx
+<LazyImg
+  src="image.jpg"
+  placeholder="placeholder.jpg"
+  targetId="scroll-container"
+  delay={200}
+/>
+```
+
+## 注意事项
+- 必须提供 `targetId`，对应一个存在的 DOM 元素的 ID
+- 如果找不到指定 ID 的 DOM 元素，会在控制台输出错误信息
+- 图片加载完成后会自动移除滚动事件监听，避免内存泄漏

package/src/component/level_list/README.md

@@ -0,0 +1,75 @@
+# LevelList
+
+## 简介
+级联列表组件 - 用于展示多级联动列表，支持鼠标悬浮自动展开和反向排列
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { LevelList } from '@gmfe/react'
+
+<LevelList
+  data={data}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  willActiveSelected={willActiveSelected}
+  onWillActiveSelect={willActiveSelected => setWillActiveSelected(willActiveSelected)}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 数据源，格式：`[{value, text, children}]`，支持多级嵌套 | `array` | - | 是 |
+| selected | 已选中的 value 数组 | `array` | - | 是 |
+| onSelect | 选中回调 | `function` | - | 是 |
+| willActiveSelected | 预激活的 value 数组，用于鼠标悬浮预选 | `array` | - | 是 |
+| onWillActiveSelect | 预激活值变化回调 | `function` | - | 是 |
+| titles | 各级列的标题数组 | `array` | `[]` | 否 |
+| onlySelectLeaf | 是否仅能选择叶子节点（TODO） | `bool` | - | 否 |
+| isReverse | 是否反向排列（从右向左） | `bool` | `false` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| isForFunctionSet | 内部使用，用于 FunctionSet 组件 | `bool` | `false` | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<LevelList
+  data={[
+    {
+      value: '1',
+      text: '南山',
+      children: [
+        { value: '11', text: '科技园' },
+        { value: '12', text: '西丽' }
+      ]
+    }
+  ]}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  willActiveSelected={willActiveSelected}
+  onWillActiveSelect={willActiveSelected => setWillActiveSelected(willActiveSelected)}
+/>
+```
+
+### 反向排列
+```jsx
+<LevelList
+  data={data}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  willActiveSelected={willActiveSelected}
+  onWillActiveSelect={willActiveSelected => setWillActiveSelected(willActiveSelected)}
+  isReverse
+/>
+```
+
+## 注意事项
+- `willActiveSelected` 和 `onWillActiveSelect` 需要配合使用，实现鼠标悬浮预选效果
+- `isReverse` 适用于右对齐的场景