@fangxinyan/lumina 0.6.18 → 0.7.0

package/docs/llms/message.md

@@ -27,7 +27,7 @@ message.success("已上传 5 个文件", "上传完成");
 
 ### 对象调用
 
-支持 content / duration / key / destroy,适合需要更新或手动关闭的提示。
+支持 content / message / duration / key / onClose；相同 key 会原位更新并重新计算自动关闭时间。
 
 ```tsx
 message.open({ key: "sync", type: "info", content: "同步中...", duration: 0 });
@@ -37,19 +37,42 @@ setTimeout(() => {
 message.destroy("sync");
 ```
 
+### 调用重载与精确关闭
+
+第二参数为 number 时表示毫秒时长，否则表示标题；数字 key 请用 dismissByKey，内部 id 请用 dismissById，避免语义冲突。
+
+```tsx
+const id = message.info("2 秒后关闭", 2000, onClose);
+message.dismissById(id);
+
+message.open({ key: 7, content: "数字 key", duration: 0 });
+message.dismissByKey(7);
+```
+
 ## API
 
 **message.***
 
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| info(message, title?) | `(msg, title?) => id` | — | 信息提示 |
-| success(message, title?) | `(msg, title?) => id` | — | 成功 |
-| warning(message, title?) / warn(message, title?) | `(msg, title?) => id` | — | 警告 |
-| error(message, title?) | `(msg, title?) => id` | — | 错误 |
-| open({ type, content, title?, duration?, key? }) | `(config) => id` | — | 对象配置 API |
-| dismiss(id) | `(id: number) => void` | — | 关闭一条 |
-| destroy(key?) / clear() | `(key?) => void` | — | 关闭指定 key 或清空全部 |
+| info / success / warning / warn / error | `(content | config, duration | title?, onClose?) => id` | — | 语义消息；第二参数为数字时表示时长，否则表示标题；第三参数为关闭回调 |
+| open(config) / show(config) | `(config: MessageConfig) => id` | — | 完整配置 API；相同 key 更新原消息 |
+| dismissById(id) | `(id: number) => void` | — | 按内部返回 id 精确关闭 |
+| dismissByKey(key) | `(key: React.Key) => void` | — | 按业务 key 精确关闭，数字 key 也不会被当成 id |
+| dismiss(idOrKey) | `(idOrKey: number | React.Key) => void` | — | 兼容 API：优先匹配现有 key，没有同值 key 时数字才按 id 处理 |
+| destroy(idOrKey?) / clear() | `(idOrKey?) => void` | — | destroy 兼容 dismiss；不传参数或 clear() 会清空全部 |
+
+
+**MessageConfig**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| content / message | `ReactNode` | — | 消息正文；message 是 content 的别名 |
+| title | `ReactNode` | — | 正文上方的可选标题 |
+| type | `"info" | "success" | "warning" | "error"` | `"info"` | 语义类型 |
+| duration | `number` | `3200` | 自动关闭时间(ms)，0 表示常驻 |
+| key | `React.Key` | — | 稳定业务键；同 key 调用会更新并重置计时器 |
+| onClose | `() => void` | — | 自动关闭、手动关闭或 clear 时执行一次 |
 
 
 **MessageContainer**

package/docs/llms/modal.md

@@ -12,6 +12,8 @@ import { Modal } from "@fangxinyan/lumina";
 
 ### 基础
 
+打开后自动聚焦并限制焦点，锁定页面滚动；关闭后把焦点归还给触发控件。
+
 ```tsx
 <Modal open={m} onClose={...} title="标题">...</Modal>
 ```
@@ -89,18 +91,26 @@ closable={false} 隐藏右上角 ×,closeIcon 可自定义。
 <Modal closeIcon={<Icon name="chevDown" />} />
 ```
 
-### 正文容器控制
+### 拟态阴影安全区
 
-bodyClassName / bodyStyle / bodyProps 可直接作用到正文容器；bodyOverflow 用于切换滚动或允许拟态阴影外溢。
+正文默认根据当前阴影强度预留安全区，Card 等凸起组件贴近边缘时不会再被滚动容器裁切；全宽图片或表格可用 bodyInset="none" 取消留白。
 
 ```tsx
 <Modal
-  bodyClassName="settings-modal-body"
-  bodyStyle={{ maxHeight: 260, padding: 12 }}
-  bodyOverflow="visible"
+  bodyStyle={{ maxHeight: 260 }}
   bodyProps={{ "data-panel": "settings" }}
 >
