@gmfe/react 2.14.30-alpha.0 → 2.14.31

package/src/component/sheet/README.md

@@ -0,0 +1,176 @@
+# Sheet
+
+## 简介
+数据表格组件 - 用于展示结构化数据，支持列定义、操作列、选择框、批量操作、展开行和分页等功能。（已废弃，建议使用 Table 组件替代）
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Sheet, SheetColumn, SheetAction, SheetSelect, SheetBatchAction } from '@gmfe/react/lib/sheet'
+
+<Sheet list={dataList}>
+  <SheetColumn field='id' name='ID' />
+  <SheetColumn field='name' name='名字' />
+  <SheetColumn field='age' name='年龄' />
+  <SheetAction>
+    {(record, index) => <Button>操作</Button>}
+  </SheetAction>
+</Sheet>
+```
+
+## API
+
+### Sheet Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| list | 表格数据数组 | `array` | `[]` | 是 |
+| loading | 是否显示加载状态 | `bool` | `false` | 否 |
+| enableEmptyTip | 数据为空时的提示，传入 `true` 显示默认提示，也可传入字符串或 React 元素自定义提示 | `bool \| string \| ReactElement` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| getTrProps | 获取行属性，返回值会传递到 `<tr>` 上 | `(index: number) => object` | `() => ({})` | 否 |
+| scrollX | 是否开启横向滚动 | `bool` | `false` | 否 |
+| expandedRowRender | 展开行渲染函数 | `(index: number) => ReactElement` | - | 否 |
+| onExpand | 单行展开/收起回调 | `(index: number) => void` | - | 否 |
+| onExpandAll | 全部展开/收起回调 | `() => void` | - | 否 |
+| children | 子组件（SheetColumn、SheetAction、SheetSelect、SheetBatchAction、Pagination 等） | `any` | - | 否 |
+
+### SheetColumn Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| field | 对应 list 中的字段名 | `string` | - | 是 |
+| name | 列标题，支持字符串或 React 元素 | `string \| ReactElement` | - | 是 |
+| render | 自定义单元格渲染函数 | `(value: any, index: number, record: object) => ReactNode` | - | 否 |
+| placeholder | 字段值为空时的占位内容 | `any` | - | 否 |
+| children | 自定义单元格渲染（函数子组件），参数为 `(value, index, record)` | `(value, index, record) => ReactNode` | - | 否 |
+
+### SheetAction Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| children | 操作列渲染函数，参数为 `(record, index)` | `(record, index) => ReactNode` | - | 否 |
+
+### SheetSelect Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| onSelect | 单选回调 | `(checked: bool, index: number) => void` | - | 是 |
+| onSelectAll | 全选回调 | `(checked: bool) => void` | - | 否 |
+| onChange | 选中状态变更回调，参数为完整的 list（修改后的） | `(list: array) => void` | - | 否 |
+| isDisabled | 判断行是否禁用选择 | `(record: object) => bool` | `() => false` | 否 |
+| isRadio | 是否为单选模式 | `bool` | `false` | 否 |
+| hasSelectTip | 是否显示全选提示 | `bool` | `false` | 否 |
+| selectAllTip | 全选提示内容 | `ReactNode` | `'已选中所有'` | 否 |
+| children | 子元素 | `any` | - | 否 |
+
+### SheetBatchAction Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| children | 批量操作按钮区域 | `any` | - | 否 |
+
+### Sheet 静态方法
+
+#### `Sheet.findTableDOM(ref)`
+获取表格 DOM 元素。
+
+| 参数 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| ref | Sheet 组件的 ref | `ReactRef` | 是 |
+
+返回值：`HTMLTableElement`
+
+## 示例
+
+### 基础用法
+```jsx
+<Sheet list={[
+  { id: 1, name: '小明', age: '10' },
+  { id: 2, name: '小红', age: '15' },
+  { id: 3, name: '小蓝', age: '20' }
+]}>
+  <SheetColumn field='id' name='ID' />
+  <SheetColumn field='name' name='名字' />
+  <SheetColumn field='age' name='年龄' />
+</Sheet>
+```
+
+### 自定义列渲染
+```jsx
+<Sheet list={list}>
+  <SheetColumn field='id' name='ID' />
+  <SheetColumn field='name' name='名字'>
+    {(name, index, record) => `我的名字叫${name}, ID是${record.id}`}
+  </SheetColumn>
+  <SheetColumn field='name' name='名字' render={(name, index, record) => `自定义: ${name}`} />
+</Sheet>
+```
+
+### 带操作列
+```jsx
+<Sheet list={list}>
+  <SheetColumn field='name' name='名字' />
+  <SheetAction>
+    {(record, index) => (
+      <div>
+        <Button onClick={() => alert(record.name)}>删除</Button>
+      </div>
+    )}
+  </SheetAction>
+</Sheet>
+```
+
+### 带选择框
+```jsx
+<Sheet list={list}>
+  <SheetColumn field='name' name='名字' />
+  <SheetSelect
+    onSelect={(checked, index) => {
+      // 处理选中逻辑，使用 _gm_select 字段标记选中状态
+    }}
+    onSelectAll={(checked) => {
+      // 处理全选逻辑
+    }}
+    hasSelectTip
+    selectAllTip={<div>全选提示信息</div>}
+  />
+  <SheetBatchAction>
+    <Button>批量删除</Button>
+  </SheetBatchAction>
+</Sheet>
+```
+
+### 带分页
+```jsx
+<Sheet list={list}>
+  <SheetColumn field='name' name='名字' />
+  <Pagination
+    data={{ count: 70, offset: 0, limit: 10 }}
+    toPage={({ offset, limit }) => fetchData({ offset, limit })}
+  />
+</Sheet>
+```
+
+### 可展开行
+```jsx
+<Sheet
+  list={list}
+  expandedRowRender={(index) => (
+    <div>展开行内容：{list[index].name}</div>
+  )}
+  onExpand={(index) => {
+    // 切换展开状态，需要修改数据中 __gm_expanded 字段
+  }}
+  onExpandAll={() => {
+    // 全部展开/收起
+  }}
+>
+  <SheetColumn field='name' name='名字' />
+</Sheet>
+```
+
+## 注意事项
+- Sheet 组件已废弃，建议使用 Table 组件替代，使用时会输出控制台警告
+- 使用 `SheetSelect` 时，约定数据列表中的 `_gm_select` 字段表示选中状态（bool 类型）
+- `onChange` 和 `onSelect` 的区别：`onChange` 会修改整个 list 数据，`onSelect` 只返回 checked 和 index
+- `SheetBatchAction` 必须配合 `SheetSelect` 使用才会显示
+- `Pagination` 和 `PaginationText` 作为 Sheet 的子组件时会自动排列到表格下方
+- `getTrProps` 返回的属性会传递到每一行的 `<tr>` 上，可用于自定义行样式或属性

package/src/component/steps/README.md

@@ -0,0 +1,55 @@
+# Steps
+
+## 简介
+步骤条组件 - 展示操作流程的当前步骤进度，支持标题和描述信息。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import Steps from '@gmfe/react/lib/steps'
+
+<Steps
+  data={[
+    { title: '第一步' },
+    { title: '第二步', description: '这是第二步的描述' },
+    { title: '第三步', description: '这是第三步的描述' }
+  ]}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 步骤数据数组 | `{ title?: string, description?: string }[]` | - | 是 |
+| className | 自定义类名 | `string` | - | 否 |
+
+data 数组中每项的字段：
+
+| 字段 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| title | 步骤标题 | `string` | 否 |
+| description | 步骤描述 | `string` | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<Steps
+  data={[
+    { title: '第一步' },
+    { title: '第二步', description: '这是第二步' },
+    { title: '第三步', description: '这是第三步' },
+    { title: '第四步', description: '这是第四步' }
+  ]}
+  style={{ width: '300px' }}
+/>
+```
+
+## 注意事项
+- 步骤条为垂直方向排列
+- 每个步骤自动显示序号（从 1 开始）
+- title 和 description 均为可选，可以只传 title 不传 description

