@qin-ui/antdv-next-pro 1.1.14 → 1.2.0

package/AI-CONTEXT.md

@@ -1,37 +1,295 @@
-# @qin-ui/antdv-next-pro
+# @qin-ui/antdv-next-pro — AI 上下文
 
-> 基于 antdv-next 的配置驱动表单和表格组件库。
+> Schema-driven Vue 3 高级组件库，基于 antdv-next。用 JavaScript 对象描述 UI，而非在模板中堆砌组件标签。
 
-## 安装
+---
 
-```bash
-npm install @qin-ui/antdv-next-pro antdv-next vue
+## 1. 架构概览
+
+### 1.1 三层架构
+
+```
+┌─────────────────────────────────────────────────┐
+│  Field[] 配置层（用户编写的 JS 对象）              │
+├─────────────────────────────────────────────────┤
+│  @qin-ui/antdv-next-pro（Schema 解析 + 属性分层）  │
+│  逐层剥离 → Grid→a-col, FormItem→a-form-item,     │
+│  剩余属性→输入控件                                  │
+├─────────────────────────────────────────────────┤
+│  antdv-next（Vue 3 组件库）                        │
+│  a-input / a-select / a-date-picker / a-table ... │
+└─────────────────────────────────────────────────┘
+```
+
+ProForm/ProTable 是**渲染引擎**，不是组件库。Field 属性被逐层剥离分发到不同层级的 antdv-next 组件。
+
+### 1.2 组件解析链
+
+```
+Field.component  →  componentMap[component]  →  antdv-next 组件
+  'input'         →  Input          (a-input)
+  'select'        →  Select         (a-select)
+  'switch'        →  Switch         (a-switch)
+  'custom'        →  VueComponent   (直接渲染)
+  'my-custom'     →  ProComponentProvider 注入的自定义组件
+```
+
+### 1.3 内置组件映射表
+
+| component           | antdv-next 组件 | 常用输入控件层透传 Props                                               |
+| :------------------ | :-------------- | :--------------------------------------------------------------------- |
+| `input`             | Input           | placeholder, maxlength, allowClear, addonBefore, addonAfter, showCount |
+| `textarea`          | TextArea        | rows, maxlength, showCount, autoSize                                   |
+| `input-password`    | InputPassword   | placeholder, maxlength, visibilityToggle                               |
+| `input-otp`         | InputOTP        | length, mask, separator                                                |
+| `input-search`      | InputSearch     | placeholder, loading, onSearch                                         |
+| `input-number`      | InputNumber     | min, max, step, precision, formatter, parser                           |
+| `select`            | Select          | **options**, mode, showSearch, allowClear, maxTagCount, loading        |
+| `auto-complete`     | AutoComplete    | **options**, filterOption, allowClear                                  |
+| `cascader`          | Cascader        | **options**, fieldNames, showSearch, expandTrigger                     |
+| `date-picker`       | DatePicker      | picker, format, showTime, disabledDate, allowClear                     |
+| `range-picker`      | RangePicker     | format, showTime, disabledDate, allowClear                             |
+| `time-picker`       | TimePicker      | format, showSecond, allowClear, hourStep                               |
+| `time-range-picker` | TimeRangePicker | format, allowClear                                                     |
+| `checkbox-group`    | CheckboxGroup   | **options**, direction                                                 |
+| `radio-group`       | RadioGroup      | **options**, direction, buttonStyle                                    |
+| `switch`            | Switch          | checkedChildren, unCheckedChildren, loading                            |
+| `slider`            | Slider          | min, max, step, marks, range, tooltip                                  |
+| `tree-select`       | TreeSelect      | **treeData**, showSearch, treeCheckable                                |
+| `transfer`          | Transfer        | **dataSource**, **titles**, **targetKeys**, showSearch                 |
+| `custom`            | 自定义          | component 传入 Vue 组件或 h() 渲染函数                                 |
+
+> **写任何输入控件属性前，必须查阅 [antdv-next 文档](https://antdv-next.com/llms-full-cn.txt) 确认属性名和类型。**
+
+---
+
+## 2. 属性分层传递（核心规则）
+
+Field 属性逐层剥离，分发到渲染树的不同目标：
+
+```html
+<a-col :span="8">
+  <a-form-item label="城市" :rules="[...]">
+    <a-select placeholder="选择" :options="[...]" />
+  </a-form-item>
+</a-col>
+```
+
+### 属性归属
+
+**Grid 层 → `<a-col>`**（仅 grid 启用时生效）
+`span`, `order`, `offset`, `push`, `pull`, `flex`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`
+
+**FormItem 层 → `<a-form-item>`**
+`label`, `rules`, `colon`, `labelAlign`, `labelCol`, `wrapperCol`, `tooltip`, `extra`, `help`, `validateFirst`, `validateTrigger`, `valuePropName`, `normalize`, `formItemClass`, `formItemStyle`, `formItemContainer`, `formItemDataAttrs`
+
+**输入控件层 → 输入组件**
+其余所有属性（`disabled`, `placeholder`, `allowClear`, `options`, `showSearch`, `maxlength`, `mode`, `componentDataAttrs`, `componentClass`, `componentStyle` 等）
+
+**ProForm 消费（不绑定 DOM）：** `component`, `fields`, `hidden`, `slots`, `modelProp`, `valueFormatter`, `componentContainer`, `extraProps`
+
+### modelProp
+
+决定 `v-model:xxx` 绑定变量名：
+
+- 默认 `'value'` → `v-model:value`
+- Switch/Checkbox 使用 `'checked'`
+- **ProComponentProvider 已为 `switch` 预设 `modelProp: 'checked'`**，通常无需手动指定
+
+---
+
+## 3. 渐进式用法
+
+### 第一阶段：配置驱动
+
+**禁止在模板中手写 `<a-form-item>` 或 `<a-input>`。**
+
+```typescript
+import { ProForm, useForm } from '@qin-ui/antdv-next-pro';
+
+const form = useForm({ username: '', password: '' }, [
+  {
+    path: 'username',
+    component: 'input',
+    label: '用户名',
+    placeholder: '请输入用户名',
+    rules: [{ required: true, message: '请输入' }],
+  },
+  {
+    path: 'password',
+    component: 'input-password',
+    label: '密码',
+    placeholder: '请输入密码',
+    rules: [{ required: true, message: '请输入' }],
+  },
+]);
+```
+
+```html
+<template>
+  <ProForm :form="form" />
+</template>
+```
+
+### 第二阶段：字段联动
+
+`disabled`、`hidden`、`rules` 等控制属性支持多种联动方式：
+
+```typescript
+import { computed, ref } from 'vue';
+
+const form = useForm({ hasLimit: false, limitCount: undefined }, [
+  { path: 'hasLimit', component: 'switch', label: '开启限制' },
+  {
+    path: 'limitCount',
+    component: 'input-number',
+    label: '限制次数',
+    // 方式一：computed() — 声明式，推荐用于初始化时已知的联动
+    disabled: computed(() => !form.formData.hasLimit),
+    rules: computed(() => [
+      { required: form.formData.hasLimit, message: '请输入' },
+    ]),
+  },
+]);
+
+// 方式二：ref() — 适合外部状态控制
+const isDisabled = ref(false); // disabled: isDisabled
+
+// 方式三：setField() — 命令式，适合运行时事件触发
+form.setField('limitCount', { disabled: true });
+```
+
+**选择：** 初始化联动 → `computed()`；运行时事件 → `setField()`；外部共享状态 → `ref()`。代码越简单越好。
+
+### 第三阶段：自定义扩展
+
+```typescript
+import { h } from 'vue';
+
+const form = useForm({ agreement: false }, [
+  {
+    path: 'agreement',
+    component: (p, ctx) => h(MyCheckbox, { ...p, ...ctx.attrs }),
+    modelProp: 'checked',
+    rules: [
+      {
+        validator: (_, val) =>
+          val ? Promise.resolve() : Promise.reject('请同意'),
+      },
+    ],
+  },
+]);
+```
+
+```html
+<ProForm :form="form">
+  <!-- 同名插槽接管渲染，scoped 内置 value/checked 等绑定参数 -->
+  <template #agreement="scoped">
+    <a-checkbox v-bind="scoped">同意协议</a-checkbox>
+  </template>
+</ProForm>
+```
+
+---
+
+## 4. 反模式
+
+```ts
+// ❌ 不要手写 a-form-item — ProForm 自动渲染
+// ❌ 不要猜测属性名 — 必须查阅 antdv-next 文档
+{ path: 'city', component: 'select', searchable: true }    // 错：Select 没有 searchable
+{ path: 'city', component: 'select', showSearch: true }     // 对：查阅文档后使用 showSearch
+
+// ❌ path 必须精确对应 formData 中的键名，否则数据/校验丢失
+// ✅ 联动优先用 computed()，运行时用 setField()，不要过度设计
+```
+
+---
+
+## 5. ProComponentProvider：全局默认配置
+
+应用顶层统一配置所有子组件默认属性。
+
+**INJECT_CONFIG 预设默认值：**
+
+| 组件                                      | 预设默认值                                                                                                                              |
+| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| `switch`                                  | `{ modelProp: 'checked' }`                                                                                                              |
+| `input`                                   | `{ maxlength: 100, allowClear: true, placeholder: '请输入' }`                                                                           |
+| `textarea`                                | `{ maxlength: 200, autoSize: {minRows:3,maxRows:6}, showCount: true, allowClear: true, placeholder: '请输入' }`                         |
+| `select` / `cascader` / `auto-complete`   | `{ allowClear: true, placeholder: '请选择', getPopupContainer }`                                                                        |
+| `input-number`                            | `{ max: 10^15, min: -(10^15), controls: false, placeholder: '请输入', style: {width:'100%'} }`                                          |
+| `date-picker` / `range-picker` / `time-*` | `{ allowClear: true, getPopupContainer, style: {width:'100%'} }`                                                                        |
+| `pro-table`                               | `{ pagination: {showTotal, showSizeChanger, showQuickJumper}, searchFormConfig: {layout:'grid'}, control: true, addIndexColumn: true }` |
+| `pro-form`                                | `{ grid: { gutter: {xs:8, sm:16, md:16, lg:24} } }`                                                                                     |
+| `pro-form-item`                           | `{ validateFirst: true, span: 8 }`                                                                                                      |
+
+**优先级：** Field 级别配置 > `componentVars` > `INJECT_CONFIG` 预设
+
+```vue
+<template>
+  <ProComponentProvider :component-vars="config">
+    <ProForm :form="form" />
+    <ProTable :table="table" />
+  </ProComponentProvider>
+</template>
+
+<script setup lang="ts">
+import { ProComponentProvider } from '@qin-ui/antdv-next-pro';
+
+const config = {
+  'pro-form-item': { validateFirst: true, span: 6 },
+  input: { maxlength: 200 },
+  select: { showSearch: true },
+  'pro-table': { addIndexColumn: false },
+};
+</script>
 ```
 