-  ...
+  <Card title="同步设置">拟态阴影由 Modal 自动保护。</Card>
+</Modal>
+```
+
+### 嵌套浮层与 Esc 顺序
+
+子 Select 即使 Portal 到对话框之外，也会保持在 Modal 上方并参与同一焦点范围；连续按 Esc 会先关 Select，再关 Modal。
+
+```tsx
+<Modal open={open} onClose={() => setOpen(false)} destroyOnClose>
+  <Select defaultOpen options={[...]} />
 </Modal>
 ```
 
@@ -111,7 +121,7 @@ bodyClassName / bodyStyle / bodyProps 可直接作用到正文容器；bodyOverf
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | open \* | `boolean` | — | 是否可见 |
-| onClose | `() => void` | — | 关闭回调(遮罩/Esc/关闭按钮) |
+| onClose | `() => void` | — | 关闭回调(遮罩/Esc/关闭按钮)；Esc 仅由当前最上层浮层响应 |
 | onOk | `() => void` | — | 默认 OK 按钮点击 |
 | onCancel | `() => void` | — | 默认 Cancel 按钮 / Esc / 关闭 / 遮罩触发,缺省则用 onClose |
 | title / description | `ReactNode` | — | 标题/说明 |
@@ -123,16 +133,18 @@ bodyClassName / bodyStyle / bodyProps 可直接作用到正文容器；bodyOverf
 | bodyStyle | `CSSProperties` | — | 正文容器内联样式 |
 | bodyProps | `HTMLAttributes<HTMLDivElement>` | — | 透传给正文容器的 DOM props |
 | bodyOverflow | `CSSProperties['overflow']` | — | 正文容器 overflow 快捷控制 |
+| bodyInset | `"safe" | "none"` | `"safe"` | 正文边缘留白；safe 自动保护拟态阴影，none 用于贴边内容 |
 | closable | `boolean` | `true` | 显示右上角 × |
 | closeIcon | `ReactNode` | — | 自定义关闭图标 |
 | maskClosable | `boolean` | `true` | 点击遮罩关闭 |
 | maskClassName | `string` | — | 遮罩层 className |
 | maskStyle | `CSSProperties` | — | 遮罩层内联样式 |
+| className | `string` | — | 对话框面板 className；ref 同样指向面板 |
 | escClosable | `boolean` | `true` | Esc 关闭 |
 | width | `number | string` | `440` | 宽度 |
 | destroyOnClose | `boolean` | `false` | 关闭时卸载子树 |
 | afterOpenChange | `(open: boolean) => void` | — | 动画结束后回调 |
-| zIndex | `number` | — | 覆盖遮罩 z-index |
+| zIndex | `number` | — | 覆盖对话框起始层级；所属子浮层会自动排在其上 |
 
 
 **Modal 静态 API**

package/docs/llms/pagination.md

@@ -61,17 +61,25 @@ import { Pagination } from "@fangxinyan/lumina";
 />
 ```
 
+### 边界值归一
+
+负数或非有限 total 按 0 处理；无效 pageSize 回退 10；页码会截断并夹紧到当前有效范围。
+
+```tsx
+<Pagination total={-8} page={99} pageSize={0} siblings={-3} />
+```
+
 ## API
 
 **Pagination**
 
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| total \* | `number` | — | 数据总条数 |
-| pageSize | `number` | `10` | 每页条数 |
-| page / defaultPage | `number` | `1` | 受控/初始页码 |
+| total \* | `number` | — | 数据总条数；负数或非有限值按 0 处理并取整数 |
+| pageSize | `number` | `10` | 每页条数；非正数或非有限值回退为 10 并取整数 |
+| page / defaultPage | `number` | `1` | 受控/初始页码；取整数并夹紧到 1..总页数 |
 | onChange | `(page: number) => void` | — | 页码变化回调 |
-| siblings | `number` | `1` | 当前页两侧可见的页码数 |
+| siblings | `number` | `1` | 当前页两侧可见页码数；负数归零、非有限值回退 1 |
 | showQuickJumper | `boolean` | `false` | 显示跳转输入框,按 Enter 跳转 |
 | showSizeChanger | `boolean` | `false` | 显示每页条数选择器,切换后回到第 1 页 |
 | pageSizeOptions | `number[]` | `[10, 20, 50, 100]` | 每页条数候选项 |