package/src/component/storage/README.md

@@ -0,0 +1,83 @@
+# Storage
+
+## 简介
+本地存储组件 - 基于 localStorage 的封装，提供组件式和静态方法两种使用方式
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+
+### 组件方式
+```jsx
+import { Storage } from '@gmfe/react'
+
+<Storage name="myKey" value={myValue} />
+```
+
+### 静态方法方式
+```jsx
+import { Storage } from '@gmfe/react'
+
+Storage.set('key', 'value')
+Storage.get('key')
+Storage.remove('key')
+```
+
+## API
+
+### 组件 Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| name | 存储的键名 | `string` | - | 是 |
+| value | 存储的值，支持 `string`、`object`、`array` | `string \| object \| array` | - | 否 |
+
+### 静态方法
+| 方法 | 说明 | 参数 |
+|------|------|------|
+| `Storage.set(key, value)` | 设置存储值 | `key: string, value: any` |
+| `Storage.get(key)` | 获取存储值 | `key: string` |
+| `Storage.remove(key)` | 删除指定存储 | `key: string` |
+| `Storage.clear()` | 清除本域名全部存储（慎用） | - |
+| `Storage.getAll()` | 获取全部存储，以对象形式返回 | - |
+
+## 示例
+
+### 实时存储
+```jsx
+function App() {
+  const [data, setData] = useState('hello')
+  return (
+    <div>
+      <input
+        type="text"
+        value={data}
+        onChange={e => setData(e.target.value)}
+      />
+      <Storage name="test" value={data} />
+    </div>
+  )
+}
+```
+
+### 静态方法
+```jsx
+// 设置值
+Storage.set('username', '张三')
+Storage.set('settings', { theme: 'dark', lang: 'zh' })
+
+// 获取值
+Storage.get('username') // '张三'
+
+// 删除
+Storage.remove('username')
+
+// 获取全部
+Storage.getAll() // { settings: { theme: 'dark', lang: 'zh' } }
+```
+
+## 注意事项
+- 所有存储的 key 会自动添加 `_react-gm_` 前缀，避免与其他存储冲突
+- 组件方式会在 `value` 变化时自动更新存储
+- `Storage.clear()` 会清除本域名下全部 localStorage，请谨慎使用
+- 内部使用 `JSON.stringify` / `JSON.parse` 序列化，支持存储对象和数组