-## 核心导出
+---
 
-### 组件
+## 6. ProTable 速览
 
-- `ProForm` - 配置驱动表单组件
-- `ProTable` - 配置驱动表格组件
-- `ProComponentProvider` - 全局配置提供者
+```vue
+<script setup lang="ts">
+import { ProTable, useTable } from '@qin-ui/antdv-next-pro';
 
-### Hooks
+type Row = { id: number; name: string; status: string };
 
-- `useForm<D>()` - 创建表单实例
-- `useFields<D>()` - 字段配置管理
-- `useFormRef()` - 表单组件引用
-- `useTable<D, T>()` - 创建表格实例
+const table = useTable<Row>({
+  columns: [
+    { title: 'ID', dataIndex: 'id', width: 80 },
+    { title: '姓名', dataIndex: 'name', width: 120 },
+    { title: '状态', dataIndex: 'status', width: 100 },
+  ],
+  // searchFields 格式与 ProForm fields 完全一致，支持相同的分层剥离机制
+  searchFields: [
+    { path: 'name', component: 'input', placeholder: '搜索姓名' },
+    { path: 'status', component: 'select', options: [...], placeholder: '状态' },
+  ],
+});
 
-## 字段配置（Field）
+// searchForm 是 ProForm 实例，可使用所有表单方法
+table.searchForm.setField('name', { placeholder: '请输入' });
+</script>
+
+<template>
+  <ProTable
+    :table="table"
+    :search="() => fetchData()"
+    addIndexColumn
+    immediateSearch
+  />
+</template>
+```
 