package/docs/llms/popover.md

@@ -137,6 +137,16 @@ trigger="hover" 鼠标悬停触发
 </Popover>
 ```
 
+### Focus 触发
+
+trigger="focus" 适合键盘可达的补充说明。按 Esc 可关闭并回到触发器。
+
+```tsx
+<Popover trigger="focus" content={<div>通过 Tab 聚焦时显示</div>}>
+  <Button>聚焦查看</Button>
+</Popover>
+```
+
 ### 表单内容
 
 气泡内可放置表单等复杂交互
@@ -168,7 +178,7 @@ trigger="hover" 鼠标悬停触发
 | content \* | `ReactNode` | — | 浮层内容 |
 | title | `ReactNode` | — | 标题 |
 | placement | `"top" | "bottom" | "left" | "right" | ...` | `"bottom"` | 弹出位置,支持 bottomLeft 等细分方向 |
-| trigger | `"click" | "hover"` | `"click"` | 触发方式 |
+| trigger | `"click" | "hover" | "focus"` | `"click"` | 触发方式 |
 | arrow | `boolean` | `false` | 显示箭头 |
 | closable | `boolean` | `false` | 显示关闭按钮 |
 | width | `number | "auto"` | — | 面板宽度，"auto" 自适应 |

package/docs/llms/progress.md

@@ -44,6 +44,7 @@ import { Progress } from "@fangxinyan/lumina";
 | size | `"sm" | "md" | "lg"` | `"md"` | 尺寸 |
 | label | `ReactNode` | — | 顶部文案 |
 | showValue | `boolean` | `false` | 显示百分比 |
+| indeterminate | `boolean` | `false` | 显示不确定进度动画 |
 
 
 ---

package/docs/llms/radio.md

@@ -27,6 +27,15 @@ import { Radio, RadioGroup } from "@fangxinyan/lumina";
 <Radio label="接收更新" defaultChecked />
 ```
 
+### 原生同名分组
+
+独立 Radio 传入相同 name 后仍保持原生互斥，并可用 value 参与表单提交。
+
+```tsx
+<Radio name="billing" value="monthly" defaultChecked label="按月" />
+<Radio name="billing" value="yearly" label="按年" />
+```
+
 ### 水平排列
 
 direction='horizontal'。
@@ -60,6 +69,8 @@ variant="segmented" 用同一组选项表达更紧凑的互斥切换。
 | checked / defaultChecked | `boolean` | — | 受控/初始选中 |
 | onChange | `(checked: boolean) => void` | — | 变更 |
 | label | `ReactNode` | — | 标签 |
+| name / value | `string / string | number` | — | 原生单选分组名与提交值;同名非受控 Radio 自动互斥 |
+| required / form | `boolean / string` | — | 原生表单必填约束与关联 form id |
 | disabled | `boolean` | — | 禁用 |
 
 
@@ -70,6 +81,8 @@ variant="segmented" 用同一组选项表达更紧凑的互斥切换。
 | options \* | `{ value, label, disabled? }[]` | — | 选项数组 |
 | value / defaultValue | `T` | — | 受控/初始 |
 | onChange | `(value: T) => void` | — | 变更 |
+| name | `string` | — | 原生分组名;省略时自动生成 |
+| required / form | `boolean / string` | — | 整组的原生必填约束与关联 form id |
 | direction | `"vertical" | "horizontal"` | `"vertical"` | 方向 |
 | variant | `"default" | "segmented"` | `"default"` | 外观 |
 | size | `"sm" | "md" | "lg"` | `"md"` | 分段外观尺寸 |

package/docs/llms/select.md