package/src/component/switch/README.md

@@ -0,0 +1,85 @@
+# Switch
+
+## 简介
+开关组件 - 用于表示两种状态之间的切换，支持多种颜色类型和自定义开/关文案。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Switch } from '@gmfe/react'
+
+<Switch
+  checked={checked}
+  onChange={setChecked}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| checked | 是否开启 | `bool` | - | 是 |
+| onChange | 状态变化回调，参数为当前 checked 值 | `func` | `_.noop` | 否 |
+| type | 颜色类型 | `'default' \| 'primary' \| 'success' \| 'info' \| 'warning' \| 'danger'` | `'default'` | 否 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| on | 开启时显示的文案 | `any` | `''` | 否 |
+| off | 关闭时显示的文案 | `any` | `''` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<Switch
+  checked={isWork}
+  onChange={checked => setIsWork(checked)}
+/>
+```
+
+### 带文案
+```jsx
+<Switch
+  checked={checked}
+  onChange={setChecked}
+  on='开'
+  off='关'
+/>
+```
+
+### 不同颜色类型
+```jsx
+<Switch type='default' checked onChange={_.noop} />
+<Switch type='primary' checked onChange={_.noop} />
+<Switch type='success' checked onChange={_.noop} />
+<Switch type='info' checked onChange={_.noop} />
+<Switch type='warning' checked onChange={_.noop} />
+<Switch type='danger' checked onChange={_.noop} />
+```
+
+### 禁用状态
+```jsx
+<Switch disabled checked onChange={_.noop} />
+<Switch disabled onChange={_.noop} />
+```
+
+### 在表单中使用
+```jsx
+<FormItem label='是否工作' required>
+  <Switch
+    checked={isWork}
+    onChange={checked => setIsWork(checked)}
+  />
+</FormItem>
+```
+
+## 注意事项
+- `checked` 为必填属性，建议使用受控模式
+- 组件宽度会根据 `on` 和 `off` 文案自动调整，取两者中较宽者
+- 建议保持 `on` 和 `off` 文案宽度一致，以获得更好的视觉效果
+- 开关的最小宽度为 34px
+- 非受控模式下（未传入 `checked`），组件内部自行管理状态
+- 组件挂载时会自动计算开关宽度，确保文案完整显示

package/src/component/table_select/README.md

@@ -0,0 +1,92 @@
+# TableSelect
+
+## 简介
+表格选择器组件 - 以表格形式展示选项列表的下拉选择器，支持多列显示和搜索过滤
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { TableSelect } from '@gmfe/react'
+
+<TableSelect
+  data={data}
+  columns={columns}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 数据源，全部展示，没有内部过滤 | `array` | - | 是 |
+| selected | 当前选中的值 | `any` | - | 否 |
+| onSelect | 选中回调 | `function` | - | 是 |
+| columns | 列定义，类似 ReactTable，格式：`[{Header, accessor, Cell, width}]` | `array` | - | 是 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| onSearch | 搜索回调，参数为 `(searchValue, data)` | `function` | - | 否 |
+| delay | 搜索防抖延迟（毫秒） | `number` | - | 否 |
+| searchPlaceholder | 搜索框占位文本 | `string` | - | 否 |
+| renderListFilter | 列表过滤函数，参数为 `(searchValue, data)` | `function` | - | 否 |
+| renderListFilterType | 指定默认的过滤类型 | `'default' \| 'pinyin'` | - | 否 |
+| placeholder | 占位文本 | `string` | - | 否 |
+| renderSelected | 定制已选区域的展示，参数为 `selected` | `function` | - | 否 |
+| listHeight | 列表高度 | `string` | - | 否 |
+| popoverType | 弹出框触发方式 | `'focus' \| 'realFocus'` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| popupClassName | 弹出框自定义类名 | `string` | - | 否 |
+| isKeyboard | 是否启用键盘导航 | `bool` | - | 否 |
+| onKeyDown | 键盘事件回调 | `function` | - | 否 |
+
+### columns 配置
+| 属性 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| Header | 列标题 | `string` | 是 |
+| accessor | 字段访问器，支持字符串路径或函数 | `string \| function` | 否 |
+| Cell | 自定义单元格渲染，参数为 `{original, index}` | `function` | 否 |
+| width | 列宽度（px），建议设置 | `number` | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+const data = [
+  { value: 'D1', text: '大白菜', original: { sku_id: 'D1', sku_name: '大白菜', supplier: '供应商A' } },
+  { value: 'D2', text: '小白菜', original: { sku_id: 'D2', sku_name: '小白菜', supplier: '供应商B' } }
+]
+
+const columns = [
+  { Header: 'ID', accessor: 'original.sku_id', width: 100 },
+  { Header: '名字', accessor: 'original.sku_name', width: 100 },
+  { Header: '供应商', accessor: 'original.supplier', width: 100 }
+]
+
+<TableSelect
+  data={data}
+  columns={columns}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+```
+
+### 自定义单元格渲染
+```jsx
+const columns = [
+  {
+    Header: '名字',
+    accessor: 'original.sku_name',
+    width: 100,
+    Cell: ({ original }) => <strong>{original.sku_name}</strong>
+  }
+]
+```
+
+## 注意事项
+- 建议为每列设置 `width`，未设置时会在控制台输出警告
+- 数据项需要包含 `value`、`text` 和 `original` 字段
+- 空值单元格会显示为 `-`

