@gmfe/react 2.14.30-alpha.0 → 2.14.31

package/src/component/price/README.md

@@ -0,0 +1,72 @@
+# Price
+
+## 简介
+价格显示组件 - 带货币符号的价格格式化组件，支持千分符、精度控制、多币种和分单位
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Price } from '@gmfe/react'
+
+<Price value={10839} />
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| value | 价格数值（负数会自动显示负号） | `number` | - | 是 |
+| precision | 保留几位小数 | `number` | `2` | 否 |
+| useGrouping | 是否使用千分符 | `bool` | `true` | 否 |
+| currencyScale | 货币符号的缩放大小（em 单位），大于 1 时按 1em 显示 | `number` | `0.85` | 否 |
+| keepZero | 是否保留小数点后无效的零 | `bool` | `true` | 否 |
+| isFenUnit | value 是否为分单位（会自动除以 100） | `bool` | `false` | 否 |
+| feeType | 多币种类型标识 | `string` | `''` | 否 |
+
+### 静态方法
+| 方法 | 说明 |
+|------|------|
+| `Price.setCurrency(symbol)` | 设置货币符号 |
+| `Price.getCurrency(type?)` | 获取货币符号 |
+| `Price.setUnit(unit)` | 设置货币单位 |
+| `Price.getUnit(type?)` | 获取货币单位 |
+| `Price.setCurrencyList(list)` | 设置多币种列表，格式：`[{symbol, type, unit}]` |
+
+## 示例
+
+### 基础用法
+```jsx
+<Price value={10839} />       // ¥10,839.00
+<Price value={-10} />         // -¥10.00
+<Price value={10000000} />    // ¥10,000,000.00
+```
+
+### 分单位
+```jsx
+<Price isFenUnit value={1234} /> // ¥12.34
+```
+
+### 自定义货币符号缩放
+```jsx
+<Price value={40002288} currencyScale={0.8} />
+```
+
+### 多币种
+```jsx
+// 先设置币种列表
+Price.setCurrencyList([
+  { symbol: '￥', type: 'CNY', unit: '元' },
+  { symbol: '$', type: 'USD', unit: 'dollar' }
+])
+
+// 使用
+<Price value={100} feeType="USD" /> // $100.00
+```
+
+## 注意事项
+- 货币符号通过 `Price.setCurrency()` 设置后会持久化到 localStorage
+- 货币符号变化时会自动刷新所有 Price 组件
+- `feeType` 和静态方法配合使用可实现多币种切换

package/src/component/progress/README.md