-每个字段支持：`path`, `label`, `component`, `hidden`, `disabled`, `rules`, `valueFormatter`, `fields`, `grid`, `slots`, `componentStyle`, `componentClass`, `componentContainer`, `formItemStyle`, `formItemClass`, `formItemContainer`, `modelProp`
+---
 
-内置组件：input, textarea, input-search, input-password, input-number, select, cascader, date-picker, range-picker, time-picker, checkbox-group, radio-group, switch, slider, tree-select, transfer, custom
+## 7. 参考
 
-## 表格列配置（Column）
+按优先级查阅：
 
-- `dataIndex` - 数据路径（优先使用）
-- `key` - 列标识（dataIndex 不满足时使用）
-- `hidden` - 是否隐藏
-- 所有 antdv-next ColumnType 属性
+1. **`node_modules/@qin-ui/antdv-next-pro/api.json`** — 结构化 API 元数据（函数签名、类型定义、JSDoc 示例）
+2. **`node_modules/@qin-ui/antdv-next-pro/README.md`** — 完整使用文档和代码示例
+3. **`https://antdv-next.com/llms-full-cn.txt`** — antdv-next 全部组件 API（确认输入控件层属性时必查）
+4. **`https://antdv-next.com/llms-semantic-cn.md`** — antdv-next 组件语义化 DOM 结构（自定义样式时必查）

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2023-present pro-components
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @qin-ui/antdv-next-pro
 
