@gmfe/react 2.14.30-alpha.0 → 2.14.31

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 延迟以避免与按钮点击冲突）
+- 禁用状态下不会显示编辑图标

package/src/component/filter_select/README.md

@@ -0,0 +1,104 @@
+# FilterSelect
+
+## 简介
+过滤选择组件 - 支持搜索过滤的下拉选择器，提供单选和多选两个版本
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { FilterSelect, MultipleFilterSelect } from '@gmfe/react'
+
+// 单选
+<FilterSelect
+  id="filter-1"
+  list={list}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+/>
+
+// 多选
+<MultipleFilterSelect
+  id="filter-2"
+  list={list}
+  selected={selectedList}
+  onSelect={selectedList => setSelectedList(selectedList)}
+/>
+```
+
+## API
+
+### FilterSelect Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| id | 唯一标识 | `string` | - | 是 |
+| list | 数据源数组 | `array` | - | 是 |
+| selected | 当前选中项 | `any` | - | 否 |
+| onSelect | 选中回调 | `function` | - | 是 |
+| disabled | 是否禁用 | `bool` | `false` | 否 |
+| isGroupList | 数据是否为分组格式 | `bool` | `false` | 否 |
+| onSearch | 搜索回调，参数为 `query` | `function` | `_.noop` | 否 |
+| withFilter | 过滤函数，参数为 `(list, query)` | `function` | `(v) => v` | 否 |
+| delay | 搜索防抖延迟（毫秒） | `number` | `500` | 否 |
+| listMaxHeight | 列表最大高度 | `string` | `'250px'` | 否 |
+| placeholder | 搜索框占位文本 | `string` | `''` | 否 |
+| isScrollToSelected | 是否滚动到选中项 | `bool` | `false` | 否 |
+| onInputFocus | 搜索框获取焦点回调 | `function` | `_.noop` | 否 |
+| disableSearch | 是否禁用搜索 | `bool` | `false` | 否 |
+| renderItemName | 自定义列表项渲染 | `function` | `(v) => v.name` | 否 |
+| showClear | 是否显示清除按钮 | `bool` | `false` | 否 |
+| className | 外层自定义类名 | `string` | - | 否 |
+| inputClassName | 列表项自定义类名 | `string` | - | 否 |
+
+### MultipleFilterSelect Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| id | 唯一标识 | `string` | - | 是 |
+| list | 数据源数组 | `array` | - | 是 |
+| selected | 已选中的项数组 | `array` | - | 是 |
+| onSelect | 选中回调 | `function` | - | 是 |
+| disabled | 是否禁用 | `bool` | `false` | 否 |
+| isGroupList | 数据是否为分组格式 | `bool` | `false` | 否 |
+| onSearch | 搜索回调，参数为 `query` | `function` | `_.noop` | 否 |
+| withFilter | 过滤函数，参数为 `(list, query)` | `function` | `(v) => v` | 否 |
+| delay | 搜索防抖延迟（毫秒） | `number` | `500` | 否 |
+| listMaxHeight | 列表最大高度 | `string` | `'250px'` | 否 |
+| placeholder | 搜索框占位文本 | `string` | `''` | 否 |
+| isScrollToSelected | 是否滚动到选中项 | `bool` | `false` | 否 |
+| onInputFocus | 搜索框获取焦点回调 | `function` | `_.noop` | 否 |
+| disableSearch | 是否禁用搜索 | `bool` | `false` | 否 |
+| renderItemName | 自定义列表项渲染 | `function` | `(v) => v.name` | 否 |
+| className | 外层自定义类名 | `string` | - | 否 |
+| inputClassName | 列表项自定义类名 | `string` | - | 否 |
+
+## 示例
+
+### 单选
+```jsx
+<FilterSelect
+  id="my-filter"
+  list={[{ value: 1, name: '选项1' }, { value: 2, name: '选项2' }]}
+  selected={selected}
+  onSelect={selected => setSelected(selected)}
+  placeholder="请选择"
+/>
+```
+
+### 多选
+```jsx
+<MultipleFilterSelect
+  id="my-multi-filter"
+  list={[{ value: 1, name: '选项1' }, { value: 2, name: '选项2' }]}
+  selected={selectedList}
+  onSelect={selectedList => setSelectedList(selectedList)}
+  placeholder="请选择"
+/>
+```
+
+## 注意事项
+- 必须提供 `id` 属性，否则会在控制台输出警告
+- 单选选中后会自动关闭弹出框
+- 多选模式下已选项会以标签形式展示，可单独关闭
+- 支持键盘上下键导航和回车键选中
+- `onSearch` 返回 Promise 时，搜索期间会显示 Loading 状态

package/src/component/flex/README.md

@@ -0,0 +1,88 @@
+# Flex
+
+## 简介
+弹性布局组件 - 对 CSS Flexbox 布局的简单封装，提供兼容性良好的布尔值属性来控制 flex 容器的各种行为。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import Flex from '@gmfe/react/lib/flex'
+
+// 水平居中布局
+<Flex justifyCenter alignCenter>
+  <div>内容1</div>
+  <div>内容2</div>
+</Flex>
+
+// 垂直布局
+<Flex column>
+  <div>上</div>
+  <div>下</div>
+</Flex>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| flex | flex 值，传入数字时作为 flex 属性值，传入 true 时等同于 1 | `number \| bool` | - | 否 |
+| auto | 设置 flex: auto | `bool` | - | 否 |
+| none | 设置 flex: none | `bool` | - | 否 |
+| width | 设置宽度（设置后自动添加 none 效果） | `string` | - | 否 |
+| height | 设置高度（设置后自动添加 none 效果） | `string` | - | 否 |
+| row | 水平排列（主轴为水平方向） | `bool` | - | 否 |
+| column | 垂直排列（主轴为垂直方向） | `bool` | - | 否 |
+| wrap | 允许换行 | `bool` | - | 否 |
+| nowrap | 不允许换行 | `bool` | - | 否 |
+| justifyStart | 主轴起始对齐 | `bool` | - | 否 |
+| justifyEnd | 主轴末尾对齐 | `bool` | - | 否 |
+| justifyCenter | 主轴居中对齐 | `bool` | - | 否 |
+| justifyBetween | 主轴两端对齐，中间等距分布 | `bool` | - | 否 |
+| justifyAround | 主轴周围等距分布 | `bool` | - | 否 |
+| alignStart | 交叉轴起始对齐 | `bool` | - | 否 |
+| alignEnd | 交叉轴末尾对齐 | `bool` | - | 否 |
+| alignCenter | 交叉轴居中对齐 | `bool` | - | 否 |
+| alignBaseline | 交叉轴基线对齐 | `bool` | - | 否 |
+| alignStretch | 交叉轴拉伸对齐 | `bool` | - | 否 |
+| alignContentStart | 多行交叉轴起始对齐 | `bool` | - | 否 |
+| alignContentEnd | 多行交叉轴末尾对齐 | `bool` | - | 否 |
+| alignContentCenter | 多行交叉轴居中对齐 | `bool` | - | 否 |
+| alignContentBetween | 多行交叉轴两端对齐 | `bool` | - | 否 |
+| alignContentAround | 多行交叉轴周围等距分布 | `bool` | - | 否 |
+| alignContentStretch | 多行交叉轴拉伸对齐 | `bool` | - | 否 |
+| children | 子元素 | `any` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+// 水平布局，两端对齐
+<Flex row justifyBetween>
+  <div>左侧</div>
+  <div>右侧</div>
+</Flex>
+
+// 垂直居中
+<Flex column alignCenter>
+  <div>项目1</div>
+  <div>项目2</div>
+</Flex>
+
+// 设置固定宽度
+<Flex width='200px'>
+  固定宽度内容
+</Flex>
+
+// flex 自适应填充
+<Flex flex>自动填充</Flex>
+```
+
+## 注意事项
+- Flex 布局语法参考 [Flex 布局教程](http://www.ruanyifeng.com/blog/2015/07/flex-grammar.html)
+- 设置 `width` 或 `height` 属性后，组件会自动添加 `none` 效果（即 `flex: none`）
+- `flex` 属性传入 `true` 时等同于 `flex: 1`，传入数字时直接作为 flex 值

package/src/component/flip_number/README.md

@@ -0,0 +1,53 @@
+# FlipNumber
+
+## 简介
+数字翻滚动画组件 - 以滚动方式从起始数字过渡到目标数字，支持小数、千分符和自定义缓动函数
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { FlipNumber } from '@gmfe/react'
+
+<FlipNumber to={12345} />
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| to | 最终要显示的数字 | `number` | - | 是 |
+| from | 滚动的起始数字 | `number` | `0` | 否 |
+| delay | 延迟开始时间（毫秒） | `number` | `0` | 否 |
+| duration | 滚动动画时长（毫秒） | `number` | `1500` | 否 |
+| easeFn | 缓动函数，控制滚动的加速度 | `function` | 默认起末慢、中间快的三次方缓动 | 否 |
+| individually | 是否逐个数字滚动 | `bool` | `true` | 否 |
+| decimal | 小数点后保留位数 | `number` | `0` | 否 |
+| useGroup | 是否启用大数逗号分组（千分符） | `bool` | `false` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<FlipNumber to={12345} />
+```
+
+### 带小数和千分符
+```jsx
+<FlipNumber
+  to={709394}
+  from={234.23}
+  decimal={2}
+  useGroup
+  delay={1000}
+  className="gm-text-20"
+/>
+```
+
+## 注意事项
+- 动画使用 `requestAnimationFrame` 实现，性能良好
+- 支持负数显示
+- 自定义缓动函数可参考 [easing-js](https://github.com/danro/easing-js) 库

package/src/component/form/README.md

@@ -0,0 +1,199 @@
+# Form
+
+## 简介
+表单组件 - 提供完整的表单布局能力，包含 Form、FormItem、FormButton、FormBlock、FormGroup、FormPanel 等子组件，支持单栏/多栏布局、表单验证、按钮位置控制等功能。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import {
+  Form,
+  FormItem,
+  FormButton,
+  FormBlock,
+  FormGroup,
+  FormPanel
+} from '@gmfe/react'
+```
+
+## API
+
+### Form Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| onSubmit | 表单提交回调（已内置 event.preventDefault） | `func` | - | 否 |
+| onSubmitValidated | 所有验证通过后调用 | `func` | - | 否 |
+| inline | 行内模式，一般用不到，BoxForm 内部自动使用 | `bool` | - | 否 |
+| disabledCol | 禁用列宽限制，让表单撑满页面 | `bool` | - | 否 |
+| colWidth | 自定义列宽 | `string` | - | 否 |
+| labelWidth | label 宽度 | `string` | - | 否 |
+| hasButtonInGroup | 仅在 FormGroup 下使用，添加隐藏按钮响应 Enter | `bool` | - | 否 |
+| btnPosition | 按钮位置 | `'center' \| 'left' \| 'right'` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### Form 方法（通过 ref 调用）
+| 方法 | 说明 |
+|------|------|
+| apiDoValidate | 手动触发验证，返回 boolean |
+
+### FormItem Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| col | 占用栏数 | `1 \| 2 \| 3` | `1` | 否 |
+| disabledCol | 禁用列宽限制 | `bool` | - | 否 |
+| label | 标签文本（请不要包含 `:`） | `string \| element` | - | 否 |
+| toolTip | 提示信息 | `element` | - | 否 |
+| toolTipLeft | 提示信息位置左移 | `bool` | - | 否 |
+| required | 是否必填 | `bool` | - | 否 |
+| unLabelTop | 去掉 label 的上边距 | `bool` | - | 否 |
+| validate | 验证函数（配合 Validator 使用） | `func` | - | 否 |
+| error | 手动设置错误状态 | `bool` | - | 否 |
+| help | 手动设置帮助文本 | `string` | - | 否 |
+| labelWidth | label 宽度（一般由 Form 传入） | `string` | - | 否 |
+| colWidth | 列宽（一般由 Form 传入） | `string` | - | 否 |
+| canValidate | 是否可验证（由 Form 内部控制） | `bool` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### FormBlock Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| col | 占用栏数 | `1 \| 2 \| 3` | `1` | 否 |
+| disabledCol | 禁用列宽限制（Form 传入，不要手动设置） | `bool` | - | 否 |
+| inline | 行内模式（Form 传入，不要手动设置） | `bool` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+### FormButton Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| labelWidth | label 宽度（由 Form 传入） | `string` | - | 否 |
+| btnPosition | 按钮位置 | `'center' \| 'left' \| 'right'` | - | 否 |
+
+### FormGroup Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| formRefs | 所有 Form 的 ref 数组 | `array` | - | 是 |
+| onSubmit | 提交回调 | `func` | - | 否 |
+| onSubmitValidated | 验证通过后回调 | `func` | - | 否 |
+| onCancel | 取消回调 | `func` | - | 否 |
+| disabled | 是否禁用提交按钮 | `bool` | - | 否 |
+| saveText | 保存按钮文案 | `string` | `'保存'` | 否 |
+| actions | 额外操作按钮 | `element` | - | 否 |
+
+### FormPanel Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| title | 面板标题 | `string` | - | 否 |
+| left | 标题左侧自定义元素 | `element` | - | 否 |
+| right | 标题右侧自定义元素 | `element` | - | 否 |
+| showBorder | 是否显示分割线 | `bool` | `true` | 否 |
+
+### FormPanel.More Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| children | 展开更多时显示的内容 | `any` | - | 否 |
+
+## 示例
+
+### 单栏表单
+```jsx
+<Form disabledCol labelWidth='100px' onSubmit={() => console.log('submit')}>
+  <FormItem label='名字' required>
+    <input
+      type='text'
+      value={name}
+      onChange={e => setName(e.target.value)}
+    />
+  </FormItem>
+  <FormItem label='地区'>
+    <Select data={area} value={areaValue} onChange={setAreaValue} />
+  </FormItem>
+  <FormButton>
+    <Button type='primary' htmlType='submit'>提交</Button>
+  </FormButton>
+</Form>
+```
+
+### 多栏表单
+```jsx
+<Form labelWidth='100px' onSubmit={() => console.log('submit')}>
+  <FormBlock col={2}>
+    <FormItem label='名字' required>
+      <input type='text' value={name} onChange={e => setName(e.target.value)} />
+    </FormItem>
+    <FormItem label='地区'>
+      <Select data={area} value={areaValue} onChange={setAreaValue} />
+    </FormItem>
+  </FormBlock>
+  <FormButton>
+    <Button type='primary' htmlType='submit'>提交</Button>
+  </FormButton>
+</Form>
+```
+
+### 表单验证
+```jsx
+import { Validator } from '@gmfe/react'
+
+<FormItem
+  label='描述'
+  required
+  validate={Validator.create([], description)}
+>
+  <textarea value={desc} onChange={e => setDesc(e.target.value)} />
+</FormItem>
+```
+
+### 多表单聚合
+```jsx
+const form1 = useRef(null)
+const form2 = useRef(null)
+
+<FormGroup
+  formRefs={[form1, form2]}
+  onCancel={() => console.log('Cancel')}
+  onSubmitValidated={() => console.log('onSubmitValidated')}
+>
+  <Form ref={form1} labelWidth='100px' hasButtonInGroup>
+    <FormItem label='名字' required>
+      <input type='text' value={name} onChange={e => setName(e.target.value)} />
+    </FormItem>
+  </Form>
+  <Form ref={form2} labelWidth='100px' hasButtonInGroup>
+    <FormItem label='描述' required validate={Validator.create([], desc)}>
+      <textarea value={desc} onChange={e => setDesc(e.target.value)} />
+    </FormItem>
+  </Form>
+</FormGroup>
+```
+
+### FormPanel 面板
+```jsx
+<FormPanel title='店铺设置' left={<Button onClick={handleSearch}>搜索</Button>}>
+  <Form colWidth='400px' ref={formRef} labelWidth='160px' hasButtonInGroup>
+    <FormItem label='名字' required>
+      <input type='text' value={name} onChange={e => setName(e.target.value)} />
+    </FormItem>
+    <FormPanel.More>
+      <FormBlock col={2}>
+        <FormItem label='邀请码' required>
+          <input type='text' value={code} onChange={e => setCode(e.target.value)} />
+        </FormItem>
+      </FormBlock>
+    </FormPanel.More>
+  </Form>
+</FormPanel>
+```
+
+## 注意事项
+- Form 的 `onSubmit` 已内置 `event.preventDefault()`，无需手动调用
+- 单栏表单需要设置 `disabledCol` 属性，否则 FormItem 会被限制在默认宽度内
+- `FormItem` 会自动识别常用的表单元素（input、textarea、select、InputNumber、InputNumberV2）并添加 `form-control` 类名
+- `FormGroup` 中 `onSubmit` 和 `onSubmitValidated` 只需提供一个，不要同时使用
+- `label` 属性不要包含冒号（`:` 或 `：`），组件会自动添加
+- 默认列宽为 320px，FormPanel 中默认为 400px，可通过 `colWidth` 自定义
+- `FormGroup` 会在内容超出屏幕高度时自动吸底按钮区域

package/src/component/function_set/README.md

@@ -0,0 +1,93 @@
+# FunctionSet
+
+## 简介
+功能集组件 - 以弹出菜单形式展示多个功能操作，支持多级嵌套子菜单
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { FunctionSet } from '@gmfe/react'
+
+<FunctionSet
+  data={[
+    { text: '功能1', onClick: () => console.log('功能1') },
+    { text: '功能2', onClick: () => console.log('功能2') }
+  ]}
+/>
+```
+
+## API
+
+### Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| data | 功能项数据，格式：`[{text, disabled, show, onClick, children}]`，支持 `children` 嵌套子菜单 | `array` | - | 是 |
+| right | 弹出层是否右对齐 | `bool` | `false` | 否 |
+| disabled | 是否禁用整个功能集 | `bool` | `false` | 否 |
+| showArrow | 是否显示三角箭头 | `bool` | `false` | 否 |
+| children | 自定义触发器元素 | `any` | - | 否 |
+
+### data 项配置
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| text | 功能项文本 | `string` | - | 是 |
+| onClick | 点击回调 | `function` | - | 否 |
+| disabled | 是否禁用该项 | `bool` | `false` | 否 |
+| show | 是否显示该项 | `bool` | `true` | 否 |
+| children | 子菜单数据，格式与 `data` 相同 | `array` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+<FunctionSet
+  data={[
+    { text: '功能1', onClick: () => alert('功能1') },
+    { text: '功能2', onClick: () => alert('功能2') },
+    { text: '功能3(不可用)', disabled: true },
+    { text: '功能4(不显示)', show: false }
+  ]}
+/>
+```
+
+### 多级子菜单
+```jsx
+<FunctionSet
+  data={[
+    {
+      text: '新建',
+      children: [
+        {
+          text: '商品新建',
+          children: [
+            { text: '商品新建1', onClick: () => alert('商品新建1') },
+            { text: '商品新建2', onClick: () => alert('商品新建2') }
+          ]
+        }
+      ]
+    }
+  ]}
+/>
+```
+
+### 自定义触发器
+```jsx
+<FunctionSet data={data}>
+  <span className="gm-cursor">更多</span>
+</FunctionSet>
+```
+
+### 三角箭头样式
+```jsx
+<FunctionSet showArrow data={data}>
+  <span className="gm-cursor">...</span>
+</FunctionSet>
+```
+
+## 注意事项
+- 当 `data` 为空数组时，组件不会渲染任何内容
+- 功能项必须配置 `onClick` 才能响应点击
+- 子菜单使用 `LevelList` 组件渲染，支持多级嵌套
+- 弹出层默认使用 `hover` 触发模式

package/src/component/grid/README.md

@@ -0,0 +1,93 @@
+# Grid
+
+## 简介
+栅格布局组件 - 基于 24 栅格系统的响应式布局组件，包含 Row 和 Col 两个子组件。
+
+## 安装
+已包含在 `@gmfe/react` 中，无需额外安装。
+
+## 使用
+```jsx
+import { Row, Col } from '@gmfe/react/lib/grid'
+
+<Row>
+  <Col span={12}>左侧</Col>
+  <Col span={12}>右侧</Col>
+</Row>
+```
+
+## API
+
+### Row Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| gutter | 栅格间隔，可传入像素值或响应式对象 `{ xs: 8, sm: 16, md: 24 }` | `number \| object` | `0` | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+| style | 自定义样式 | `object` | - | 否 |
+
+Row 组件继承 Flex 组件的所有属性（`row` 和 `wrap` 已默认开启）。
+
+### Col Props
+| 属性 | 说明 | 类型 | 默认值 | 必填 |
+|------|------|------|--------|------|
+| span | 栅格占位格数，为 0 时相当于 `display: none` | `number` | - | 否 |
+| offset | 栅格左侧的间隔格数 | `number` | - | 否 |
+| sm | 768px 响应式栅格，可为栅格数或包含 span/offset 的对象 | `number \| {span, offset}` | - | 否 |
+| md | 992px 响应式栅格，可为栅格数或包含 span/offset 的对象 | `number \| {span, offset}` | - | 否 |
+| lg | 1200px 响应式栅格，可为栅格数或包含 span/offset 的对象 | `number \| {span, offset}` | - | 否 |
+| xl | 1920px 响应式栅格，可为栅格数或包含 span/offset 的对象 | `number \| {span, offset}` | - | 否 |
+| className | 自定义类名 | `string` | - | 否 |
+
+## 示例
+
+### 基础用法
+```jsx
+// 占满 24 栅格
+<Row>
+  <Col span={24}>Col 24</Col>
+</Row>
+
+// 三等分
+<Row>
+  <Col span={8}>Col 8</Col>
+  <Col span={8}>Col 8</Col>
+  <Col span={8}>Col 8</Col>
+</Row>
+
+// 左偏移
+<Row>
+  <Col span={8}>Col 8</Col>
+  <Col span={8} offset={8}>Col 8, Offset 8</Col>
+</Row>
+```
+
+### 响应式布局
+```jsx
+<Row>
+  <Col sm={{ span: 4, offset: 4 }} md={{ span: 5, offset: 1 }} lg={{ span: 6, offset: 2 }} xl={8}>
+    Col
+  </Col>
+  <Col sm={{ span: 4, offset: 4 }} md={{ span: 11, offset: 1 }} lg={{ span: 6, offset: 2 }} xl={8}>
+    Col
+  </Col>
+  <Col sm={{ span: 4, offset: 4 }} md={{ span: 5, offset: 1 }} lg={{ span: 6, offset: 2 }} xl={8}>
+    Col
+  </Col>
+</Row>
+```
+
+### 间隔设置
+```jsx
+<Row gutter={8}>
+  <Col span={8}>Col 8</Col>
+  <Col span={8}>Col 8</Col>
+  <Col span={8}>Col 8</Col>
+</Row>
+```
+
+## 注意事项
+- 栅格系统基于 24 格
+- Row 组件默认开启了 `row`（水平排列）和 `wrap`（自动换行）属性
+- 响应式断点：`sm` = 768px, `md` = 992px, `lg` = 1200px, `xl` = 1920px
+- `span` 设为 0 时，该列不会显示（相当于 `display: none`）
+- 设置 `gutter` 后，Col 会自动添加左右内边距