@@ -0,0 +1,98 @@
+# Progress
+
+## 简介
+进度条组件 - 用于展示操作进度的线性进度条，支持自定义颜色、粗细、文字显示位置和状态
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Progress } from '@gmfe/react'
+```
+
+## API
+
+### Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| percentage | 进度百分比，取值范围 0~100 | `number` | - | 是 |
+| text | 自定义显示文字，不传则显示百分比 | `string` | - | 否 |
+| status | 进度条状态 | `'success' \| 'exception'` | - | 否 |
+| strokeWidth | 进度条高度（像素） | `number` | - | 否 |
+| textInside | 是否将文字显示在进度条内部 | `bool` | `false` | 否 |
+| textInsideFix | 文字在进度条内部的对齐方式（需配合 `textInside` 使用） | `'left' \| 'right' \| 'center'` | - | 否 |
+| showText | 是否显示文字 | `bool` | `true` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| textColor | 文字颜色 | `string` | - | 否 |
+| strokeColor | 进度条颜色 | `string` | - | 否 |
+| bgColor | 进度条背景颜色 | `string` | - | 否 |
+
+## 示例
+
+### 基础用法
+
+```jsx
+<Progress percentage={30} />
+<Progress percentage={70} />
+<Progress percentage={100} />
+```
+
+### 不显示文字
+
+```jsx
+<Progress percentage={50} showText={false} />
+```
+
+### 自定义文字
+
+```jsx
+<Progress percentage={20} text='20斤/100斤' strokeWidth={18} />
+```
+
+### 文字内置
+
+```jsx
+// 文字显示在进度条内部
+<Progress percentage={70} textInside strokeWidth={18} />
+```
+
+### 文字内对齐方式
+
+```jsx
+<Progress percentage={70} textInside textInsideFix='center' strokeWidth={18} />
+<Progress percentage={70} textInside textInsideFix='left' strokeWidth={18} />
+<Progress percentage={70} textInside textInsideFix='right' strokeWidth={18} />
+```
+
+### 自定义颜色
+
+```jsx
+<Progress
+  percentage={70}
+  textInside
+  textInsideFix='center'
+  strokeWidth={18}
+  textColor='black'
+  strokeColor='orange'
+  bgColor='lightgray'
+/>
+```
+
+### 状态展示
+
+```jsx
+// 成功状态 - 显示绿色和对勾图标
+<Progress percentage={100} status='success' />
+
+// 异常状态 - 显示红色和错误图标
+<Progress percentage={50} status='exception' />
+```
+
+## 注意事项
+
+- `percentage` 为必填属性，取值范围 0~100。
+- 设置 `status='success'` 时进度条变为绿色并显示对勾图标，`status='exception'` 时进度条变为红色并显示错误图标。状态图标仅在文字显示在进度条外部（`textInside=false`）时可见。
+- `textInsideFix` 仅在 `textInside` 为 `true` 时生效，可控制文字在进度条内部的对齐方向。
+- `textInside` 设为 `true` 时建议同时设置 `strokeWidth` 以确保进度条有足够的高度容纳文字。

package/src/component/progress_circle/README.md

@@ -0,0 +1,92 @@
+# ProgressCircle
+
+## 简介
+环形进度条组件 - 使用 SVG 绘制的圆环进度指示器，支持自定义大小、颜色、线宽和文字位置
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { ProgressCircle } from '@gmfe/react'
+```
+
+## API
+
+### Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| percentage | 进度百分比，取值范围 0~100 | `number` | `0` | 否 |
+| text | 自定义显示文字，不传则显示百分比 | `string` | - | 否 |
+| showText | 是否显示文字 | `bool` | `true` | 否 |
+| textPosition | 文字显示位置 | `'left' \| 'center' \| 'right'` | `'center'` | 否 |
+| status | 进度条状态 | `'success' \| 'exception'` | `'success'` | 否 |
+| size | 圆环整体尺寸（像素） | `string \| number` | `'40'` | 否 |
+| lineWidth | 圆环线条宽度 | `string \| number` | `'60'` | 否 |
+| progressColor | 进度条颜色 | `string` | - | 否 |
+| bgColor | 背景圆环颜色 | `string` | `'#e4e8f1'` | 否 |
+
+## 示例
+
+### 基础用法
+
+```jsx
+<ProgressCircle percentage={60} />
+<ProgressCircle percentage={80} status='exception' />
+```
+
+### 不显示文字
+
+```jsx
+<ProgressCircle percentage={50} showText={false} />
+<ProgressCircle percentage={80} status='exception' showText={false} />
+```
+
+### 自定义文字和位置
+
+```jsx
+// 文字在右侧
+<ProgressCircle percentage={75} textPosition='right' />
+
+// 文字在左侧，自定义文字
+<ProgressCircle percentage={60} textPosition='left' text='60/100' />
+```
+
+### 自定义大小和线宽
+
+```jsx
+// 大尺寸
+<ProgressCircle percentage={80} size='100' />
+
+// 细线条
+<ProgressCircle percentage={80} size='100' lineWidth={20} />
+```
+
+### 自定义颜色
+
+```jsx
+<ProgressCircle
+  percentage={80}
+  size='100'
+  lineWidth={20}
+  progressColor='orange'
+/>
+
+<ProgressCircle
+  percentage={80}
+  size='100'
+  lineWidth={20}
+  progressColor='orange'
+  bgColor='gray'
+/>
+```
+
+## 注意事项
+
+- ProgressCircle 使用 SVG 绘制，内部固定 viewBox 为 `300x300`，通过 `size` 属性控制实际渲染尺寸。
+- 默认状态为 `success`（绿色），可设为 `exception`（红色）来表示异常状态。
+- `textPosition='center'` 时文字渲染在圆环中央（SVG text 元素），`left` 和 `right` 时文字显示在圆环外侧。
+- `lineWidth` 控制圆环线条的粗细，值越大圆环越粗。当线条较粗时，建议使用较小的值以避免线条溢出。
+- `size` 和 `lineWidth` 支持 `string` 和 `number` 类型。
+- 百分比超过 100 时会被自动限制为 100。

package/src/component/radio/README.md

