@gmfe/react 2.14.29 → 2.14.30

package/src/component/cascader/README.md

@@ -0,0 +1,139 @@
+# Cascader
+
+## 简介
+级联选择组件 - 支持多级数据联动选择，可搜索过滤，提供 Cascader（基础级联）和 CascaderSelect（可选多级值）两个组件。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Cascader } from '@gmfe/react'
+
+const data = [
+  {
+    value: '110000',
+    name: '北京市',
+    children: [
+      {
+        value: '150600000000',
+        name: '东城区',
+        children: [
+          { value: '150600800000', name: '东单' },
+          { value: '150600900000', name: '东四' }
+        ]
+      }
+    ]
+  }
+]
+
+<Cascader
+  data={data}
+  value={selected}
+  onChange={ids => setSelected(ids)}
+/>
+```
+
+## API
+
+### Cascader Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 级联数据，格式 `[{value, name, children: [{...}]}]` | `array` | - | 是 |
+| value | 当前选中的值数组，如 `[1, 2, 3]` | `array` | - | 否 |
+| defaultValue | 默认选中的值数组 | `array` | - | 否 |
+| onChange | 选择变化回调，参数为选中的值数组 | `func` | `_.noop` | 否 |
+| inputProps | 传递给内部 input 的属性（没有 children 时有效） | `object` | `{}` | 否 |
+| valueRender | 自定义显示值的渲染函数 | `func` | - | 否 |
+| children | 自定义触发元素 | `any` | - | 否 |
+| disabled | 是否禁用 | `bool` | `false` | 否 |
+| filtrable | 是否可搜索 | `bool` | - | 否 |
+| onlyChildSelectable | 是否只允许选择末级节点（有 children 则清空输入框） | `bool` | `false` | 否 |
+| popoverStyle | 弹出层样式 | `object` | - | 否 |
+| className | 弹出层自定义类名 | `string` | - | 否 |
+| style | 弹出层自定义样式 | `object` | - | 否 |
+
+### CascaderSelect Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 级联数据，格式同 Cascader | `array` | - | 是 |
+| selected | 已选中的项数组（每项为完整的 value 对象数组） | `array` | - | 否 |
+| onSelect | 选择回调，单选返回单个值，多选返回数组 | `func` | - | 是 |
+| multiple | 是否多选 | `bool` | - | 否 |
+| selectedRender | 自定义已选项渲染函数 | `func` | - | 否 |
+| inputProps | 传递给内部 Cascader input 的属性 | `object` | `{}` | 否 |
+| disabled | 是否禁用 | `bool` | `false` | 否 |
+| valueRender | 自定义 Cascader 显示值渲染函数 | `func` | - | 否 |
+| filtrable | 是否可搜索 | `bool` | `false` | 否 |
+| onlyChildSelectable | 是否只允许选择末级节点 | `bool` | `false` | 否 |
+
+## 示例
+
+### 基础级联选择
+```jsx
+const data = [
+  {
+    value: '110000',
+    name: '北京市',
+    children: [
+      {
+        value: '150600000000',
+        name: '东城区',
+        children: [
+          { value: '150600800000', name: '东单' },
+          { value: '150600900000', name: '东四' }
+        ]
+      }
+    ]
+  }
+]
+
+<Cascader
+  data={data}
+  value={selected}
+  onChange={ids => setSelected(ids)}
+/>
+```
+
+### 可搜索级联
+```jsx
+<Cascader
+  filtrable
+  data={data}
+  value={selected}
+  onChange={ids => setSelected(ids)}
+/>
+```
+
+### 只允许选择末级节点
+```jsx
+<Cascader
+  filtrable
+  onlyChildSelectable
+  data={data}
+  value={selected}
+  onChange={ids => setSelected(ids)}
+/>
+```
+
+### CascaderSelect 多选
+```jsx
+import { CascaderSelect } from '@gmfe/react'
+
+<CascaderSelect
+  multiple
+  data={data}
+  selected={selectedItems}
+  onSelect={items => setSelectedItems(items)}
+/>
+```
+
+## 注意事项
+- `data` 数据格式要求每项包含 `value`、`name`，子级数据放在 `children` 中
+- `value` 属性为各级 value 组成的数组，如选中"北京市 > 东城区 > 东单"则为 `['110000', '150600000000', '150600800000']`
+- 启用 `filtrable` 后支持中文搜索和拼音搜索（全拼、首字母）
+- `onlyChildSelectable` 开启后，选择有 children 的节点会清空输入框
+- CascaderSelect 支持单选和多选模式
+- CascaderSelect 的 `selected` 是完整的值对象数组（每项为各级对象的数组），而非简单的 value
+- 支持键盘上下键和回车键操作
+- 组件会深拷贝传入的 `data` 并在内部维护 `_path` 属性

package/src/component/checkbox/README.md

@@ -0,0 +1,120 @@
+# Checkbox
+
+## 简介
+复选框组件 - 用于多选场景，支持单个使用和分组使用（CheckboxGroup）。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Checkbox, CheckboxGroup } from '@gmfe/react'
+
+// 单个使用
+<Checkbox checked onChange={onChange}>选项</Checkbox>
+
+// 分组使用
+<CheckboxGroup name='city' value={value} onChange={setValue}>
+  <Checkbox value={1}>广州</Checkbox>
+  <Checkbox value={2}>深圳</Checkbox>
+  <Checkbox value={3}>成都</Checkbox>
+</CheckboxGroup>
+```
+
+## API
+
+### Checkbox Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| checked | 是否选中 | `bool` | - | 否 |
+| onChange | 变化回调 | `func` | `_.noop` | 否 |
+| value | 选项值，配合 CheckboxGroup 使用 | `any` | - | 否 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| children | 显示文本 | `any` | - | 否 |
+| indeterminate | 半选状态（仅 checked 为 false 时有效，只控制样式） | `bool` | - | 否 |
+| inline | 是否行内显示 | `bool` | - | 否 |
+| block | 是否整行可点击 | `bool` | - | 否 |
+| col | 配合 group 使用，设置列数下的宽度占比 | `number` | - | 否 |
+| name | input name 属性 | `string` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### CheckboxGroup Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| name | 表单名称，必填 | `string` | - | 是 |
+| value | 已选中的值数组 | `array` | - | 是 |
+| onChange | 变化回调，参数为最新的值数组 | `func` | `_.noop` | 否 |
+| inline | 是否行内显示 | `bool` | - | 否 |
+| block | 是否整行可点击 | `bool` | - | 否 |
+| col | 列数，子元素会按百分比分配宽度 | `number` | - | 否 |
+| children | Checkbox 子组件 | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<Checkbox checked>选中状态</Checkbox>
+<Checkbox>未选中状态</Checkbox>
+<Checkbox indeterminate>半选状态</Checkbox>
+```
+
+### 禁用状态
+```jsx
+<Checkbox checked disabled>选中禁用</Checkbox>
+<Checkbox disabled>未选中禁用</Checkbox>
+<Checkbox indeterminate disabled>半选禁用</Checkbox>
+```
+
+### 行内显示
+```jsx
+<Checkbox checked inline>选项1</Checkbox>
+<Checkbox inline>选项2</Checkbox>
+```
+
+### 整行可点击
+```jsx
+<Checkbox block checked={checked} onChange={() => setChecked(!checked)}>
+  整行都可以点击
+</Checkbox>
+```
+
+### 分组使用
+```jsx
+<CheckboxGroup
+  name='city'
+  value={[1, 4]}
+  onChange={value => console.log(value)}
+>
+  <Checkbox value={1}>广州</Checkbox>
+  <Checkbox value={2} disabled>深圳</Checkbox>
+  <Checkbox value={3}>成都</Checkbox>
+  <Checkbox value={4} disabled>东莞</Checkbox>
+</CheckboxGroup>
+```
+
+### 分组带列数
+```jsx
+<CheckboxGroup
+  name='city'
+  value={value}
+  onChange={setValue}
+  col={2}
+  inline
+>
+  <Checkbox value={1}>广州</Checkbox>
+  <Checkbox value={2}>深圳</Checkbox>
+  <Checkbox value={3}>成都</Checkbox>
+  <Checkbox value={4}>东莞</Checkbox>
+</CheckboxGroup>
+```
+
+## 注意事项
+- `CheckboxGroup` 的 `name` 属性为必填项
+- `CheckboxGroup` 的 `value` 属性接收的是已选值的数组（非 Checkbox 的 value 对象）
+- `indeterminate` 半选状态只影响样式，`checked` 为 `false` 时才生效
+- `block` 模式下整行都可以触发选中/取消选中
+- `col` 属性与 `CheckboxGroup` 配合使用，按百分比自动分配每列宽度
+- 非行内模式下，每个 Checkbox 独占一行

package/src/component/collapse/README.md

@@ -0,0 +1,80 @@
+# Collapse
+
+## 简介
+折叠面板组件 - 通过 `in` 属性控制内容的展开和折叠，带有高度和透明度的过渡动画效果。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import Collapse from '@gmfe/react/lib/collapse'
+
+<Collapse in={true}>
+  <div>折叠的内容</div>
+</Collapse>
+```
+
+## API
+
+### Props
+
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| in | 控制展开/折叠状态，`true` 为展开，`false` 为折叠 | `bool` | - | 是 |
+| children | 折叠面板中的内容 | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义内联样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+import React, { useState } from 'react'
+import Collapse from '@gmfe/react/lib/collapse'
+
+const App = () => {
+  const [isExpanded, setIsExpanded] = useState(true)
+
+  return (
+    <div>
+      <button onClick={() => setIsExpanded(!isExpanded)}>
+        {isExpanded ? '收起' : '展开'}
+      </button>
+      <Collapse in={isExpanded}>
+        <div>这是可以折叠的内容区域</div>
+      </Collapse>
+    </div>
+  )
+}
+```
+
+### 配合自定义样式
+```jsx
+import React, { useState } from 'react'
+import Collapse from '@gmfe/react/lib/collapse'
+
+const App = () => {
+  const [isExpanded, setIsExpanded] = useState(false)
+
+  return (
+    <div>
+      <button onClick={() => setIsExpanded(!isExpanded)}>
+        {isExpanded ? '收起详情' : '查看详情'}
+      </button>
+      <Collapse in={isExpanded}>
+        <div style={{ padding: '12px', background: '#f5f5f5' }}>
+          这里是详情内容，点击按钮可以切换展开和折叠状态。
+        </div>
+      </Collapse>
+    </div>
+  )
+}
+```
+
+## 注意事项
+- `in` 属性为必填项，必须由父组件手动控制展开/折叠状态
+- 展开时过渡动画持续 0.5s，使用 ease 缓动曲线
+- 折叠状态下 `overflow` 被设置为 `hidden`，高度为 0，透明度为 0
+- 组件根节点会添加 `gm-collapse` 类名，可通过 `className` 进行覆盖或扩展
+- `style` 属性会与组件内部的过渡样式进行合并，同名属性以 `style` 为准

package/src/component/color_picker/README.md

@@ -0,0 +1,50 @@
+# ColorPicker
+
+## 简介
+颜色选择器组件 - 提供预设颜色和自定义颜色选择的弹出式颜色选择器
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { ColorPicker } from '@gmfe/react'
+
+<ColorPicker color={color} onChange={value => setColor(value)}>
+  <button>选择颜色</button>
+</ColorPicker>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| color | 当前选中的颜色值（十六进制格式） | `string` | - | 否 |
+| onChange | 颜色变化回调，参数为十六进制颜色值 | `function` | `_.noop` | 否 |
+| children | 触发器元素 | `any` | - | 是 |
+
+### 预设颜色
+组件内置以下预设颜色：
+- 红色 `#e02020`
+- 橙色 `#fa6400`
+- 黄色 `#f7b500`
+- 绿色 `#6dd400`
+- 蓝色 `#0091ff`
+- 紫色 `#b620e0`
+- 灰色 `#6d7278`
+
+## 示例
+
+### 基础用法
+```jsx
+<ColorPicker color="#ff0000" onChange={value => setColor(value)}>
+  <button>颜色选择器: {color}</button>
+</ColorPicker>
+```
+
+## 注意事项
+- 组件内部使用 `Popover` 以点击方式触发弹出
+- 支持手动输入十六进制颜色值
+- 支持通过系统取色器选择自定义颜色
+- 点击"确定"后触发 `onChange`，点击"取消"关闭弹窗