package/src/component/tabs/README.md

@@ -0,0 +1,85 @@
+# Tabs
+
+## 简介
+选项卡组件 - 支持受控和非受控两种模式，可通过 `lazy` 属性开启懒加载渲染。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import Tabs from '@gmfe/react/lib/tabs'
+
+// 非受控模式
+<Tabs tabs={['选项1', '选项2', '选项3']} defaultActive={0}>
+  <div>内容1</div>
+  <div>内容2</div>
+  <div>内容3</div>
+</Tabs>
+
+// 受控模式
+<Tabs
+  tabs={['选项1', '选项2', '选项3']}
+  active={activeIndex}
+  onChange={index => setActiveIndex(index)}
+>
+  <div>内容1</div>
+  <div>内容2</div>
+  <div>内容3</div>
+</Tabs>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| tabs | 选项卡标题数组 | `string[]` | - | 是 |
+| active | 当前激活的选项卡索引（受控模式） | `number` | - | 否 |
+| defaultActive | 默认激活的选项卡索引（非受控模式） | `number` | `0` | 否 |
+| lazy | 是否懒加载，开启后只渲染当前激活的选项卡内容 | `bool` | `false` | 否 |
+| onChange | 选项卡切换回调，返回当前选中的索引 | `(index: number) => void` | - | 否 |
+| children | 选项卡内容，长度必须与 tabs 数组一致 | `ReactNode[]` | - | 否 |
+
+## 示例
+
+### 受控模式
+```jsx
+const [active, setActive] = useState(0)
+const tabs = ['第一个', '第二个', '第三个']
+
+<Tabs
+  tabs={tabs}
+  active={active}
+  onChange={index => setActive(index)}
+>
+  <div>第一个选项卡内容</div>
+  <div>第二个选项卡内容</div>
+  <div>第三个选项卡内容</div>
+</Tabs>
+```
+
+### 非受控模式
+```jsx
+<Tabs tabs={['选项1', '选项2', '选项3']} defaultActive={2}>
+  <div>内容1</div>
+  <div>内容2</div>
+  <div>内容3</div>
+</Tabs>
+```
+
+### 懒加载模式
+```jsx
+<Tabs tabs={['选项1', '选项2', '选项3']} lazy>
+  <div>内容1</div>
+  <div>内容2</div>
+  <div>内容3</div>
+</Tabs>
+```
+
+## 注意事项
+- `active` 和 `defaultActive` 不能同时使用，否则会输出控制台警告
+- 使用 `active`（受控模式）时，必须同时传入 `onChange`，否则会输出控制台警告
+- `children` 的长度必须与 `tabs` 数组长度一致，否则会报错
+- 非懒加载模式下，所有选项卡内容都会被渲染（通过 `hidden` 类名控制显示/隐藏）
+- 懒加载模式下，只有当前激活的选项卡内容会被渲染，切换时会销毁之前的内容