@@ -53,6 +53,23 @@ allowClear / showSearch / popupClassName / optionFilterProp 可直接使用。
 />
 ```
 
+### 复杂选项与独立选中渲染
+
+optionRender 承载多行菜单内容；selectedRender 提供适合固定高度触发器的紧凑版本。listHeight 和 popupStyle 可调整浮层尺寸。
+
+```tsx
+<Select
+  aria-label="订阅套餐"
+  value={plan}
+  onChange={setPlan}
+  options={plans}
+  optionRender={(option, info) => <PlanCard option={option} selected={info.selected} />}
+  selectedRender={(option) => <CompactPlan option={option} />}
+  listHeight={420}
+  popupStyle={{ minWidth: "min(460px, calc(100vw - 16px))" }}
+/>
+```
+
 ### 分组
 
 options 接受 { label, options } 表示分组。
@@ -88,17 +105,25 @@ loading 时显示 spinner,emptyContent 自定义空态。
 | options \* | `SelectItem<T>[]` | — | 选项,可含 { label, options } 分组 |
 | value / defaultValue | `T | T[]` | — | 受控/初始 |
 | onChange | `(value) => void` | — | 变更 |
+| placeholder | `string` | `"请选择…"` | 空选择时的提示文本 |
 | multiple | `boolean` | `false` | 多选 |
 | maxTagCount | `number` | — | 多选时显示的标签数(超出折叠 +N) |
 | searchable | `boolean` | `false` | 可搜索 |
 | showSearch | `boolean` | `false` | searchable 的等价别名 |
 | filterOption | `(input, option) => boolean` | — | 自定义过滤 |
 | optionFilterProp | `"label" | "value" | "text" | string` | — | 默认过滤使用的 option 字段 |
-| clearable | `boolean` | `false` | 可清除 |
+| clearable | `boolean` | `false` | 显示独立且可访问的清除按钮 |
 | allowClear | `boolean | { clearIcon? }` | `false` | clearable 的等价别名 |
-| menuClassName / popupClassName | `string` | — | 浮层菜单 className |
+| onClear | `() => void` | — | 用户点击清除按钮后触发 |
+| open / defaultOpen / onOpenChange | `boolean / (open: boolean) => void` | — | 受控或非受控菜单显隐；非受控组件禁用时会关闭 |
+| id / aria-* | `原生属性` | — | 转发到实际 combobox 触发节点，便于 Form.Item 关联标签和错误说明 |
+| menuClassName / popupClassName / dropdownClassName | `string` | — | 浮层菜单 className 别名 |
 | loading | `boolean` | `false` | 加载态 |
 | emptyContent | `ReactNode` | — | 空态文案 |
+| optionRender | `(option, info) => ReactNode` | — | 自定义菜单内完整选项内容，并获得 selected / active / index 状态 |
+| selectedRender | `(option, info) => ReactNode` | — | 自定义触发器中的紧凑已选内容；单选和多选标签均支持 |
+| listHeight | `number` | `260` | 菜单选项滚动区域最大高度 |
+| popupStyle | `CSSProperties` | — | Portal 菜单内联样式，可覆盖宽度或高度 |
 | size | `"sm" | "md" | "lg"` | `"md"` | 尺寸 |
 | invalid | `boolean` | `false` | 错误态 |
 | disabled | `boolean` | `false` | 禁用 |
@@ -110,6 +135,8 @@ loading 时显示 spinner,emptyContent 自定义空态。
 | --- | --- | --- | --- |
 | value \* | `T` | — | 值 |
 | label | `ReactNode` | — | 显示 |
+| text | `string` | — | 复杂 label 的独立搜索文本 |
+| ariaLabel | `string` | — | 复杂选项或 optionRender 的独立可访问名称 |
 | icon | `IconName | ReactNode` | — | 前置图标,可传内置图标名或自定义节点 |
 | description | `ReactNode` | — | 次要描述 |
 | disabled | `boolean` | `false` | 禁用项 |

package/docs/llms/sidebar.md

@@ -16,6 +16,25 @@ import { Sidebar } from "@fangxinyan/lumina";
 <Sidebar items={[{ key, label, icon, badge }]} activeKey={active} onSelect={setActive} />
 ```
 
+### 折叠与多级导航
+
+切换 collapsed 比较完整侧栏与图标轨道；点击含 children 的分组可独立展开或收起。
+
+```tsx
+<Sidebar
+  collapsed={collapsed}
+  expandedKeys={expandedKeys}
+  onExpandedKeysChange={setExpandedKeys}
+  items={[{
+    key: "workspace",
+    label: <span>工作区 <Tag tone="info">团队</Tag></span>,
+    ariaLabel: "工作区",
+    icon: <Icon name="folder" />,
+    children: [{ key: "design", label: "设计系统" }],
+  }]}
+/>
+```
+
 ## API
 
 **Sidebar**
@@ -25,8 +44,11 @@ import { Sidebar } from "@fangxinyan/lumina";
 | items \* | `SidebarItem[]` | — | 导航项 |
 | activeKey | `string` | — | 当前激活项 |
 | onSelect | `(key: string) => void` | — | 选择回调 |