package/src/component/date_picker/README.md

@@ -0,0 +1,144 @@
+# DatePicker
+
+## 简介
+日期选择组件 - 提供日历弹出层选择日期，支持日期范围限制、不可选日期设置、自定义展示格式和时间选择功能。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { DatePicker } from '@gmfe/react'
+
+<DatePicker
+  date={date}
+  placeholder='请选择日期'
+  onChange={date => setDate(date)}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| date | 当前选中的日期，Date 对象 | `object` | - | 否 |
+| onChange | 日期选择回调，参数为 Date 对象 | `func` | - | 是 |
+| placeholder | 占位文字 | `string` | - | 否 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| min | 可选的最小日期，Date 对象 | `object` | - | 否 |
+| max | 可选的最大日期，Date 对象 | `object` | - | 否 |
+| disabledDate | 定义不可选择的日期，参数为 Date 对象，返回 true 不可选 | `func` | - | 否 |
+| renderDate | 自定义日期显示格式，参数为 Date 对象，返回展示内容 | `func` | - | 否 |
+| renderBottom | 添加底部自定义组件 | `element` | - | 否 |
+| popoverType | 弹出层触发方式 | `'focus' \| 'realFocus'` | - | 否 |
+| enabledTimeSelect | 是否启用时间选择 | `bool` | `false` | 否 |
+| timeLimit | 时间选择限制配置 | `object` | - | 否 |
+| timeLimit.defaultTime | 默认时间，HH:mm 格式 | `object` | - | 否 |
+| timeLimit.disabledSpan | 禁用时间段函数，参数为 Date 对象，返回 bool | `func` | - | 否 |
+| timeLimit.timeSpan | 时间间隔，默认 30 分钟 | `number` | `1800000`（30分钟） | 否 |
+| onKeyDown | 键盘事件回调 | `func` | `_.noop` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| children | 自定义触发元素 | `any` | - | 否 |
+
+### 方法（通过 ref 调用）
+| 方法 | 说明 |
+|------|------|
+| apiDoFocus | 聚焦到日期选择框 |
+| apiDoSelectWillActive | 选择键盘高亮的当前日期 |
+
+## 示例
+
+### 基础用法
+```jsx
+<DatePicker
+  date={date}
+  placeholder='请选择日期'
+  onChange={date => setDate(date)}
+/>
+```
+
+### 自定义显示格式
+```jsx
+<DatePicker
+  date={date}
+  placeholder='请选择日期'
+  onChange={date => setDate(date)}
+  renderDate={date => `${date.getMonth() + 1}月-${date.getDate()}日`}
+/>
+```
+
+### 禁用日期选择
+```jsx
+<DatePicker
+  date={date}
+  placeholder='请选择日期'
+  disabled
+  onChange={date => setDate(date)}
+/>
+```
+
+### 限制可选日期范围
+```jsx
+// 只能选择今天之后
+<DatePicker
+  date={date}
+  placeholder='选今天之后的'
+  min={new Date()}
+  onChange={date => setDate(date)}
+/>
+```
+
+### 自定义禁用日期
+```jsx
+// 只能选择非周五的日期
+<DatePicker
+  date={date}
+  placeholder='非周五'
+  disabledDate={m => moment(m).get('day') === 5}
+  onChange={date => setDate(date)}
+/>
+```
+
+### 带时间选择
+```jsx
+<DatePicker
+  date={date}
+  placeholder='请选择日期'
+  onChange={date => setDate(date)}
+  enabledTimeSelect
+/>
+```
+
+### 自定义底部内容
+```jsx
+<DatePicker
+  date={date}
+  placeholder='请选择日期'
+  onChange={date => setDate(date)}
+  renderBottom={
+    <div className='gm-border-top text-center gm-padding-10'>
+      说明：请随便输入时间
+    </div>
+  }
+/>
+```
+
+### 自定义触发元素
+```jsx
+<DatePicker date={date} onChange={date => setDate(date)}>
+  <span>
+    {date ? moment(date).format('YYYY-MM-DD') : '请点击选择'}
+  </span>
+</DatePicker>
+```
+
+## 注意事项
+- `date` 属性接收的是 JavaScript 原生 `Date` 对象
+- 不设置 `renderDate` 时，默认展示格式为 `YYYY-MM-DD`；启用 `enabledTimeSelect` 时为 `YYYY-MM-DD HH:mm`
+- `disabledDate` 的优先级高于 `min` 和 `max`
+- `renderDate` 用于自定义已选日期在输入框中的显示格式
+- 启用 `enabledTimeSelect` 后，`renderDate` 需要手动带上时间部分
+- 支持键盘上下键切换日期
+- `timeLimit.timeSpan` 的单位为毫秒，默认 30 分钟（30 * 60 * 1000）

