npm - @qin-ui/antd-vue-pro - Versions diffs - 2.2.2 → 2.2.4 - Mend

@qin-ui/antd-vue-pro 2.2.2 → 2.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/AI-CONTEXT.md CHANGED Viewed

@@ -1,236 +1,164 @@
-# @qin-ui/antd-vue-pro — AI Context
+# @qin-ui/antd-vue-pro
-> Schema-driven component library wrapping **ant-design-vue v4** (`a-` prefix). Describe UIs as JS objects instead of template tag soup.
+基于 ant-design-vue v4（`a-` 前缀）封装的 Schema 驱动组件库。
+用 JS 配置对象描述 UI，不写 `<a-*>` 模板堆叠。ProForm/ProTable 是渲染引擎，所有真实 UI 来自 ant-design-vue。
----
+## 安装与使用
-## 1. Architecture
-### 1.1 Three-layer rendering
-```
-Field[] config layer       { path:'name', component:'input', span:8, label:'Name', placeholder:'...' }
-        │
-@qin-ui/antd-vue-pro       Schema parser — strips props layer by layer
-        │
-ant-design-vue v4          a-input / a-select / a-table / a-form-item / a-col  ...
+```bash
+pnpm add @qin-ui/antd-vue-pro   # peerDeps: ant-design-vue ^4, vue ^3.5
 ```
-ProForm/ProTable are **rendering engines**, not a component library. All actual UI comes from ant-design-vue. Field props are peeled off and dispatched to different DOM layers.
+```ts
+// 按需引入（推荐）
+import { ProForm, ProTable, useForm, useTable } from '@qin-ui/antd-vue-pro';
+```
-### 1.2 Component resolution
+## 核心心智模型
-`Field.component` string → `componentMap` → ant-design-vue component.
+**1. 配置驱动**：`useForm(数据, Field[])` / `useTable({ columns, searchFields })` 生成实例，组件接收实例。
-If not found in the built-in map, the string is resolved against `ProComponentProvider` injected components; a Vue component object is rendered directly (used by `'custom'` internally).
+**2. 属性分层透传**（最关键）：Field 上的属性被"剥离到不同 DOM 层"，不是全塞给输入控件。写错层就失效：
-### 1.3 Built-in component map
+| 属性                                                                                                                                                                                                               | 落到哪一层                       | 说明           |
+| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- | :------------- |
+| `span`/`offset`/`push`/`pull`/`flex`/`xs..xxl`                                                                                                                                                                     | `<a-col>` Grid 层                | 仅 grid 开启时 |
+| `label`/`rules`/`tooltip`/`colon`/`labelAlign`/`labelCol`/`wrapperCol`/`extra`/`help`/`validateFirst`/`validateTrigger`/`valuePropName`/`normalize`/`required`/`formItemClass`/`formItemStyle`/`formItemDataAttrs` | `<a-form-item>` 层               | 表单项         |
+| `disabled`/`placeholder`/`allowClear`/`options`/`mode`/`maxlength`/`componentClass`/`componentStyle`/`componentDataAttrs` + 该控件其余 ant 原生属性                                                                | 输入控件本身（a-input 等）       | 其余全部       |
+| `component`/`hidden`/`modelProp`/`valueFormatter`/`fields`/`slots`/`formItemContainer`/`componentContainer`/`extraProps`                                                                                           | ProForm 逻辑消费，**不绑到 DOM** | 框架级         |
-| Field `component`  | ant-design-vue component | Key pass-through props (verify against https://antdv.com)                              |
-| :----------------- | :----------------------- | :------------------------------------------------------------------------------------- |
-| `'input'`          | Input                    | placeholder, maxlength, allowClear, addonBefore, addonAfter, prefix, suffix, showCount |
-| `'textarea'`       | TextArea                 | rows, maxlength, showCount, autoSize                                                   |
-| `'input-password'` | InputPassword            | placeholder, maxlength, visibilityToggle                                               |
-| `'input-search'`   | InputSearch              | placeholder, loading, onSearch                                                         |
-| `'input-number'`   | InputNumber              | min, max, step, precision, formatter, parser                                           |
-| `'select'`         | Select                   | **options**, mode, showSearch, filterOption, allowClear, loading                       |
-| `'cascader'`       | Cascader                 | **options**, fieldNames, showSearch, allowClear                                        |
-| `'date-picker'`    | DatePicker               | picker, format, showTime, disabledDate, valueFormat                                    |
-| `'range-picker'`   | RangePicker              | format, showTime, disabledDate, allowClear                                             |
-| `'time-picker'`    | TimePicker               | format, showSecond, hourStep, minuteStep                                               |
-| `'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, fieldNames                                    |
-| `'transfer'`       | Transfer                 | **dataSource**, **titles**, **targetKeys**, showSearch, render                         |
-| `'custom'`         | (user-supplied)          | component receives a Vue component or `h()` render function                            |
+> 规则：`span` 给 Grid，`label`/`rules` 给 FormItem，其余给输入控件。
-> The prop column is illustrative. **Always verify prop names/types against [antdv.com](https://antdv.com).**
+## 速查
----
+### component 映射（Field.component 字符串 -> ant-design-vue 组件）
-## 2. Property layering (core rule)
+`input`->Input · `textarea`->TextArea · `input-password`->InputPassword · `input-search`->InputSearch ·
+`input-number`->InputNumber · `select`->Select · `cascader`->Cascader · `date-picker`->DatePicker ·
+`range-picker`->RangePicker · `time-picker`->TimePicker · `checkbox-group`->CheckboxGroup ·
+`radio-group`->RadioGroup · `switch`->Switch · `slider`->Slider · `tree-select`->TreeSelect ·
+`transfer`->Transfer · `custom`->用户自定义组件
-Field props are **stripped in layers** and dispatched to different DOM targets.
+> 写 Field 中输入控件的具体属性前，**属性名/类型以 https://antdv.com 官方文档为准**。
-```
-<a-col :span="8">                   ← Grid layer
-  <a-form-item label="City">        ← FormItem layer
-    <a-select placeholder="..." />  ← Input-control layer
-  </a-form-item>
-</a-col>
-```
+### 隐式默认行为（INJECT_CONFIG，易踩坑）
-### 2.1 Layer dispatch
+由 `ProComponentProvider` 注入，优先级低于 Field 配置。**不写也有这些默认值，需知晓以免行为与预期不符：**
-**Grid layer → `<a-col>`** (only when grid is enabled):
-`span`, `order`, `offset`, `push`, `pull`, `flex`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`
+| component                                      | 默认预设                                                                                                                                                                                                                                 |
+| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `switch`                                       | `{ modelProp: 'checked' }` -> v-model 绑 `checked` 而非 `value`                                                                                                                                                                          |
+| `input` / `input-password`                     | `{ maxlength: 100, allowClear: true, placeholder: '请输入' }`                                                                                                                                                                            |
+| `textarea`                                     | `{ maxlength: 200, autoSize: {minRows:3,maxRows:6}, showCount: true, allowClear: true, placeholder: '请输入' }`                                                                                                                          |
+| `input-number`                                 | `{ max: 1e15-1, min: -(1e15+1), controls: false, placeholder: '请输入', style:{width:'100%'} }`                                                                                                                                          |
+| `select` / `cascader`                          | `{ allowClear: true, placeholder: '请选择', getPopupContainer }`                                                                                                                                                                         |
+| `date-picker` / `range-picker` / `time-picker` | `{ allowClear: true, getPopupContainer, style:{width:'100%'} }`                                                                                                                                                                          |
+| `pro-form`                                     | `{ grid: { gutter: {xs:8, sm:16, md:16, lg:24} } }`                                                                                                                                                                                      |
+| `pro-form-item`                                | `{ validateFirst: true, span: 8 }`                                                                                                                                                                                                       |
+| `pro-table`                                    | `{ pagination:{showTotal, showSizeChanger, pageSizeOptions:['10','20','30','40','50','100'], showQuickJumper:true}, searchFormConfig:{layout:'grid', expand:{minExpandRows:2, expandStatus:false}}, control:true, addIndexColumn:true }` |
-**FormItem layer → `<a-form-item>`**:
-`label`, `rules`, `colon`, `labelAlign`, `labelCol`, `wrapperCol`, `tooltip`, `extra`, `help`, `validateFirst`, `validateTrigger`, `valuePropName`, `normalize`, `formItemClass`→`class`, `formItemStyle`→`style`, `formItemContainer`, `formItemDataAttrs`→`data-*`
+> `modelProp` 控制 v-model 绑定名，默认 `'value'`->`v-model:value`。
+> `date-picker` 支持按 picker 子类型分别预设：`date-picker.date` / `.week` / `.month` / `.year` / `.quarter`，默认值同上。
+> `input-search` / `checkbox-group` / `radio-group` / `slider` / `tree-select` / `transfer` 无预设（`{}`）。
-**Input-control layer → the input component** (everything else):
-`disabled`, `placeholder`, `allowClear`, `options`, `showSearch`, `maxlength`, `mode`, `componentClass`→`class`, `componentStyle`→`style`, `componentDataAttrs`→`data-*`, and any ant-design-vue props for that component.
+### 不支持响应式的属性（不能包 ref/computed）
-**Consumed by ProForm logic, not bound to DOM**: `component`, `fields`, `hidden`, `slots`, `modelProp`, `valueFormatter`, `componentContainer`, `extraProps`.
+`component` / `formItemContainer` / `componentContainer` / `valueFormatter` / `fields` / `slots` / `modelProp`。
-### 2.2 modelProp
+## 实例成员速查
-Controls the `v-model:xxx` binding name.
+### useForm -- 表单实例
-- Default: `modelProp: 'value'` → `v-model:value`
-- Switch uses `checked` — **ProComponentProvider presets `modelProp: 'checked'` for `'switch'`** so you rarely set it manually.
-- Override per-field when using a custom component that expects a different v-model prop.
+```ts
+useForm(initFormData, Field[], root = true)   // 重载一（常用）：初始数据 + 字段配置
+useForm(true | false)                          // 重载二：仅拿实例（root）
+```
----
+返回 `Form` 实例（**`formData` 是 reactive 对象，不用 `.value`**）：
-## 3. Progressive usage
+| 成员                                                                                  | 说明                                                                                                                       |
+| :------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------- |
+| `form.formData`                                                                       | 响应式数据，可直接读写，支持深层路径 `formData.address.city`                                                               |
+| `form.getFormData(path)`                                                              | 路径读取；无参返回 `undefined`                                                                                             |
+| `form.setFormData(path, value)` / `setFormData(path, prev=>new)`                      | 路径写入，支持函数式                                                                                                       |
+| `form.setFormData({...})` / `setFormData(prev => ({...prev, name:'新'}))`             | 批量覆盖整个表单，支持函数式（先清空再写入）                                                                               |
+| `form.fields`                                                                         | 字段配置数组（Ref）                                                                                                        |
+| `form.getField(path)` / `getField(fn)`                                                | 字段查找，支持路径或查找函数；`{all:true}` 返回所有匹配数组                                                                |
+| `form.setField(path, patch)` / `setField(path, prev=>({...}))`                        | 字段增改查；默认合并，`{updateType:'rewrite'}` 覆盖；支持函数式更新；`{all:true}` 批量更新所有匹配                         |
+| `form.deleteField` / `form.appendField` / `form.prependField` / `form.getParentField` | 字段增删查；均支持 `{all:true}`；`appendField(undefined, f)` 末尾追加、`prependField(undefined, f)` 开头插入，入参可为数组 |
+| `form.formRef`                                                                        | 底层 ant Form 实例引用（Ref），`formRef.value?.validate()` / `.resetFields()`                                              |
-### Level 1: Config-driven (no hand-written a-\* tags)
+### useTable -- 表格实例
 ```ts
-import { ProForm, useForm } from '@qin-ui/antd-vue-pro';
-const form = useForm({ username: '', password: '' }, [
-  {
-    path: 'username',
-    component: 'input',
-    label: '用户名',
-    placeholder: '请输入',
-    rules: [{ required: true }],
-  },
-  {
-    path: 'password',
-    component: 'input-password',
-    label: '密码',
-    placeholder: '请输入',
-    rules: [{ required: true }],
-  },
-]);
+useTable({ columns, dataSource, pageParam, searchParam, searchFields });
 ```
-```html
-<ProForm :form="form" />
-```
+返回 `Table` 实例：
-### Level 2: Field linkage
+| 成员                                                                  | 说明                                                   |
+| :-------------------------------------------------------------------- | :----------------------------------------------------- |
+| `table.columns` / `table.dataSource`                                  | 列配置 / 数据源（Ref）                                 |
+| `table.pageParam`                                                     | 分页参数（reactive）：`current` / `pageSize` / `total` |
+| `table.searchForm`                                                    | 搜索表单实例（Form 类型，所有 useForm 方法可用）       |
+| `table.setColumn` / `deleteColumn` / `appendColumn` / `prependColumn` | 列增删改查（用法同 setField，支持 `{all:true}`）       |
+| `table.setPageParam(patch)`                                           | 设置分页参数                                           |
+| `table.resetQueryParams()`                                            | 重置分页到第一页 + 恢复搜索条件到初始值                |
-Control props (`disabled`, `hidden`, `rules`, etc.) support three reactivity patterns:
+## 关键约定
-```ts
-// A) computed() — declarative, for linkages known at init (preferred)
-disabled: computed(() => !form.formData.enabled),
-rules: computed(() => [{ required: form.formData.hasLimit, message: '必填' }]),
+### 自定义组件
-// B) ref() — external shared state
-const isDisabled = ref(false);
+`Field.component` 解析优先级（高 -> 低）：`teleport 插槽注入` > `ProComponentProvider.componentMap` > `内置 componentMap` > `原始 component 值`。
-// C) setField() — imperative, for event-driven changes
-form.setField('limitCount', { disabled: true });
-```
+四种接入方式（完整代码见 skills）：
+- **方式 1** `markRaw(SFC)`：单字段复用 SFC（**必须 markRaw**，否则被 Vue 深度代理触发性能警告）
+- **方式 2** render 函数 `(props, ctx) => VNode`：需动态拼装 props
+- **方式 3** `ProComponentProvider` 注入 `componentMap`：全局复用 / 覆盖内置组件，可追加 `declare module` 声明获强类型
+- **方式 4** 模板 scoped slot：插槽名 = 字段 `path`，`v-bind="scoped"` 转发（teleport 机制，优先级最高）
-**Rule: pick the simplest. computed() for init-time, setField() for runtime events, ref() for external state.**
+约定：默认 v-model 绑 `value`，他 prop 用 `modelProp` 指定；组件会收到 `path` prop；除框架级属性外其余作 attrs 透传。
-### Level 3: Custom component
+### valueFormatter -- 字段值转换
+控制表单值与组件值之间的转换。**在表单数据写入前（computed setter 中）执行**，支持两种形态：
 ```ts
-import { h } from 'vue';
-import CustomInput from './CustomInput.vue';
+// 函数形态：(新值, 旧值) => 转换后的值，写回 formData。仅 set（写入）方向生效，读取时不转换
+{ path: 'name', valueFormatter: (val, oldVal) => val?.trim() }
-// In field config:
-{ path: 'key', component: (p, ctx) => h(CustomInput, { ...p, ...ctx.attrs }) }
+// 对象形态：get 读出时转换，set 写入时转换（双向）
+{ path: 'birthday', component: 'date-picker',
+  valueFormatter: { get: v => v ? dayjs(v) : null, set: v => v ? dayjs(v).format('YYYY-MM-DD') : null } }
 ```
-Or via scoped slot in template (all binding params forwarded via `v-bind="scoped"`):
+### ProTable -- 配置驱动表格
-```html
-<ProForm :form="form">
-  <template #agreement="scoped">
-    <a-checkbox v-bind="scoped">同意协议</a-checkbox>
-  </template>
-</ProForm>
-```
+透传所有 ant-design-vue `TableProps`（`& TableProps`），可直接写 `row-key` / `bordered` / `scroll` / `row-selection` 等原生属性；`size`、`loading` 是 v-model。
----
-## 4. Anti-patterns
-- **Never hand-write `<a-form-item>` inside `<ProForm>`.** ProForm renders FormItems from Field config automatically.
-- **Never guess pass-through prop names.** Verify against [ant-design-vue docs](https://antdv.com).
-- **Don't confuse Grid props with input props.** `span` goes to `<a-col>`, not the input.
-- **Use `computed()` for reactive Field configs.** Plain values won't track dependencies.
-- **Prefer the simplest linkage pattern.** Don't use `setField()` when `computed()` suffices.
----
-## 5. ProComponentProvider — global defaults
-Wrap your app to set defaults for all ProForm/ProTable instances. Merged with priority (highest first):
-1. **Field-level config** (always wins)
-2. **`componentVars`** passed to ProComponentProvider
-3. **`INJECT_CONFIG`** built-in presets
-### Built-in presets (INJECT_CONFIG)
-| Component                                      | Preset                                                                                                                                  |
-| :--------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
-| `switch`                                       | `{ modelProp: 'checked' }`                                                                                                              |
-| `input`                                        | `{ maxlength: 100, allowClear: true, placeholder: '请输入' }`                                                                           |
-| `textarea`                                     | `{ maxlength: 200, autoSize: {minRows:3,maxRows:6}, showCount: true, allowClear: true, placeholder: '请输入' }`                         |
-| `select` / `cascader`                          | `{ allowClear: true, placeholder: '请选择', getPopupContainer }`                                                                        |
-| `input-number`                                 | `{ max: 10^15, min: -(10^15), controls: false, placeholder: '请输入', style: {width:'100%'} }`                                          |
-| `date-picker` / `range-picker` / `time-picker` | `{ 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 }`                                                                                                      |
-### Override example
-```vue
-<ProComponentProvider
-  :component-vars="{
-    'pro-form-item': { span: 6 },
-    input: { maxlength: 200 },
-    select: { showSearch: true },
-    'pro-table': { addIndexColumn: false },
-  }"
->
-  <ProForm :form="form" />
-  <ProTable :table="table" />
-</ProComponentProvider>
-```
+关键 prop：`table`（useTable 实例）、`search`（数据查询方法 `() => Promise`，ProTable 内部调用，非自动触发）、`addIndexColumn`、`immediateSearch`、`control`、`searchFormConfig`（含 `hidden`/`container`/`layout`/`expand`）、`tableContainer`。
----
+**数据流**：搜索->重置分页到第 1 页->调 `search()`；分页/排序变化->更新 `pageParam`->调 `search()`；重置->`resetQueryParams()`->调 `search()`。
-## 6. ProTable quick reference
+### Column -- 列配置
-```ts
-import { ProTable, useTable } from '@qin-ui/antd-vue-pro';
-const table = useTable<Row>({
-  columns: [
-    { title: 'ID', dataIndex: 'id', width: 80 },
-    { title: 'Name', dataIndex: 'name', width: 120 },
-  ],
-  // searchFields uses the same Field[] format as ProForm
-  searchFields: [
-    { path: 'name', component: 'input', placeholder: 'Search' },
-    { path: 'status', component: 'select', options: [...] },
-  ],
-});
-// table.searchForm is a ProForm instance — all form methods available
-```
+继承 ant-design-vue `ColumnType`，所有原生列属性可用。新增：`dataIndex`（列数据路径，主用，支持 `'name'` / `'address.city'` / `['address','city']`）、`key`（辅助标识，优先级更低）、`hidden`（隐藏该列，配合列控制）。
-```html
-<ProTable :table="table" :search="fetchData" addIndexColumn immediateSearch />
-```
+## 反模式
+- ❌ 在 `<ProForm>` 内手写 `<a-form-item>` -- ProForm 从 Field 配置自动渲染。
+- ❌ 猜透传属性名 -- 先查 antdv.com。
+- ❌ 把 `span` 当输入控件属性。
+- ❌ 传 SFC 给 `component` 不用 `markRaw`。
+- ❌ 在 ProTable 上忘了传 `:search`，或期望它自动请求 -- 查询由你提供并驱动。
----
+## 按需深查
-## 7. References
+完整 API（详细签名、参数表、完整示例、ProTable Slots、ProComponentProvider 用法）：
-1. **`node_modules/@qin-ui/antd-vue-pro/api.json`** — Structured API metadata (signatures, types, JSDoc examples)
-2. **`node_modules/@qin-ui/antd-vue-pro/README.md`** — Full usage docs and code examples
-3. **[antdv.com](https://antdv.com)** — ant-design-vue component API reference (always check before writing pass-through props)
+- `.agents/skills/antd-vue-pro/SKILL.md` — skills 入口（速查 + 参考导航）
+- `.agents/skills/antd-vue-pro/references/README.md` — 完整使用文档与进阶示例
+- `.agents/skills/antd-vue-pro/references/api.md` — 结构化 API 元数据
+- `node_modules/@qin-ui/antd-vue-pro/README.md` — 完整用法与进阶示例
+- ant-design-vue 组件属性查阅官方文档：https://antdv.com

package/README.md CHANGED Viewed

@@ -38,6 +38,24 @@ pnpm add @qin-ui/antd-vue-pro
 ---
+## 🤖 AI 辅助开发
+本项目内置 AI 上下文初始化工具。安装后在项目根目录执行：
+```bash
+npx @qin-ui/antd-vue-pro init-ai
+```
+将在项目中生成双载体 AI 上下文，使 Cursor / Claude Code / Codex 等 AI 工具深度理解本库的 Schema 驱动用法与属性透传规则：
+- `AGENTS.md` — 核心使用规则（跨工具开放约定，会话时自动注入，AI 默认加载）
+- `.agents/skills/antd-vue-pro/SKILL.md` — skills 入口（速查 + 参考导航）
+- `.agents/skills/antd-vue-pro/references/` — 完整使用文档与结构化 API 元数据
+> 生成的 `AGENTS.md` 使用标记区块写入，重复执行 `init-ai` 可安全更新，不影响项目内其他库的指令。建议将生成的文件提交到 Git 仓库，团队共享 AI 上下文。
+---
 ## 🚀 快速开始
 ### 1. 全局注册组件（可选）
@@ -119,6 +137,29 @@ const handleSubmit = async () => {
 ---
+## 🧱 属性分层透传（核心规则）
+ProForm/ProTable 是渲染引擎，所有真实 UI 来自 ant-design-vue。**Field 上的属性会被"剥离到不同 DOM 层"，不是全塞给输入控件**。写错层就会失效，这是最容易踩的坑：
+```
+<a-col :span="8">            ← Grid 层（仅 grid 开启时）
+  <a-form-item label="...">  ← FormItem 层
+    <a-input placeholder>     ← 输入控件层
+  </a-form-item>
+</a-col>
+```
+| 属性                                                                                                                                                                                                                   | 落到哪一层                       | 说明                 |
+| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- | :------------------- |
+| `span` / `offset` / `push` / `pull` / `flex` / `xs`..`xxl`                                                                                                                                                             | `<a-col>` Grid 层                | 仅 `grid` 开启时生效 |
+| `label` / `rules` / `tooltip` / `colon` / `labelCol` / `wrapperCol` / `extra` / `help` / `validateTrigger` / `validateFirst` / `valuePropName` / `normalize` / `formItemStyle` / `formItemClass` / `formItemDataAttrs` | `<a-form-item>` 层               | 表单项相关属性       |
+| `disabled` / `placeholder` / `allowClear` / `options` / `mode` / `maxlength` / `componentStyle` / `componentClass` / `componentDataAttrs` + 该控件其余 ant-design-vue 原生属性                                         | 输入控件本身（`a-input` 等）     | 其余全部             |
+| `component` / `hidden` / `modelProp` / `valueFormatter` / `fields` / `slots` / `formItemContainer` / `componentContainer` / `extraProps`                                                                               | ProForm 逻辑消费，**不绑到 DOM** | 框架级属性           |
+> **规则**：`span` 给 Grid，`label`/`rules` 给 FormItem，其余给输入控件。输入控件的具体属性名/类型请以 [ant-design-vue 官方文档](https://antdv.com) 为准。
+---
 ## 📚 组件 API 说明
 ### 1. ProComponentProvider
@@ -131,6 +172,24 @@ const handleSubmit = async () => {
 | :--------------- | :-------------------------------------- | :-------------- | :----- |
 | `component-vars` | 需要全局 provide 给子组件的默认属性配置 | `ComponentVars` | -      |
+#### 内置默认预设（INJECT_CONFIG）
+ProComponentProvider 内置了一套默认属性预设，**即使不配置 `component-vars` 也会生效**。Field 配置优先级最高，会覆盖这些预设。以下为各组件的内置默认值（写代码时需知晓，避免行为与预期不符）：
+| component                                      | 默认预设                                                                                                                                                                                                                                                      |
+| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `switch`                                       | `{ modelProp: 'checked' }` —— v-model 绑定 `checked` 而非 `value`                                                                                                                                                                                             |
+| `input` / `input-password`                     | `{ maxlength: 100, allowClear: true, placeholder: '请输入' }`                                                                                                                                                                                                 |
+| `textarea`                                     | `{ maxlength: 200, autoSize: { minRows: 3, maxRows: 6 }, showCount: true, allowClear: true, placeholder: '请输入' }`                                                                                                                                          |
+| `input-number`                                 | `{ max: 1e15-1, min: -(1e15+1), controls: false, placeholder: '请输入', style: { width: '100%' } }`                                                                                                                                                           |
+| `select` / `cascader`                          | `{ allowClear: true, placeholder: '请选择', getPopupContainer }`                                                                                                                                                                                              |
+| `date-picker` / `range-picker` / `time-picker` | `{ allowClear: true, getPopupContainer, style: { width: '100%' } }`                                                                                                                                                                                           |
+| `pro-form`                                     | `{ grid: { gutter: { xs: 8, sm: 16, md: 16, lg: 24 } } }`                                                                                                                                                                                                     |
+| `pro-form-item`                                | `{ validateFirst: true, span: 8 }`                                                                                                                                                                                                                            |
+| `pro-table`                                    | `{ pagination: { showTotal, showSizeChanger, pageSizeOptions: ['10', '20', '30', '40', '50', '100'], showQuickJumper: true }, searchFormConfig: { layout: 'grid', expand: { minExpandRows: 2, expandStatus: false } }, control: true, addIndexColumn: true }` |
+> `modelProp` 控制 v-model 绑定的属性名，默认 `'value'`（即 `v-model:value`）。`switch` 经预设绑定为 `checked`，通常无需手动设置。
 ---
 ### 2. ProForm
@@ -177,6 +236,32 @@ const handleSubmit = async () => {
 | `toolbar`     | 自定义工具栏区域（位于表格右上方控制按钮旁）       |
 | `table`       | 完全自定义渲染表格区域                             |
+#### 数据流
+ProTable 不会自动请求数据，**查询由你提供的 `search` 回调驱动**。内部串联逻辑：
+```
+点击搜索  -> 重置分页到第 1 页        -> 调用 search()
+分页/排序变化 -> 更新 pageParam        -> 调用 search()
+点击重置  -> resetQueryParams()       -> 调用 search()
+挂载(immediateSearch) -> 立即触发一次   -> 调用 search()
+```
+`search` 回调内通常组装查询参数并赋值数据源：
+```ts
+const fetchData = async () => {
+  const res = await api.list({
+    ...table.searchForm.formData, // 搜索条件
+    ...table.pageParam, // 分页
+  });
+  table.dataSource.value = res.data;
+  table.setPageParam({ total: res.total });
+};
+// 重置按钮（ProTable 内部已串联 resetQueryParams -> search，一般无需手动处理）
+```
 ---
 ## ⚙️ 核心 Hooks 说明
@@ -197,19 +282,19 @@ const form = useForm<D>(initFormData?, initFields?, root?)
 #### 返回值 (Form 实例)
-| 属性/方法                      | 说明                                                                                | 类型                             |
-| :----------------------------- | :---------------------------------------------------------------------------------- | :------------------------------- |
-| `formData`                     | 响应式表单数据对象（**2.0+ 中由 reactive 包装**）                                   | `Reactive<D>`                    |
-| `fields`                       | 响应式表单字段配置数组引用                                                          | `Ref<Field[]>`                   |
-| `formRef`                      | 底层 Ant Design Vue `a-form` 的 DOM/组件引用实例                                    | `Ref<FormInstance \| undefined>` |
-| `getFormData(path)`            | 安全获取指定字段路径（支持深层 'a.b'）的数据值                                      | `(path) => any`                  |
-| `setFormData(path, val)`       | 安全更新指定路径的值，支持批量对象或函数式更新                                      | `(path, val) => void`            |
-| `getField(path, opts?)`        | 获取指定 path 的字段配置，支持查找函数定位，支持配置 `{ all: true }` 获取所有匹配项 | `(path, opts) => Field`          |
-| `setField(path, patch, opts?)` | 增量更新指定字段的配置参数（如改变 label、hidden 等），支持 merge 或 rewrite 更新   | `(path, patch, opts) => void`    |
-| `deleteField(path)`            | 从当前配置数组中删除特定 path 的表单字段配置                                        | `(path) => void`                 |
-| `appendField(path, field)`     | 在特定的字段 path 后面，动态追加一个新的表单字段配置                                | `(path, field) => void`          |
-| `prependField(path, field)`    | 在特定的字段 path 前面，动态插入一个新的表单字段配置                                | `(path, field) => void`          |
-| `getParentField(path)`         | 查找获取当前子字段的父级配置项，一级字段返回虚拟根容器                              | `(path) => Field`                |
+| 属性/方法                      | 说明                                                                                                                           | 类型                             |
+| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |
+| `formData`                     | 响应式表单数据对象（**2.0+ 中由 reactive 包装**）                                                                              | `Reactive<D>`                    |
+| `fields`                       | 响应式表单字段配置数组引用                                                                                                     | `Ref<Field[]>`                   |
+| `formRef`                      | 底层 Ant Design Vue `a-form` 的 DOM/组件引用实例                                                                               | `Ref<FormInstance \| undefined>` |
+| `getFormData(path)`            | 安全获取指定字段路径（支持深层 'a.b'）的数据值                                                                                 | `(path) => any`                  |
+| `setFormData(path, value)`     | 路径写入或函数式更新；传对象（`{...}`）批量覆盖整个表单；传函数 `(prev) => new` 批量更新                                       | `(path, val) => void`            |
+| `getField(path, opts?)`        | 获取指定 path 的字段配置，支持查找函数定位，支持配置 `{ all: true }` 获取所有匹配项                                            | `(path, opts) => Field`          |
+| `setField(path, patch, opts?)` | 默认合并更新字段配置；`{updateType:'rewrite'}` 覆盖；支持函数式 `setField(path, prev=>({...}))`；`{all:true}` 批量更新所有匹配 | `(path, patch, opts) => void`    |
+| `deleteField(path, opts?)`     | 删除字段配置；`{all:true}` 删除所有匹配的字段                                                                                  | `(path, opts?) => void`          |
+| `appendField(path, field)`     | 在指定字段后追加新字段（入参可为数组）；`undefined` 在末尾追加；`{all:true}` 所有匹配后追加                                    | `(path, field, opts?) => void`   |
+| `prependField(path, field)`    | 在指定字段前插入新字段（入参可为数组）；`undefined` 在开头插入；`{all:true}` 所有匹配前插入                                    | `(path, field, opts?) => void`   |
+| `getParentField(path, opts?)`  | 查找父级字段配置；`{all:true}` 返回所有匹配的父级字段                                                                          | `(path, opts?) => Field`         |
 ---
@@ -244,6 +329,16 @@ const table = useTable<D, T>({
 | `setPageParam(param)`     | 增量设置当前分页参数值，支持传入对象或更新函数            | `(param) => void`      |
 | `resetQueryParams()`      | 重置搜索参数，并恢复分页至第 1 页                         | `() => void`           |
+#### 列配置（Column）
+`columns` 数组中每一项为 `Column<T>` 类型，**继承 ant-design-vue `ColumnType`**，因此所有原生列属性（`title` / `width` / `fixed` / `align` / `customRender` / `ellipsis` 等）均可用。在此基础上新增：
+| 属性        | 说明                                                                                      | 类型                 | 默认值  |
+| :---------- | :---------------------------------------------------------------------------------------- | :------------------- | :------ |
+| `dataIndex` | 列数据路径（主要字段），类型安全，支持 `'name'` / `'address.city'` / `['address','city']` | `string \| string[]` | -       |
+| `key`       | 列字段标识（辅助），仅当 `dataIndex` 无法满足时使用，匹配优先级低于 `dataIndex`           | `string`             | -       |
+| `hidden`    | 是否隐藏该列（配合列动态控制）                                                            | `boolean`            | `false` |
 ---
 ## 📄 字段配置（`Field`）详解
@@ -275,6 +370,63 @@ const table = useTable<D, T>({
 | `fields`             | 嵌套子表单项的 Schema 数组配置（用于分组或复杂嵌套表单）                      | `Field[]`                     | -         |
 | `grid`               | 针对当前嵌套子表单项所使用的网格布局参数（仅当有 `fields` 时有效）            | `boolean \| GridProps`        | -         |
+#### `valueFormatter` 字段值转换
+控制表单值与组件值之间的转换（如日期 `dayjs` 与字符串互转）。在表单数据写入前（computed setter 中）执行，支持两种形态。**函数形态仅 set（写入）方向生效，读取时不转换；对象形态 get/set 双向生效：**
+```ts
+// 函数形态：(新值, 旧值) => 转换后的值，写回 formData
+{ path: 'name', component: 'input', valueFormatter: (val, oldVal) => val?.trim() }
+// 对象形态：get 读出时转换，set 写入时转换
+{
+  path: 'birthday',
+  component: 'date-picker',
+  valueFormatter: {
+    get: (val) => (val ? dayjs(val) : null),                          // formData -> 组件显示
+    set: (val) => (val ? dayjs(val).format('YYYY-MM-DD') : null),     // 组件 -> formData
+  },
+}
+```
+> ⚠️ `valueFormatter` 不支持响应式（不能包 `ref`/`computed`），与 `component` / `fields` / `slots` / `modelProp` 等同属不支持响应式的属性。
+---
+### 🔄 响应式联动
+控制类属性（`disabled` / `hidden` / `rules` 等）支持三种响应式模式，按场景选最简的：
+```ts
+// A. computed() 声明式 -- 初始化时已知的联动（首选）
+disabled: computed(() => !form.formData.enabled),
+rules: computed(() => form.formData.hasLimit ? [{ required: true, message: '必填' }] : []),
+// B. ref() -- 外部共享状态
+const isDisabled = ref(false);
+disabled: isDisabled,
+// C. setField() 命令式 -- 事件驱动的运行时变更
+form.setField('limitCount', { disabled: true });
+```
+> **规则**：初始化时已知的联动用 `computed()`，运行时事件触发的用 `setField()`，外部共享状态用 `ref()`。能用 `computed()` 解决就不要用 `setField()`。
+#### 不支持响应式的属性
+以下属性不能包 `ref`/`computed`（会失效或引发渲染异常），只能传静态值：
+| 属性                                       | 原因                                                |
+| :----------------------------------------- | :-------------------------------------------------- |
+| `component`                                | 组件对象/函数，响应式代理会破坏渲染（需 `markRaw`） |
+| `valueFormatter`                           | 纯转换函数，无需响应式                              |
+| `fields`                                   | 嵌套字段数组结构，响应式代理会干扰内部解析          |
+| `slots`                                    | 插槽内容，响应式代理会破坏渲染                      |
+| `modelProp`                                | 字符串标识，无需响应式                              |
+| `formItemContainer` / `componentContainer` | 容器组件，需 `markRaw`                              |
+> 动态切换 `component` 或 `slots` 时，用 `setField()` 命令式更新，而非包 `computed`。
 ---
 ### 内置组件映射（`component` 可选值）
@@ -303,9 +455,45 @@ const table = useTable<D, T>({
 ---
-### 🧩 扩充注册您的自定义组件
+### 🧩 自定义组件（4 种方式）
-#### 步骤 1：利用 ComponentProvider 全局注册
+`Field.component` 的解析优先级（高 -> 低）：
+`teleport 插槽注入` > `ProComponentProvider.componentMap` > `内置 componentMap` > `原始 component 值`
+#### 方式 1：传入 SFC 单文件组件对象（推荐，单字段最常用）
+`component` 直接传组件对象，**必须用 `markRaw` 包裹**：
+```ts
+import { markRaw } from 'vue';
+import MyInput from './MyInput.vue';
+const fields = [{ path: 'code', label: '验证码', component: markRaw(MyInput) }];
+```
+> ⚠️ **必须 `markRaw`**：不包会被 Vue 当成响应式对象深度代理，触发性能警告甚至渲染异常。类型上 `component` 接受 `RenderComponentType | Raw<RenderComponentType>`，`Raw<T>` 即 markRaw 的类型标记。此字段不支持响应式（不能包 `ref`/`computed`）。
+#### 方式 2：传入 render 函数（单字段，需动态拼装 props 时）
+`component` 传 `(props, ctx) => VNode`。`props` 含 v-model 绑定值与 path，`ctx.attrs` 含透传属性：
+```ts
+import { h } from 'vue';
+import MyInput from './MyInput.vue';
+const fields = [
+  {
+    path: 'code',
+    label: '验证码',
+    component: (p, ctx) => h(MyInput, { ...p, ...ctx.attrs }),
+  },
+];
+```
+#### 方式 3：ProComponentProvider 注入 componentMap（全局复用，推荐多字段场景）
+在根用 `componentMap` 注册，Field 里用字符串引用。**可覆盖内置组件**（如 `input: MyInput` 替换全局 `input`）。
 ```vue
 <script setup lang="ts">