@@ -0,0 +1,101 @@
+# Radio
+
+## 简介
+单选框组件 - 用于单选场景，支持单个使用和分组使用（RadioGroup）。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Radio, RadioGroup } from '@gmfe/react'
+
+// 单个使用
+<Radio checked onChange={onChange}>选项</Radio>
+
+// 分组使用
+<RadioGroup name='city' value={value} onChange={setValue}>
+  <Radio value={1}>广州</Radio>
+  <Radio value={2}>深圳</Radio>
+  <Radio value={3}>成都</Radio>
+</RadioGroup>
+```
+
+## API
+
+### Radio Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| checked | 是否选中 | `bool` | - | 否 |
+| onChange | 变化回调 | `func` | `_.noop` | 否 |
+| onClick | 点击回调 | `func` | `_.noop` | 否 |
+| value | 选项值，配合 RadioGroup 使用 | `any` | - | 否 |
+| children | 显示文本 | `any` | - | 否 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| inline | 是否行内显示 | `bool` | - | 否 |
+| block | 是否整行可点击 | `bool` | - | 否 |
+| name | input name 属性 | `string` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### RadioGroup Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| name | 表单名称，必填 | `string` | - | 是 |
+| value | 当前选中的值 | `any` | - | 否 |
+| onChange | 变化回调，参数为选中的 value | `func` | `_.noop` | 否 |
+| inline | 是否行内显示 | `bool` | - | 否 |
+| children | Radio 子组件 | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<Radio checked>选中状态</Radio>
+<Radio>未选中状态</Radio>
+```
+
+### 禁用状态
+```jsx
+<Radio checked disabled>选中禁用</Radio>
+<Radio disabled>未选中禁用</Radio>
+```
+
+### 行内显示
+```jsx
+<Radio checked inline>选项1</Radio>
+<Radio inline>选项2</Radio>
+```
+
+### 整行可点击
+```jsx
+<Radio
+  block
+  checked={checked}
+  onChange={() => setChecked(!checked)}
+>
+  整行都可以点击
+</Radio>
+```
+
+### 分组使用
+```jsx
+<RadioGroup
+  name='city'
+  value={value}
+  onChange={value => console.log(value)}
+>
+  <Radio value={1}>广州</Radio>
+  <Radio value={2}>深圳</Radio>
+  <Radio value={3} disabled>成都</Radio>
+</RadioGroup>
+```
+
+## 注意事项
+- `RadioGroup` 的 `name` 属性为必填项
+- `RadioGroup` 内部会自动管理选中状态，通过 `value` 和 `onChange` 控制受控模式
+- `block` 模式下整行都可以触发选中操作
+- 非行内模式下，每个 Radio 独占一行
+- `RadioGroup` 的 `onChange` 回调参数为选中项的 `value` 值

package/src/component/recommend_input/README.md

@@ -0,0 +1,75 @@
+# RecommendInput
+
+## 简介
+推荐输入组件 - 输入时展示推荐列表的下拉输入框，支持拼音搜索过滤
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { RecommendInput } from '@gmfe/react'
+
+<RecommendInput
+  data={[{ text: '选项1' }, { text: '选项2' }]}
+  value={value}
+  onChange={value => setValue(value)}
+  placeholder="请输入"
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 推荐列表的数据，格式：`[{ text: 'text1' }, { text: 'text2' }, ...]` | `array` | - | 是 |
+| value | 输入框的值 | `string` | - | 是 |
+| onChange | 值变化回调，参数为 `value` | `function` | - | 是 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| listHeight | 推荐列表高度 | `string` | `'180px'` | 否 |
+| inputMaxLength | 输入框最大字符数 | `number` | - | 否 |
+| placeholder | 占位文本 | `string` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<RecommendInput
+  data={[
+    { text: '选项1' },
+    { text: '选项2' },
+    { text: '选项3' }
+  ]}
+  value={value}
+  onChange={value => setValue(value)}
+  placeholder="请输入"
+/>
+```
+
+### 禁用状态
+```jsx
+<RecommendInput
+  data={data}
+  value={value}
+  onChange={value => setValue(value)}
+  disabled
+/>
+```
+
+### 限制输入长度
+```jsx
+<RecommendInput
+  data={data}
+  value={value}
+  onChange={value => setValue(value)}
+  inputMaxLength={15}
+/>
+```
+
+## 注意事项
+- 输入时支持拼音搜索过滤推荐列表
+- 选择推荐项后会自动关闭下拉列表
+- 输入框右侧有清除按钮，点击可清空输入内容
+- 弹出框使用 `realFocus` 触发模式，输入框获取焦点时自动展示

package/src/component/select/README.md

@@ -0,0 +1,120 @@
+# Select
+
+## 简介
+下拉选择组件 - 通过弹出层展示选项列表，支持键盘上下键选择、禁用选项和清除功能。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Select } from '@gmfe/react'
+
+const list = [
+  { value: 0, text: '南山' },
+  { value: 1, text: '福田' },
+  { value: 2, text: '宝安' },
+  { value: 3, text: '宝安不可用', disabled: true },
+  { value: 4, text: '罗湖' }
+]
+
+<Select
+  data={list}
+  value={value}
+  onChange={setValue}
+/>
+```
+
+## API
+
+### Select Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 选项数据，每项包含 text、value、disabled | `array` | - | 是 |
+| value | 当前选中的值 | `any` | - | 是 |
+| onChange | 选择变化回调，参数为选中的 value | `func` | - | 是 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| canShowClose | 是否显示清除按钮 | `bool` | `false` | 否 |
+| clean | 清洁模式 | `bool` | - | 否 |
+| listProps | 传递给列表组件的属性 | `object` | - | 否 |
+| popoverType | 弹出层触发方式 | `'focus' \| 'realFocus'` | - | 否 |
+| isInPopup | 是否在弹出层中 | `bool` | - | 否 |
+| onKeyDown | 键盘事件回调 | `func` | `_.noop` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| children | 兼容旧用法，使用 Option 子组件 | `any` | - | 否 |
+
+### Option Props（已废弃）
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| value | 选项值 | `any` | - | 否 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| children | 选项显示文本 | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### 方法（通过 ref 调用）
+| 方法 | 说明 |
+|------|------|
+| apiDoFocus | 聚焦到选择框 |
+| apiDoSelectWillActive | 选择键盘高亮的当前项 |
+
+## 示例
+
+### 基础用法
+```jsx
+const list = [
+  { value: 0, text: '南山' },
+  { value: 1, text: '福田' },
+  { value: 2, text: '宝安' }
+]
+
+<Select
+  data={list}
+  value={value}
+  onChange={setValue}
+/>
+```
+
+### 禁用选项
+```jsx
+const list = [
+  { value: 0, text: '南山' },
+  { value: 1, text: '福田' },
+  { value: 2, text: '宝安', disabled: true }
+]
+
+<Select
+  data={list}
+  value={value}
+  onChange={setValue}
+/>
+```
+
+### 可清除
+```jsx
+<Select
+  data={list}
+  value={value}
+  onChange={setValue}
+  canShowClose
+/>
+```
+
+### 清洁模式
+```jsx
+<Select
+  clean
+  data={list}
+  value={value}
+  onChange={setValue}
+/>
+```
+
+## 注意事项
+- 推荐使用 `data` 属性传入选项数据，`Option` 子组件方式已废弃
+- 选项数据格式为 `[{ value, text, disabled }]`，其中 `disabled` 可选
+- `canShowClose` 属性允许用户清除已选值
+- 支持键盘上下键切换选项
+- 列表最大高度为 `250px`，超出部分可滚动
+- 弹出层默认使用 Popover 组件