package/src/component/date_range_picker/README.md

@@ -0,0 +1,126 @@
+# DateRangePicker
+
+## 简介
+日期范围选择组件 - 提供双日历弹出层选择日期段，支持日期范围限制、时间选择、快速选择列表等功能。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { DateRangePicker } from '@gmfe/react'
+
+<DateRangePicker
+  begin={beginDate}
+  end={endDate}
+  onChange={(begin, end) => {
+    setBeginDate(begin)
+    setEndDate(end)
+  }}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| begin | 开始日期，Date 对象 | `object` | - | 否 |
+| end | 结束日期，Date 对象 | `object` | - | 否 |
+| onChange | 日期变化回调，参数为 (begin, end) | `func` | `_.noop` | 否 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| min | 可选的最小日期，Date 对象 | `object` | - | 否 |
+| max | 可选的最大日期，Date 对象 | `object` | - | 否 |
+| disabledDate | 自定义日期是否可选，参数为 Date 对象，返回 bool。设置后 min/max 无效 | `func` | - | 否 |
+| renderDate | 自定义日期展示格式，参数为 (begin, end) 两个 Date 对象 | `func` | - | 否 |
+| canClear | 是否可清除已选日期 | `bool` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| enabledTimeSelect | 是否启用时间选择 | `bool` | `false` | 否 |
+| timeSpan | 时间间隔，默认 30 分钟 | `number` | `1800000`（30分钟） | 否 |
+| beginTimeSelect | 开始时间选择限制配置 | `object` | - | 否 |
+| beginTimeSelect.defaultTime | 默认开始时间，HH:mm 格式 | `object` | - | 否 |
+| beginTimeSelect.disabledSpan | 禁用时间段函数，参数为 Date 对象，返回时间段 | `func` | - | 否 |
+| endTimeSelect | 结束时间选择限制配置 | `object` | - | 否 |
+| endTimeSelect.defaultTime | 默认结束时间 | `object` | - | 否 |
+| endTimeSelect.disabledSpan | 禁用时间段函数 | `func` | - | 否 |
+| customQuickSelectList | 自定义左侧快速选择列表 | `array` | - | 否 |
+| children | 自定义触发元素 | `any` | - | 否 |
+
+### 方法（通过 ref 调用）
+| 方法 | 说明 |
+|------|------|
+| apiDoFocus | 聚焦到日期范围选择框 |
+
+## 示例
+
+### 基础用法
+```jsx
+<DateRangePicker
+  begin={beginDate}
+  end={endDate}
+  onChange={(begin, end) => {
+    setBeginDate(begin)
+    setEndDate(end)
+  }}
+/>
+```
+
+### 带清除功能
+```jsx
+<DateRangePicker
+  begin={beginDate}
+  end={endDate}
+  canClear
+  onChange={(begin, end) => {
+    setBeginDate(begin)
+    setEndDate(end)
+  }}
+/>
+```
+
+### 启用时间选择
+```jsx
+<DateRangePicker
+  begin={beginDate}
+  end={endDate}
+  enabledTimeSelect
+  onChange={(begin, end) => {
+    setBeginDate(begin)
+    setEndDate(end)
+  }}
+/>
+```
+
+### 自定义快速选择列表
+```jsx
+const quickList = [
+  {
+    range: [[0, 'day'], [0, 'day']],
+    text: '今天'
+  },
+  {
+    range: [[-7, 'day'], [0, 'day']],
+    text: '最近7天'
+  }
+]
+
+<DateRangePicker
+  begin={beginDate}
+  end={endDate}
+  customQuickSelectList={quickList}
+  onChange={(begin, end) => {
+    setBeginDate(begin)
+    setEndDate(end)
+  }}
+/>
+```
+
+## 注意事项
+- `begin` 和 `end` 属性接收 JavaScript 原生 `Date` 对象
+- 不设置 `renderDate` 时，默认展示格式为 `YYYY-MM-DD ~ YYYY-MM-DD`
+- 启用 `enabledTimeSelect` 时，展示格式自动带上时间部分
+- `disabledDate` 设置后，`min` 和 `max` 将失效
+- `customQuickSelectList` 的 `range` 数组项格式为 `[距离天数, 'day']`，从当前日期推算
+- 选择日期后需要点击"确定"按钮才会触发 `onChange`
+- 点击"取消"会关闭弹窗且不触发回调
+- `canClear` 为 true 时，选中状态下可以通过清除按钮清空日期范围