@@ -324,9 +512,7 @@ const componentMap = {
 </template>
 ```
-#### 步骤 2：追加 TypeScript 全局声明获取强类型补全
-在项目任意 `.d.ts` 类型文件中写入以下代码：
+追加 TypeScript 全局声明获取强类型补全（项目任意 `.d.ts`）：
 ```ts
 declare module '@qin-ui/antd-vue-pro' {
@@ -336,7 +522,34 @@ declare module '@qin-ui/antd-vue-pro' {
 }
 ```
-现在，您在表单配置中写入 `component: 'rich-editor'` 时，将自动获得精准的属性类型联想与校验！
+之后 `component: 'rich-editor'` 即获精准属性类型联想与校验。
+#### 方式 4：模板 scoped slot（声明式，简单替换）
+插槽名 = 字段 `path`，绑定参数通过 `v-bind="scoped"` 转发（teleport 机制，优先级最高）：
+```vue
+<ProForm :form="form">
+  <template #agreement="scoped">
+    <a-checkbox v-bind="scoped">同意协议</a-checkbox>
+  </template>
+</ProForm>
+```
+#### 选择建议
+| 场景                         | 推荐方式                          |
+| :--------------------------- | :-------------------------------- |
+| 单字段复用一个 SFC           | 方式 1（`markRaw(SFC)`）          |
+| 单字段、需动态拼装 props     | 方式 2（render 函数）             |
+| 多处复用 / 替换内置组件      | 方式 3（componentMap + 声明扩充） |
+| 简单声明式替换、不想写 `h()` | 方式 4（scoped slot）             |
+#### 自定义组件需遵守的约定
+- **v-model**：默认绑 `value`（`v-model:value`）。若组件用别的 prop（如 Switch 用 `checked`），通过字段 `modelProp` 指定，或在 `componentVars` 预设 `modelProp`。
+- **接收 path**：组件会收到 `path` prop（字段路径），可用于透传或标识。
+- **属性透传**：Field 上除框架级属性外（`component` / `hidden` / `modelProp` / `valueFormatter` / `fields` / `slots` / `formItemContainer` / `componentContainer` / `extraProps` 等），其余作为 attrs 透传给自定义组件。
 ---

package/api.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-13T08:00:52.657Z",
+  "generatedAt": "2026-08-05T02:02:12.968Z",
   "name": "@qin-ui/antd-vue-pro",
   "api": [
     {
@@ -8,6 +8,20 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "<ProComponentProvider>",
       "description": "@qin-ui/antd-vue-pro 全局配置提供者组件\n用于在组件树的顶层配置所有子组件的全局默认属性。\n支持配置 ProForm、ProTable、ProFormItem 以及所有内置组件的默认属性。",
+      "params": [
+        {
+          "name": "componentVars",
+          "type": "ComponentVars",
+          "optional": true,
+          "description": "组件全局配置变量"
+        },
+        {
+          "name": "componentMap",
+          "type": "Record<ComponentName, any>",
+          "optional": true,
+          "description": "自定义组件映射，用于替换或扩展内置组件"
+        }
+      ],
       "examples": [
         "```vue\n<template>\n<ProComponentProvider\n:componentVars=\"{\n'pro-form': { labelCol: { span: 4 } },\n'input': { placeholder: '请输入', maxlength: 200 },\n'select': { placeholder: '请选择' },\n}\"\n>\n<ProForm :form=\"form\" />\n</ProComponentProvider>\n</template>\n```"
       ]
@@ -32,6 +46,26 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "<ProForm>",
       "description": "@qin-ui/antd-vue-pro 配置驱动表单组件\n架构设计说明 (Architecture Overview)\n[ 数据层 (Core) ]  =>  [ 绑定层 (ProForm) ]  =>  [ 渲染层 (BaseFormItem / BaseField) ]\n1. 数据隔离：ProForm 本身不负责存储和管理表单状态，所有核心状态（formData, fields, 校验规则）\n均交由底层的 `useForm`（@qin-ui/pro-components-core）驱动。\n2. 上下文透传：通过 `provide` 将核心状态下发给子组件，避免了深层嵌套的 Props 传递。\n3. 递归渲染：网格布局和具体字段的解析交由 `<BaseFormItem>` 递归完成，实现了 UI 布局与表单逻辑的解耦。\n通过配置驱动的方式快速构建表单，支持：\n- 字段联动（通过 setField、watch 等实现）\n- 嵌套字段（通过 fields 递归配置）\n- 自定义组件（通过 component 属性和 custom 类型）\n- 网格布局（通过 grid 属性）\n- 动态插槽（以字段 path 命名的插槽）\n- 全局配置注入（通过 ProComponentProvider）",
+      "params": [
+        {
+          "name": "form",
+          "type": "F",
+          "optional": true,
+          "description": "useForm 返回的表单实例"
+        },
+        {
+          "name": "grid",
+          "type": "boolean | GridProps",
+          "optional": true,
+          "description": "是否启用网格布局 (默认 false)"
+        },
+        {
+          "name": "...attrs",
+          "type": "...FormProps",
+          "optional": false,
+          "description": "Ant Design Vue Form 组件的其他属性"
+        }
+      ],
       "typeParams": [
         {
           "name": "F"
@@ -74,6 +108,14 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "export const useFormData = <D extends Data = Data>(\n  initFormData?: ExtendWithAny<DeepPartial<D>>\n): UseFormDataReturn<D> =>",
       "description": "表单数据处理 Hook\n提供响应式表单数据的管理能力，支持：\n- 响应式数据存储（基于 Vue reactive）\n- 深层路径读写（支持点号分隔，如 'address.city'）\n- 类型安全的路径提示（传入泛型 D 后，path 参数可获得类型推导）\n- 父子表单自动注入（非根表单会从注入中获取数据）",
+      "params": [
+        {
+          "name": "initFormData",
+          "type": "ExtendWithAny<DeepPartial<D>>",
+          "optional": true,
+          "description": "初始表单数据"
+        }
+      ],
       "returns": "{UseFormDataReturn<D>} 表单数据操作对象",
       "typeParams": [
         {
@@ -90,6 +132,14 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "export function useFields<D extends Data = Data>(\n  initFields?: Fields<D>\n): UseFieldsReturn<D, Field<ComponentName, D>, FormItemInstance>;",
       "description": "字段配置管理 Hook\n基于 `@qin-ui/pro-components-core` 的 `useFields`，将泛型参数绑定为 Ant Design Vue 的本地类型：\n- 字段类型 F -> `Field<ComponentName, D>`（支持 Ant Design Vue 组件类型推导）\n- FormItem 实例 -> Ant Design Vue 的 `FormItemInstance`\n提供对字段配置数组的增删改查操作，支持：\n- 通过路径字符串或查找函数定位字段\n- 深层嵌套字段的遍历和匹配\n- 字段配置的合并/覆盖更新\n- 字段的添加、插入、删除\n- 父级字段查找\n- `fields` - 字段配置数组（响应式 Ref\\<F[]\\>）\n- `getField(path)` - 获取字段配置，支持路径字符串或查找函数\n- `setField(path, field, options?)` - 更新字段配置，默认合并模式\n- `deleteField(path, options?)` - 删除字段配置\n- `appendField(path, field, options?)` - 在指定字段后追加\n- `prependField(path, field, options?)` - 在指定字段前插入\n- `getParentField(path, options?)` - 获取父级字段配置",
+      "params": [
+        {
+          "name": "initFields",
+          "type": "Fields<D>",
+          "optional": true,
+          "description": "初始字段配置数组"
+        }
+      ],
       "returns": "字段操作对象，包含以下属性：",
       "typeParams": [
         {
@@ -131,6 +181,26 @@
       "package": "@qin-ui/antd-vue-pro",
       "signature": "export function useForm<D extends Data = Data>(\n  initFormData?: ExtendWithAny<DeepPartial<D>>,\n  initFields?: Field<ComponentName, D>[],\n  root?: boolean\n): Form<D, Field<ComponentName, D>>;",
       "description": "创建表单实例的 Hook\n基于 `@qin-ui/pro-components-core` 的 `useForm`，将泛型参数绑定为 Ant Design Vue 的本地类型：\n- 字段类型 F -> `Field<ComponentName, D>`（支持 Ant Design Vue 所有内置组件类型推导）\n- 表单实例 -> Ant Design Vue 的 `FormInstance`（使 formRef 获得完整的类型提示）\n表单实例组合了三个子模块的能力：\n- **useFormData**：表单数据管理（响应式数据、读写、批量更新）\n- **useFields**：字段配置管理（增删改查字段配置，支持嵌套）\n- **useFormRef**：底层 Form 组件实例引用",
+      "params": [
+        {
+          "name": "initFormData",
+          "type": "ExtendWithAny<DeepPartial<D>>",
+          "optional": true,
+          "description": "初始表单数据"
+        },
+        {
+          "name": "initFields",
+          "type": "Field<ComponentName, D>[]",
+          "optional": true,
+          "description": "初始字段配置数组"
+        },
+        {
+          "name": "root",
+          "type": "boolean",
+          "optional": true,
+          "description": "是否为根表单。设为 `false` 时尝试从父组件注入获取表单实例 (默认 true)"
+        }
+      ],
       "returns": "{Form<D>} 表单实例，包含数据操作、字段操作和 ref 操作",
       "typeParams": [
         {
@@ -206,6 +276,36 @@
           "type": "object",
           "optional": false,
           "description": "表格配置参数"
+        },
+        {
+          "name": "params.columns",
+          "type": "Columns<T>",
+          "optional": true,
+          "description": "初始列配置数组"
+        },
+        {
+          "name": "params.dataSource",
+          "type": "T[]",
+          "optional": true,
+          "description": "初始数据源"
+        },
+        {
+          "name": "params.pageParam",
+          "type": "PageParam",
+          "optional": true,
+          "description": "初始分页参数，默认 `{ current: 1, pageSize: 10, total: 0 }`"
+        },
+        {
+          "name": "params.searchParam",
+          "type": "ExtendWithAny<DeepPartial<D>>",
+          "optional": true,
+          "description": "初始搜索参数"
+        },
+        {
+          "name": "params.searchFields",
+          "type": "Fields<D>",
+          "optional": true,
+          "description": "搜索表单字段配置"
         }
       ],
       "returns": "{Table<D, T>} 表格实例",

package/bin/init-ai.mjs CHANGED Viewed

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
+/* global process -- Node.js CLI 脚本 */
 /**
  * @qin-ui/antd-vue-pro AI 上下文初始化 CLI 工具
  *
- * 在消费方项目中生成分层 AI 上下文文件，使 AI 工具能够：
- * 1. 理解 @qin-ui/antd-vue-pro 的 Schema 驱动架构
- * 2. 掌握属性透传规则（何时查阅 ant-design-vue 文档）
- * 3. 快速获取完整 API 参考
+ * 在消费方项目中生成双载体 AI 上下文：
+ * 1. 根目录 AGENTS.md -- 核心使用规则，跨工具自动注入（主载体）
+ * 2. .agents/skills/{pkg}/SKILL.md + references/ -- 分层参考文档，支持 skills 发现的工具按需逐层调取（参考载体）
  *
  * 用法:
  *   npx @qin-ui/antd-vue-pro init-ai
@@ -28,6 +28,10 @@ const PKG_JSON = JSON.parse(
 const PKG_NAME = PKG_JSON.name;
 const PKG_SHORT = PKG_NAME.replace(/^@qin-ui\//, '');
+// AGENTS.md 智能合并区块标记（支持多库共存，幂等更新）
+const BEGIN_MARKER = `<!-- BEGIN ${PKG_NAME} -->`;
+const END_MARKER = `<!-- END ${PKG_NAME} -->`;
 // ==================== 终端颜色 ====================
 const green = s => `\x1b[32m${s}\x1b[0m`;
@@ -47,7 +51,10 @@ function readPackageFile(filename) {
 }
 function getAiContextContent() {
-  return readPackageFile('AI-CONTEXT.md') || `# ${PKG_NAME}\n\n> 基于 Vue 3 的配置驱动组件库。`;
+  return (
+    readPackageFile('AI-CONTEXT.md') ||
+    `# ${PKG_NAME}\n\n> 基于 Vue 3 的配置驱动组件库。`
+  );
 }
 function getReadmeContent() {
@@ -64,76 +71,157 @@ function getApiJsonContent() {
   }
 }
-// ==================== 内容生成 ====================
+// ==================== 工具函数 ====================
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+function writeFileWithLog(filePath, content, label) {
+  const dir = path.dirname(filePath);
+  ensureDir(dir);
+  const existed = fs.existsSync(filePath);
+  fs.writeFileSync(filePath, content, 'utf-8');
+  const status = existed ? yellow('[更新]') : green('[创建]');
+  console.log(`  ${status} ${cyan(label)}`);
+}
+// ==================== AGENTS.md（主载体，自动注入）====================
 /**
- * 生成 rules 文件内容（Instructions 层）
- * 包含：架构关系、透传规则、反模式、ant-design-vue 资源链接
+ * 生成 AGENTS.md 区块内容
+ * = AI-CONTEXT.md 全文（核心使用规则，AI 必然读到）
  */
-function getRulesContent() {
+function getAgentsBlock() {
+  return getAiContextContent();
+}
+/**
+ * 智能合并 AGENTS.md：
+ * - 文件不存在 -> 创建，内容 = 标记区块
+ * - 已有本库区块 -> 幂等替换区块内容（支持升级后更新）
+ * - 已有其他内容但无本库区块 -> 末尾追加区块（多库共存不冲突）
+ */
+function writeAgentsMd(cwd) {
+  const agentsPath = path.join(cwd, 'AGENTS.md');
+  const blockContent = getAgentsBlock();
+  const newBlock = `${BEGIN_MARKER}\n${blockContent}\n${END_MARKER}`;
+  let existing = '';
+  if (fs.existsSync(agentsPath)) {
+    existing = fs.readFileSync(agentsPath, 'utf-8');
+  }
+  let result;
+  const hasBlock =
+    existing.includes(BEGIN_MARKER) && existing.includes(END_MARKER);
+  if (hasBlock) {
+    // 幂等替换已有区块
+    const blockRegex = new RegExp(
+      `${escapeRegExp(BEGIN_MARKER)}[\\s\\S]*?${escapeRegExp(END_MARKER)}`,
+      'g'
+    );
+    result = existing.replace(blockRegex, newBlock);
+  } else if (existing.trim()) {
+    // 已有其他内容，追加区块
+    result = `${existing.trimEnd()}\n\n${newBlock}\n`;
+  } else {
+    // 文件不存在或空
+    result = `${newBlock}\n`;
+  }
+  const existed = fs.existsSync(agentsPath);
+  fs.writeFileSync(agentsPath, result, 'utf-8');
+  const status = existed ? yellow('[更新]') : green('[创建]');
+  console.log(`  ${status} ${cyan('AGENTS.md')}`);
+}
+// ==================== Skills（参考载体，按需调取）====================
+/**
+ * 生成 SKILL.md 内容
+ * = skill frontmatter + AI-CONTEXT.md 速查内容 + references 导航
+ * 供支持 skills 发现的工具按需调取，精准定位后查阅 references
+ */
+function getSkillMainContent() {
   const aiContext = getAiContextContent();
+  const sections = [];
+  // skill frontmatter
+  sections.push('---');
+  sections.push(`name: ${PKG_SHORT}`);
+  sections.push(
+    `description: ${PKG_NAME} 使用指南 - 组件、Hooks、类型、Field/Column 配置。Schema 驱动的配置式组件库。当需要组件映射、默认预设、属性透传规则或完整用法时按需调取。`
+  );
+  sections.push('---');
+  sections.push('');
+  // AI-CONTEXT.md 速查内容（与 AGENTS.md 主载体同源，确保一致）
+  sections.push(aiContext);
+  sections.push('');
+  // references 导航
+  sections.push('---');
+  sections.push('');
+  sections.push('## 参考文档');
+  sections.push('');
+  sections.push(
+    `以下文件位于 \`.agents/skills/${PKG_SHORT}/references/\`，可在需要精确细节时进一步查阅：`
+  );
+  sections.push('');
+  sections.push(
+    `- [references/README.md](references/README.md) — 完整使用文档与进阶示例`
+  );
+  sections.push(
+    `- [references/api.md](references/api.md) — 结构化 API 元数据（函数签名、参数类型、返回值，提取自源码 JSDoc）`
+  );
+  sections.push(`- 底层组件属性查阅 ant-design-vue 官方文档：https://antdv.com`);
+  sections.push('');
-  return [
-    '---',
-    `description: "${PKG_NAME} 组件库使用规范 — Schema 驱动、属性透传规则"`,
-    'globs: ["**/*.vue", "**/*.ts", "**/*.tsx"]',
-    'alwaysApply: false',
-    '---',
-    '',
-    aiContext,
-    '',
-    '---',
-    '',
-    '## 本地参考文件',
-    '',
-    '本规则文件提供了核心架构和用法指南。需要完整 API 参考或底层组件文档时，请阅读以下资源：',
-    '',
-    `- **\`.agents/docs/${PKG_SHORT}-api.md\`** — 完整 API 文档（组件、Hooks、类型、Field 配置参考）`,
-    `- **\`node_modules/${PKG_NAME}/api.json\`** — 结构化 API 元数据（函数签名、类型定义）`,
-    '',
-    '## 底层组件文档',
-    '',
-    `${PKG_NAME} 基于 **ant-design-vue**（v4，\`a-\` 前缀）封装。编写 Field 中的输入控件属性前，请查阅 ant-design-vue 官方文档确认属性名和类型：`,
-    '',
-    '- **[ant-design-vue 官方文档](https://antdv.com)** — 组件 API 参考（中文）',
-    '',
-  ].join('\n');
+  return sections.join('\n');
 }
 /**
- * 生成 API 文档内容（Resources 层）
- * 从 README.md + api.json 合并提取完整 API 参考
+ * 生成 references/api.md 内容（结构化 API 元数据 + skill frontmatter）
+ * 从 api.json 提取 @public 标记的 JSDoc，含签名、参数、返回值、示例
  */
-function getApiDocContent() {
-  const readme = getReadmeContent();
+function getSkillApiContent() {
   const apiJson = getApiJsonContent();
   const sections = [];
-  sections.push(`# ${PKG_NAME} — 完整 API 参考`, '');
-  sections.push(`> 自动生成自 README.md 和 api.json。版本: ${PKG_JSON.version}`, '');
+  // skill frontmatter
+  sections.push('---');
+  sections.push(`name: ${PKG_SHORT}-api`);
+  sections.push(
+    `description: ${PKG_NAME} 结构化 API 元数据 - 函数签名、参数类型、返回值、示例。从源码 JSDoc（@public 标记）自动提取。`
+  );
+  sections.push('---');
+  sections.push('');
-  // README 内容（已包含完整的使用文档）
-  if (readme) {
-    sections.push(readme);
-    sections.push('');
-  }
+  sections.push(`# ${PKG_NAME} - 结构化 API 元数据`, '');
+  sections.push(
+    `> 自动提取自源码 JSDoc（\`@public\` 标记）。版本: ${PKG_JSON.version}`,
+    ''
+  );
   // 结构化 API 元数据
   if (apiJson && apiJson.api && apiJson.api.length > 0) {
-    sections.push('---');
-    sections.push('');
-    sections.push('## 结构化 API 元数据（自动提取自源码 JSDoc）');
-    sections.push('');
     for (const item of apiJson.api) {
-      const typeLabel = {
-        component: '组件',
-        function: '函数/Hook',
-        type: '类型',
-        interface: '接口',
-        constant: '常量',
-      }[item.type] || '';
+      const typeLabel =
+        {
+          component: '组件',
+          function: '函数/Hook',
+          type: '类型',
+          interface: '接口',
+          constant: '常量',
+        }[item.type] || '';
       sections.push(`### ${typeLabel} \`${item.name}\``);
       sections.push('');
@@ -168,7 +256,9 @@ function getApiDocContent() {
         sections.push('| 参数名 | 类型 | 可选 | 描述 |');
         sections.push('| :--- | :--- | :--- | :--- |');
         for (const p of item.params) {
-          sections.push(`| \`${p.name}\` | \`${p.type}\` | ${p.optional ? '是' : '否'} | ${p.description} |`);
+          sections.push(
+            `| \`${p.name}\` | \`${p.type}\` | ${p.optional ? '是' : '否'} | ${p.description} |`
+          );
         }
       }
@@ -195,41 +285,30 @@ function getApiDocContent() {
   return sections.join('\n');
 }
-// ==================== 文件写入 ====================
-function ensureDir(dirPath) {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
-  }
-}
-function writeFileWithLog(filePath, content, label) {
-  const dir = path.dirname(filePath);
-  ensureDir(dir);
-  const existed = fs.existsSync(filePath);
-  fs.writeFileSync(filePath, content, 'utf-8');
-  const status = existed ? yellow('[更新]') : green('[创建]');
-  console.log(`  ${status} ${cyan(label)}`);
-}
 // ==================== CLI 入口 ====================
 function printHelp() {
   console.log(`
-${bold(`${PKG_NAME} CLI — AI 上下文初始化`)}
+${bold(`${PKG_NAME} CLI - AI 上下文初始化`)}
 ${bold('用法:')}
   npx ${PKG_NAME} init-ai
 ${bold('说明:')}
-  在项目中生成分层 AI 上下文文件，使 AI 工具能够深度理解和规范使用 ${PKG_NAME}。
+  在项目中生成双载体 AI 上下文，使 AI 工具能够深度理解和规范使用 ${PKG_NAME}。
   生成的文件结构：
+    AGENTS.md                          核心使用规则（跨工具自动注入）
     .agents/
-      rules/
-        ${PKG_SHORT}.md         规则文件（架构、透传规则、反模式）
-      docs/
-        ${PKG_SHORT}-api.md     API 参考（完整文档 + 结构化元数据）
+      skills/
+        ${PKG_SHORT}/
+          SKILL.md                     skills 入口（速查 + 导航）
+          references/
+            README.md                  完整使用文档
+            api.md                     结构化 API 元数据
+  ${dim('AGENTS.md 是跨工具开放约定，Codex / Claude Code / Cursor 等会话时自动注入。')}
+  ${dim('.agents/skills/ 供支持 skills 发现的工具按需逐层调取。')}
 ${bold('选项:')}
   --help     显示帮助信息
@@ -253,49 +332,83 @@ function main() {
   }
   console.log('');
-  console.log(bold(`📦 ${PKG_NAME} — AI 上下文初始化 v${PKG_JSON.version}`));
+  console.log(bold(`📦 ${PKG_NAME} - AI 上下文初始化 v${PKG_JSON.version}`));
   console.log(dim(`   基于 ant-design-vue 的 Schema 驱动组件库`));
   console.log('');
-  // 1. 生成 Rules 文件
-  console.log(bold('📋 规则层 (Rules)'));
-  const rulesContent = getRulesContent();
-  writeFileWithLog(
-    path.join(process.cwd(), '.agents/rules', `${PKG_SHORT}.md`),
-    rulesContent,
-    `.agents/rules/${PKG_SHORT}.md`
+  // 1. 生成 AGENTS.md（主载体）
+  console.log(bold('📋 主载体：AGENTS.md（自动注入）'));
+  writeAgentsMd(process.cwd());
+  console.log(
+    dim('   -> 核心使用规则，Codex/Claude Code/Cursor 等会话自动加载')
   );
-  console.log(dim('   → 架构概览、属性透传决策树、渐进用法、反模式'));
   console.log('');
-  // 2. 生成 API 文档
-  console.log(bold('📖 参考层 (Docs)'));
-  const apiDocContent = getApiDocContent();
+  // 2. 生成 Skills（标准结构：SKILL.md + references/）
+  console.log(bold('📖 参考载体：.agents/skills/（按需调取）'));
+  const skillDir = path.join(process.cwd(), '.agents/skills', PKG_SHORT);
+  const skillRefsDir = path.join(skillDir, 'references');
+  // SKILL.md（入口：frontmatter + 速查内容 + 参考导航）
   writeFileWithLog(
-    path.join(process.cwd(), '.agents/docs', `${PKG_SHORT}-api.md`),
-    apiDocContent,
-    `.agents/docs/${PKG_SHORT}-api.md`
+    path.join(skillDir, 'SKILL.md'),
+    getSkillMainContent(),
+    `.agents/skills/${PKG_SHORT}/SKILL.md`
+  );
+  // references/README.md（完整使用文档）
+  const readme = getReadmeContent();
+  if (readme) {
+    writeFileWithLog(
+      path.join(skillRefsDir, 'README.md'),
+      readme,
+      `.agents/skills/${PKG_SHORT}/references/README.md`
+    );
+  }
+  // references/api.md（结构化 API 元数据）
+  const apiJson = getApiJsonContent();
+  if (apiJson && apiJson.api && apiJson.api.length > 0) {
+    writeFileWithLog(
+      path.join(skillRefsDir, 'api.md'),
+      getSkillApiContent(),
+      `.agents/skills/${PKG_SHORT}/references/api.md`
+    );
+  }
+  console.log(
+    dim('   -> SKILL.md 入口 + references/ 完整文档，skills 工具按需逐层调取')
   );
-  console.log(dim('   → 完整 README 文档 + 结构化 API 元数据'));
   console.log('');
   // 3. 完成提示
-  console.log(green('✅ 完成！已生成分层 AI 上下文文件。'));
+  console.log(green('✅ 完成！已生成双载体 AI 上下文文件。'));
   console.log('');
   console.log(`${bold('📂 生成的文件:')}`);
-  console.log(`   ${cyan('.agents/')}`);
-  console.log(`   ├── ${cyan('rules/')}`);
-  console.log(`   │   └── ${cyan(PKG_SHORT + '.md')}            ${dim('← 核心规则（AI 优先读取）')}`);
-  console.log(`   └── ${cyan('docs/')}`);
-  console.log(`       └── ${cyan(PKG_SHORT + '-api.md')}        ${dim('← 完整 API 参考')}`);
+  console.log(
+    `   ${cyan('AGENTS.md')}                          ${dim('← 核心规则（AI 自动读取）')}`
+  );
+  console.log(`   ${cyan('.agents/skills/' + PKG_SHORT + '/')}`);
+  console.log(
+    `       ├── ${cyan('SKILL.md')}                    ${dim('← skills 入口（速查 + 导航）')}`
+  );
+  console.log(`       └── ${cyan('references/')}`);
+  console.log(
+    `             ├── ${cyan('README.md')}              ${dim('← 完整使用文档')}`
+  );
+  if (apiJson && apiJson.api && apiJson.api.length > 0) {
+    console.log(
+      `             └── ${cyan('api.md')}                ${dim('← 结构化 API 元数据')}`
+    );
+  }
   console.log('');
-  console.log(`${bold('🔄 建议的下一步:')}`);
-  console.log(`   1. 提交 ${cyan('.agents/')} 目录到 Git 仓库，团队共享`);
-  console.log(`   2. 编写 Field 配置中的输入控件属性前，查阅 ant-design-vue 官方文档：`);
-  console.log(`      ${cyan('https://antdv.com')}`);
-  console.log(`   3. ${dim('（可选）查看完整 API 参考：')}`);
-  console.log(`      ${dim(`cat .agents/docs/${PKG_SHORT}-api.md`)}`);
+  console.log(`${bold('🔄 说明:')}`);
+  console.log(
+    `   - AGENTS.md 已用标记区块写入，重复执行 init-ai 可安全更新（不破坏其他库的指令）`
+  );
+  console.log(
+    `   - 编写 Field 中输入控件属性前，查阅 ant-design-vue 官方文档：${cyan('https://antdv.com')}`
+  );
   console.log('');
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@qin-ui/antd-vue-pro",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "二次封装antd vue组件",
   "bin": {
     "antd-vue-pro": "./bin/init-ai.mjs"
@@ -42,11 +42,11 @@
   },
   "dependencies": {
     "scroll-into-view-if-needed": "^3.1.0",
-    "@qin-ui/pro-components-core": "^1.0.2"
+    "vue-component-type-helpers": "^3.2.5",
+    "@qin-ui/pro-components-core": "^1.0.4"
   },
   "devDependencies": {
-    "ant-design-vue": "^4",
-    "vue-component-type-helpers": "^3.2.5"
+    "ant-design-vue": "^4"
   },
   "sideEffects": [
     "**/*.css",
@@ -72,7 +72,7 @@
     "pro-table"
   ],
   "scripts": {
-    "prebuild": "tsx ../../scripts/generate-api-json.ts antd-vue-pro",
+    "prebuild": "tsx ../../scripts/generate-api-json.ts antd-vue-pro && tsx ../../scripts/generate-init-ai.ts antd-vue-pro",
     "build": "vue-tsc --noEmit && vite build"
   }
 }