-> 基于 **antdv-next** 和 **Vue 3.x** 的二次封装高级组件库，提供高度可配置、Schema 驱动的 `ProForm`、`ProTable` 和 `ComponentProvider`。
+> 基于 **antdv-next**（Vue 3 组件库，对齐 Ant Design 设计规范）和 **Vue 3.x** 的二次封装高级组件库，提供高度可配置、Schema 驱动的 `ProForm`、`ProTable` 和 `ProComponentProvider`。
 
 <p align="center">
   <img src="https://img.shields.io/badge/antdv--next-v1.1%2B-blue" alt="antdv-next" />
@@ -63,23 +63,24 @@ const form = useForm<FormData>({}, [
 
 ### `useForm` 返回值 (Form 实例)
 
-| 属性/方法                  | 类型                             | 说明                                                      |
-| :------------------------- | :------------------------------- | :-------------------------------------------------------- |
-| `formRef`                  | `Ref<FormInstance \| undefined>` | AntdvNext FormInstance 引用，支持直接调用 validate 等方法 |
-| `formData`                 | `Reactive<D>`                    | 响应式表单数据对象                                        |
-| `fields`                   | `Ref<Field<D>[]>`                | 响应式字段配置数组                                        |
-| `getFormData(path?)`       | `(path?) => any`                 | 读取表单字段或整个表单的值（支持深层路径）                |
-| `setFormData(path, value)` | `-`                              | 安全更新指定路径的值，支持批量设置与函数式更新            |
-| `setField(path, patch)`    | `-`                              | 动态增量更新某一个字段的 Schema 配置参数                  |
-| `resetFormData()`          | `-`                              | 重置表单数据为初始值                                      |
+| 属性/方法                  | 类型                             | 说明                                                                                                                                                                                             |
+| :------------------------- | :------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formRef`                  | `Ref<FormInstance \| undefined>` | **antdv-next 原生 [FormInstance](https://antdv-next.com/components/form-cn#api)** 引用，可直接调用 `validate()`、`resetFields()`、`validateFields([paths])`、`clearValidate([paths])` 等原生方法 |
+| `formData`                 | `Reactive<D>`                    | 响应式表单数据对象                                                                                                                                                                               |
+| `fields`                   | `Ref<Field<D>[]>`                | 响应式字段配置数组                                                                                                                                                                               |
+| `getFormData(path?)`       | `(path?) => any`                 | 读取表单字段或整个表单的值（支持深层路径）                                                                                                                                                       |
+| `setFormData(path, value)` | `-`                              | 安全更新指定路径的值，支持批量设置与函数式更新                                                                                                                                                   |
+| `setField(path, patch)`    | `-`                              | 动态增量更新某一个字段的 Schema 配置参数                                                                                                                                                         |
+| `resetFormData()`          | `-`                              | 重置表单数据为初始值                                                                                                                                                                             |
 
 ### `ProForm` Props
 
-| 属性     | 类型                   | 默认值  | 说明                                    |
-| :------- | :--------------------- | :------ | :-------------------------------------- |
-| `form`   | `Form<D>`              | -       | `useForm` 返回的实例                    |
-| `grid`   | `boolean \| GridProps` | `false` | 是否启用 Grid 网格布局                  |
-| 其余属性 | `FormProps`            | -       | 继承并直接透传至 antdv-next `Form` 组件 |
+| 属性       | 类型                                                                         | 默认值  | 说明                                                                                     |
+| :--------- | :--------------------------------------------------------------------------- | :------ | :--------------------------------------------------------------------------------------- |
+| `form`     | `Form<D>`                                                                    | -       | `useForm` 返回的实例                                                                     |
+| `grid`     | `boolean \| GridProps`                                                       | `false` | 是否启用 Grid 网格布局                                                                   |
+| `disabled` | `boolean`                                                                    | `false` | 是否全局禁用整个表单                                                                     |
+| 其余属性   | 继承 antdv-next [`FormProps`](https://antdv-next.com/components/form-cn#api) | -       | 如 `labelCol`、`wrapperCol`、`labelAlign`、`colon` 等，直接透传至 antdv-next `Form` 组件 |
 
 ---
 
@@ -89,28 +90,28 @@ const form = useForm<FormData>({}, [
 
 ### 公共基础属性（`Base`）
 
-| 属性                 | 类型                                | 说明                                                      |
-| :------------------- | :---------------------------------- | :-------------------------------------------------------- |
-| `path`               | `Path<D>`                           | 字段标识，需对应 `formData` 中的 key                      |
-| `label`              | `string \| Component`               | 字段标签名称，支持直接传入 Vue 组件渲染                   |
-| `component`          | 见下方内置组件列表                  | 使用的内置组件名或自定义组件                              |
-| `hidden`             | `MaybeRef<boolean>`                 | 字段是否隐藏，支持 Ref / Computed 响应式                  |
-| `disabled`           | `MaybeRef<boolean>`                 | 组件是否禁用，支持 Ref / Computed 响应式                  |
-| `rules`              | `FormItemRule[]`                    | 字段数据校验规则                                          |
-| `span`               | `number`                            | Grid 占位列宽（仅在开启 `grid` 模式下有效）               |
-| `slots`              | `Partial<ComponentSlots<FormItem>>` | FormItem 插槽（包含 `label`/`extra`/`help`/`tooltip` 等） |
-| `grid`               | `boolean \| GridProps`              | 嵌套子字段的 Grid 配置                                    |
-| `fields`             | `Fields<D>`                         | 嵌套子字段配置数组（用于复杂分组）                        |
-| `formItemStyle`      | `CSSProperties`                     | FormItem 样式属性                                         |
-| `formItemClass`      | `string`                            | FormItem 自定义类名                                       |
-| `formItemContainer`  | `Component`                         | FormItem 外层包裹容器组件                                 |
-| `formItemDataAttrs`  | `Record<string, string>`            | 附加到 FormItem DOM 节点上的自定义 data 属性              |
-| `componentStyle`     | `CSSProperties`                     | 表单输入组件的样式属性                                    |
-| `componentClass`     | `string`                            | 表单输入组件的自定义类名                                  |
-| `componentContainer` | `Component`                         | 表单输入组件的外层包裹容器组件                            |
-| `componentDataAttrs` | `Record<string, string>`            | 附加到输入组件 DOM 节点上的自定义 data 属性               |
-| `valueFormatter`     | `ValueFormatter`                    | 字段值格式化与转换器（支持 get/set 双向处理器）           |
-| `modelProp`          | `string`                            | 双向绑定的数据名，默认 `'value'`                          |
+| 属性                 | 类型                                | 说明                                                                                                                |
+| :------------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
+| `path`               | `Path<D>`                           | 字段标识，需对应 `formData` 中的 key                                                                                |
+| `label`              | `string \| Component`               | 字段标签名称，支持直接传入 Vue 组件渲染                                                                             |
+| `component`          | 见下方内置组件列表                  | 使用的内置组件名或自定义组件                                                                                        |
+| `hidden`             | `MaybeRef<boolean>`                 | 字段是否隐藏，支持 Ref / Computed 响应式                                                                            |
+| `disabled`           | `MaybeRef<boolean>`                 | 组件是否禁用，支持 Ref / Computed 响应式                                                                            |
+| `rules`              | `FormItemRule[]`                    | 字段数据校验规则                                                                                                    |
+| `span`               | `number`                            | Grid 占位列宽（仅在开启 `grid` 模式下有效）                                                                         |
+| `slots`              | `Partial<ComponentSlots<FormItem>>` | FormItem 插槽（包含 `label`/`extra`/`help`/`tooltip` 等）                                                           |
+| `grid`               | `boolean \| GridProps`              | 嵌套子字段的 Grid 配置                                                                                              |
+| `fields`             | `Fields<D>`                         | 嵌套子字段配置数组（用于复杂分组）                                                                                  |
+| `formItemStyle`      | `CSSProperties`                     | FormItem 样式属性                                                                                                   |
+| `formItemClass`      | `string`                            | FormItem 自定义类名                                                                                                 |
+| `formItemContainer`  | `Component`                         | FormItem 外层包裹容器组件                                                                                           |
+| `formItemDataAttrs`  | `Record<string, string>`            | 附加到 FormItem DOM 节点上的自定义 data 属性                                                                        |
+| `componentStyle`     | `CSSProperties`                     | 表单输入组件的样式属性                                                                                              |
+| `componentClass`     | `string`                            | 表单输入组件的自定义类名                                                                                            |
+| `componentContainer` | `Component`                         | 表单输入组件的外层包裹容器组件                                                                                      |
+| `componentDataAttrs` | `Record<string, string>`            | 附加到输入组件 DOM 节点上的自定义 data 属性                                                                         |
+| `valueFormatter`     | `ValueFormatter`                    | 字段值格式化与转换器（支持 get/set 双向处理器）                                                                     |
+| `modelProp`          | `string`                            | 双向绑定的数据名，默认 `'value'`。Switch/Checkbox 使用 `'checked'`，**ProComponentProvider 已为 `switch` 预设此值** |
 
 > [!NOTE]
 > **响应式支持**：除了 `component`、`fields`、`slots`、`modelProp`、`formItemContainer`、`componentContainer`、`valueFormatter` 之外，所有属性均高度支持 `Ref` 或 `ComputedRef` 响应式数据。
@@ -215,42 +216,58 @@ const table = useTable<Row>({
 
 ### `useTable` 配置参数
 
-| 参数名         | 类型             | 说明                                              |
-| :------------- | :--------------- | :------------------------------------------------ |
-| `columns`      | `Column<D>[]`    | 表格列 Schema 配置，支持响应式 `hidden`           |
-| `dataSource`   | `T[]`            | 静态初始数据源数组                                |
-| `pageParam`    | `PageParam`      | 初始分页参数（current, pageSize, total）          |
-| `searchParam`  | `DeepPartial<D>` | 搜索栏表单初始填充数据                            |
-| `searchFields` | `Fields<D>`      | 搜索栏字段 Schema 配置（格式与 ProForm 完全一致） |
+| 参数名         | 类型             | 说明                                                                                            |
+| :------------- | :--------------- | :---------------------------------------------------------------------------------------------- |
+| `columns`      | `Column<D>[]`    | 表格列 Schema 配置，支持响应式 `hidden`                                                         |
+| `dataSource`   | `T[]`            | 静态初始数据源数组                                                                              |
+| `pageParam`    | `PageParam`      | 初始分页参数（current, pageSize, total）                                                        |
+| `searchParam`  | `DeepPartial<D>` | 搜索栏表单初始填充数据                                                                          |
+| `searchFields` | `Fields<D>`      | 搜索栏字段 Schema 配置，**格式与 ProForm 的 `fields` 完全一致**，同样支持配置驱动渲染和属性透传 |
+
+### `useTable` 返回值 (Table 实例)
+
+| 属性/方法          | 类型                  | 说明                                                                                       |
+| :----------------- | :-------------------- | :----------------------------------------------------------------------------------------- |
+| `columns`          | `Ref<Column<T>[]>`    | 响应式表格列配置数组                                                                       |
+| `dataSource`       | `Ref<T[]>`            | 响应式表格数据源                                                                           |
+| `pageParam`        | `Reactive<PageParam>` | 响应式分页参数：`{ current, pageSize, total }`                                             |
+| `searchForm`       | `Form<D>`             | 搜索栏 ProForm 实例，可通过 `searchForm.formData` 获取搜索条件，也可调用其所有字段操作方法 |
+| `setColumn`        | `(path, col, opts?)`  | 动态合并/覆盖列配置（`opts.updateType: 'merge' \| 'rewrite'`）                             |
+| `deleteColumn`     | `(path, opts?)`       | 根据 dataIndex 路径或查找函数删除列                                                        |
+| `appendColumn`     | `(path, col, opts?)`  | 在指定列后追加新列                                                                         |
+| `prependColumn`    | `(path, col, opts?)`  | 在指定列前插入新列                                                                         |
+| `setPageParam`     | `(pageParam)`         | 更新分页参数（支持局部属性或函数式更新）                                                   |
+| `resetQueryParams` | `()`                  | 重置分页状态和搜索表单数据至初始值                                                         |
 
 ### `ProTable` Props
 
-| 属性               | 类型                                        | 默认值  | 说明                                              |
-| :----------------- | :------------------------------------------ | :------ | :------------------------------------------------ |
-| `table`            | `Table<D>`                                  | -       | 由 `useTable` 返回的表格实例引用                  |
-| `search`           | `() => Promise<void>`                       | -       | 触发表格数据查询的异步回调函数                    |
-| `addIndexColumn`   | `boolean`                                   | `false` | 是否自动在表格首列插入序号列                      |
-| `immediateSearch`  | `boolean`                                   | `false` | 表格挂载完毕（onMounted）是否立即触发一次查询回调 |
-| `control`          | `boolean \| { sizeControl, columnControl }` | `true`  | 是否展示表格右上角尺寸调节和列显示控制条          |
-| `searchFormConfig` | `SearchFormConfig`                          | -       | 搜索栏表单的排版布局及展开/收起配置参数           |
-| `tableContainer`   | `Component \| false`                        | -       | 表格区域外层自定义包裹组件                        |
+| 属性               | 类型                                                                           | 默认值  | 说明                                                                                  |
+| :----------------- | :----------------------------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------ |
+| `table`            | `Table<D>`                                                                     | -       | 由 `useTable` 返回的表格实例引用                                                      |
+| `search`           | `() => Promise<void>`                                                          | -       | 触发表格数据查询的异步回调函数                                                        |
+| `addIndexColumn`   | `boolean`                                                                      | `false` | 是否自动在表格首列插入序号列                                                          |
+| `immediateSearch`  | `boolean`                                                                      | `false` | 表格挂载完毕（onMounted）是否立即触发一次查询回调                                     |
+| `control`          | `boolean \| { sizeControl, columnControl }`                                    | `true`  | 是否展示表格右上角尺寸调节和列显示控制条                                              |
+| `searchFormConfig` | `SearchFormConfig`                                                             | -       | 搜索栏表单的排版布局及展开/收起配置参数                                               |
+| `tableContainer`   | `Component \| false`                                                           | -       | 表格区域外层自定义包裹组件                                                            |
+| 其余属性           | 继承 antdv-next [`TableProps`](https://antdv-next.com/components/table-cn#api) | -       | 如 `bordered`、`loading`、`size`、`pagination` 等，直接透传至 antdv-next `Table` 组件 |
 
 ---
 
-## ⚙️ ComponentProvider
+## ⚙️ ProComponentProvider
 
-全局或局部的默认配置提供者，通过在最外层包裹 `ComponentProvider`，传入 `componentVars` 属性，能够极其优雅地控制其所有子组件的默认配置。
+全局或局部的默认配置提供者，通过在最外层包裹 `ProComponentProvider`，传入 `componentVars` 属性，能够极其优雅地控制其所有子组件的默认配置。
 
 ```vue
 <template>
-  <ComponentProvider :component-vars="config">
+  <ProComponentProvider :component-vars="config">
     <ProForm :form="form" />
     <ProTable :table="table" />
-  </ComponentProvider>
+  </ProComponentProvider>
 </template>
 
 <script setup lang="ts">
-import { ComponentProvider } from '@qin-ui/antdv-next-pro';
+import { ProComponentProvider } from '@qin-ui/antdv-next-pro';
 
 const config = {
   'pro-form': { grid: { gutter: 24 } },