package/src/component/selection/README.md

@@ -0,0 +1,87 @@
+# Selection
+
+## 简介
+选择器基础组件 - 可作为输入框形式的选择器，支持清除、干净模式等多种形态
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Selection } from '@gmfe/react'
+
+<Selection
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  placeholder="请选择"
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| selected | 单选情况为 `null` 或 `{value, text}` 对象 | `any` | - | 否 |
+| onSelect | 选中回调 | `function` | - | 是 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| renderSelected | 自定义选中项的展示，参数为 `selected` | `function` | `(item) => item.text` | 否 |
+| placeholder | 占位文本 | `string` | - | 否 |
+| funIcon | 代替默认的箭头图标 | `element` | - | 否 |
+| clean | 干净模式，隐藏右侧图标和关闭按钮 | `bool` | `false` | 否 |
+| disabledClose | 禁用关闭（x）按钮 | `bool` | `false` | 否 |
+| onKeyDown | 键盘事件回调 | `function` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| isForSelect | 给 Select 定制的标记，使用 div 代替 input | `bool` | `false` | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<Selection
+  onSelect={selected => console.log(selected)}
+  placeholder="请选择"
+/>
+```
+
+### 已选中状态
+```jsx
+<Selection
+  selected={{ value: 0, text: '选中项' }}
+  onSelect={selected => console.log(selected)}
+/>
+```
+
+### 自定义选中项展示
+```jsx
+<Selection
+  selected={{ value: 0, text: '选中项' }}
+  onSelect={selected => console.log(selected)}
+  renderSelected={item => item.text + 'lalala'}
+/>
+```
+
+### 干净模式
+```jsx
+<Selection
+  clean
+  selected={{ value: 0, text: '选中项' }}
+  onSelect={selected => console.log(selected)}
+  placeholder="请选择"
+/>
+```
+
+### 禁用关闭按钮
+```jsx
+<Selection
+  disabledClose
+  selected={{ value: 0, text: '选中项' }}
+  onSelect={selected => console.log(selected)}
+/>
+```
+
+## 注意事项
+- 这是基础组件，通常不单独使用，而是作为 `LevelSelect`、`TimeSpanPicker` 等组件的内部组件
+- 选中后显示关闭按钮（x），点击可清除选中状态
+- 默认右侧有上下箭头图标，选中状态下箭头图标会左移