+| expandedKeys / defaultExpandedKeys | `string[]` | — | 受控/初始展开的分组键；省略初始值时默认全部展开 |
+| onExpandedKeysChange | `(keys: string[]) => void` | — | 点击含 children 的分组后返回新的展开键 |
 | collapsed | `boolean` | `false` | 折叠为图标 |
 | header / footer | `ReactNode` | — | 头/尾内容 |
+| navigationLabel | `string` | `"主导航"` | 导航区域可访问名称 |
 
 
 **SidebarItem**
@@ -35,8 +57,10 @@ import { Sidebar } from "@fangxinyan/lumina";
 | --- | --- | --- | --- |
 | key \* | `string` | — | 唯一键 |
 | label | `ReactNode` | — | 文案 |
+| ariaLabel | `string` | — | 复杂标签在折叠状态下使用的可访问名称与 title |
 | icon | `ReactNode` | — | 前置图标 |
 | badge | `ReactNode` | — | 尾部徽标 |
+| children | `SidebarItem[]` | — | 递归子导航项 |
 
 
 ---

package/docs/llms/slider.md

@@ -38,7 +38,8 @@ range 模式下 value / onChange 采用 [min, max] 元组。
 
 ```tsx
 const [v, setV] = useState<[number, number]>([20, 70]);
-<Slider range value={v} onChange={setV} showValue />
+<Slider range value={v} onChange={setV} showValue
+  ariaLabel={["最低值", "最高值"]} />
 ```
 
 ### 渐变色
@@ -70,12 +71,14 @@ marks 配合 colors 可直观表达冷暖等语义。
 | --- | --- | --- | --- |
 | value / defaultValue | `number | [number, number]` | — | 受控/初始;range 模式下为 [number, number] |
 | onChange | `(value) => void` | — | 变更回调,range 模式返回元组 |
-| min / max / step | `number` | — | 区间与步进 |
+| min / max / step | `number` | — | 区间与步进;非法边界或非正步长会安全归一化 |
 | range | `boolean` | `false` | 是否为双滑块区间模式 |
 | marks | `Record<number, ReactNode>` | — | 刻度,点击可跳到对应值 |
 | tone | `"accent" | "success" | "warning" | "danger"` | `"accent"` | 色调 |
 | colors | `string[]` | — | 渐变色数组,按位置插值;覆盖 tone |
 | showValue | `boolean` | `false` | 显示数值 |
+| ariaLabel | `string | [string, string]` | — | 单滑块标签，或区间模式的起点/终点标签;支持方向键及 Home/End |
+| 原生 div 属性 | `HTMLAttributes<HTMLDivElement>` | — | className / style / id / data-* 等会透传到根节点 |
 | disabled | `boolean` | `false` | 禁用 |
 
 

package/docs/llms/splitter.md

@@ -43,11 +43,11 @@ direction="vertical" 让面板上下排列,分隔条变成横条。
 
 ### 受控模式
 
-通过 size / onResize 可以持久化宽度或与其他状态联动。
+通过 size / onResize 与外部状态联动；storageKey 可直接持久化最后一次完成的尺寸。
 
 ```tsx
 const [w, setW] = useState(220);
-<Splitter size={w} onResize={setW}>...</Splitter>
+<Splitter size={w} onResize={setW} storageKey="workspace-sidebar">...</Splitter>
 ```
 
 ## API
@@ -62,6 +62,9 @@ const [w, setW] = useState(220);
 | onResizeEnd | `(n: number) => void` | — | 拖动结束回调 |
 | min / max | `number` | `80 / Infinity` | 尺寸限制 (px) |
 | step | `number` | `16` | 方向键步长 (px) |
+| secondMin | `number` | `24` | 第二面板保留的最小尺寸 |
+| storageKey | `string` | — | 持久化尺寸的本地存储键 |
+| handleProps | `HTMLAttributes<HTMLDivElement>` | — | 分隔手柄原生属性与 aria-label |
 | children \* | `[ReactNode, ReactNode]` | — | 必须恰好两个子节点 |
 
 

package/docs/llms/switch.md