package/src/component/time_span/README.md

@@ -0,0 +1,112 @@
+# TimeSpan / TimeSpanPicker
+
+## 简介
+时间跨度选择组件 - TimeSpan 提供时间点选择面板，TimeSpanPicker 提供带输入框的时间选择器
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { TimeSpan, TimeSpanPicker } from '@gmfe/react'
+
+// 直接使用时间面板
+<TimeSpan
+  selected={date}
+  onSelect={date => setDate(date)}
+/>
+
+// 带输入框的时间选择器
+<TimeSpanPicker
+  date={date}
+  onChange={date => setDate(date)}
+/>
+```
+
+## API
+
+### TimeSpan Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| min | 可选的最小时间（Date 对象），默认一天的开始时间 | `object` | 当天 `00:00` | 否 |
+| max | 可选的最大时间（Date 对象），默认一天的结束时间 | `object` | 当天 `23:59` | 否 |
+| disabledSpan | 禁用时间段函数，参数为 Date 对象，返回 `boolean` | `function` | - | 否 |
+| span | 时间跨度（毫秒），默认为 30 分钟 | `number` | `1800000` (30分钟) | 否 |
+| selected | 当前选中的时间（Date 对象） | `object` | - | 否 |
+| renderItem | 渲染时间文本格式 | `function` | `(value) => moment(value).format('HH:mm')` | 否 |
+| onSelect | 选中回调，参数为 Date 对象 | `function` | `_.noop` | 否 |
+| beginTime | 自定义起始时间点（Date 对象），不传默认从 00:00 开始 | `object` | - | 否 |
+| endTime | 自定义结束时间点（Date 对象） | `object` | - | 否 |
+| enabledEndTimeOfDay | 是否展示 24:00 结束时间 | `bool` | `false` | 否 |
+
+### TimeSpanPicker Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| date | 当前选中的时间（Date 对象） | `object` | - | 是 |
+| onChange | 选中回调，参数为 Date 对象 | `function` | `_.noop` | 否 |
+| disabled | 是否禁用 | `bool` | - | 否 |
+| min | 可选的最小时间（Date 对象） | `object` | - | 否 |
+| max | 可选的最大时间（Date 对象） | `object` | - | 否 |
+| span | 时间跨度（毫秒），默认为 30 分钟 | `number` | `1800000` (30分钟) | 否 |
+| disabledSpan | 禁用时间段函数，参数为 Date 对象，返回 `boolean` | `function` | - | 否 |
+| renderItem | 渲染时间文本格式 | `function` | `(value) => moment(value).format('HH:mm')` | 否 |
+| beginTime | 自定义起始时间点（Date 对象） | `object` | - | 否 |
+| endTime | 自定义结束时间点（Date 对象） | `object` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+| children | 自定义触发器元素 | `any` | - | 否 |
+| isInPopup | 是否嵌套在其他弹出层中 | `bool` | `false` | 否 |
+| enabledEndTimeOfDay | 是否展示 24:00 结束时间 | `bool` | `false` | 否 |
+
+## 示例
+
+### TimeSpan 基础用法
+```jsx
+<TimeSpan
+  selected={date}
+  onSelect={date => setDate(date)}
+/>
+```
+
+### TimeSpan 禁用时间段
+```jsx
+<TimeSpan
+  max={moment().hour(20).minute(0)}
+  disabledSpan={spanMoment =>
+    spanMoment.isSameOrAfter(moment('11:00', 'HH:mm')) &&
+    spanMoment.isSameOrBefore(moment('18:30', 'HH:mm'))
+  }
+  selected={date}
+  onSelect={date => setDate(date)}
+/>
+```
+
+### TimeSpan 自定义时间跨度
+```jsx
+<TimeSpan
+  span={60 * 60 * 1000} // 1小时
+  renderItem={value => moment(value).format('HH')}
+  selected={date}
+  onSelect={date => setDate(date)}
+/>
+```
+
+### TimeSpanPicker 基础用法
+```jsx
+<TimeSpanPicker
+  date={date}
+  onChange={date => setDate(date)}
+/>
+```
+
+### TimeSpanPicker 自定义触发器
+```jsx
+<TimeSpanPicker date={date} onChange={date => setDate(date)}>
+  <span>{date ? moment(date).format('HH:mm') : '请点击选择'}</span>
+</TimeSpanPicker>
+```
+
+## 注意事项
+- 时间面板分三列展示，时间间隔较大时，某一列可能无数据
+- `TimeSpanPicker` 内部使用 `Popover` 和 `Selection` 组件
+- `disabledSpan` 可用于禁用特定时间段（如午休时间）