@@ -16,6 +16,17 @@ import { Switch } from "@fangxinyan/lumina";
 <Switch checked={v} onChange={setV} label="开启通知" />
 ```
 
+### 原生表单
+
+开启后按 name / value 参与原生表单提交，required 可交给浏览器校验。
+
+```tsx
+<form onSubmit={(event) => event.preventDefault()}>
+  <Switch name="notifications" value="enabled" required label="开启通知" />
+  <Button type="submit">验证提交</Button>
+</form>
+```
+
 ### 尺寸
 
 提供 sm / md 两档。
@@ -53,6 +64,8 @@ checkedChildren / unCheckedChildren 在轨道内显示简短文字(如 ON/OFF)
 | checkedChildren | `ReactNode` | — | 轨道内选中状态文本/图标 |
 | unCheckedChildren | `ReactNode` | — | 轨道内未选中状态文本/图标 |
 | size | `"sm" | "md"` | `"md"` | 尺寸 |
+| name / value | `string` | — | 原生表单字段名与开启时提交的值 |
+| required / form | `boolean / string` | — | 原生必填约束与关联 form id |
 | disabled | `boolean` | `false` | 禁用 |
 
 

package/docs/llms/table.md

@@ -29,20 +29,20 @@ import { Table } from "@fangxinyan/lumina";
 
 ### 内置分页
 
-传入 pagination 即可自动分页;data 会按当前页切片。传 false 关闭。
+传入 pagination 即可自动分页;这里从第 2 页开始,同时演示 defaultCurrent。传 false 关闭。
 
 ```tsx
 <Table
   rowKey="id"
   columns={[...]}
   data={data}
-  pagination={{ pageSize: 6 }}
+  pagination={{ defaultCurrent: 2, pageSize: 4 }}
 />
 ```
 
 ### 分页配置
 
-覆盖 current / defaultCurrent / pageSize / defaultPageSize / total / onChange / showQuickJumper / showSizeChanger / pageSizeOptions。
+用一个受控案例集中展示 current、pageSize、total、快速跳页和每页条数切换,避免重复堆叠相同表格。
 
 ```tsx
 <Table
@@ -60,11 +60,6 @@ import { Table } from "@fangxinyan/lumina";
     },
   }}
 />
-
-<Table
-  data={allRows}
-  pagination={{ defaultCurrent: 2, defaultPageSize: 4 }}
-/>
 ```
 
 ### 固定表头 / 横向滚动
@@ -208,6 +203,7 @@ filteredValue 由外部状态控制,适合和工具栏筛选器或 URL 状态同
       onFilter: (value, row) => row.status === value,
     },
   ]}
+  onChange={({ filters }) => setFilteredValue(filters.status ?? [])}
 />
 ```
 
@@ -244,6 +240,7 @@ empty 自定义空态;className / style / id / data-* / aria-* 透传到表格
 | sortKey | `string` | — | 当前排序列 key |
 | sortDir | `"asc" | "desc"` | `"asc"` | 当前排序方向 |
 | onSort | `(key) => void` | — | 点击可排序表头时触发 |
+| onChange | `(info: TableChangeInfo) => void` | — | 排序、筛选、分页的统一状态回调 |
 | rowSelection | `RowSelectionConfig` | — | 行选择配置 |
 | selectable | `boolean` | — | 旧版多选开关,优先使用 rowSelection |
 | selected | `(string | number)[]` | — | 旧版受控选中 key |
@@ -251,6 +248,7 @@ empty 自定义空态;className / style / id / data-* / aria-* 透传到表格
 | expandable | `ExpandableConfig` | — | 可展开行配置 |
 | pagination | `false | PaginationConfig` | — | 分页配置;false 关闭 |
 | scroll | `TableScrollConfig` | — | 滚动配置 |
+| tableProps / caption | `TableHTMLAttributes / ReactNode` | — | 透传原生 table 属性与语义标题 |
 | onRowClick | `(row, index) => void` | — | 点击行 |
 | empty | `ReactNode` | `"暂无数据"` | 空数据占位内容 |
 | className / style / id / data-* / aria-* | `native attrs` | — | 透传到外层 table-wrap 容器 |
@@ -286,6 +284,7 @@ empty 自定义空态;className / style / id / data-* / aria-* 透传到表格
 | showQuickJumper | `boolean` | — | 显示跳页输入 |
 | showSizeChanger | `boolean` | — | 显示每页条数下拉选择 |
 | pageSizeOptions | `number[]` | — | 每页条数选项 |
+| mode | `"local" | "remote"` | — | 本地切片或远程预切片 |
 
 
 **TableScrollConfig**