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

package/api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-25T06:47:30.124Z",
+  "generatedAt": "2026-07-09T04:30:33.730Z",
   "name": "@qin-ui/antdv-next-pro",
   "api": [
     {
@@ -12,25 +12,25 @@
         "```vue\n<ProComponentProvider\n:componentVars=\"{ 'input': { placeholder: '请输入' } }\"\n>\n<ProForm :form=\"form\" :fields=\"fields\" />\n</ProComponentProvider>\n```"
       ]
     },
+    {
+      "name": "ContainerFragment",
+      "type": "component",
+      "package": "@qin-ui/antdv-next-pro",
+      "signature": "<ContainerFragment>",
+      "description": "容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。"
+    },
     {
       "name": "ProForm",
       "type": "component",
       "package": "@qin-ui/antdv-next-pro",
       "signature": "<ProForm>",
-      "description": "@qin-ui/antdv-next-pro 配置驱动表单组件\n通过配置驱动的方式快速构建表单，支持：\n- 字段联动（通过 setField、watch 等实现）\n- 嵌套字段（通过 fields 递归配置）\n- 自定义组件（通过 component 属性和 custom 类型）\n- 网格布局（通过 grid 属性）\n- 动态插槽（以字段 path 命名的插槽）",
+      "description": "@qin-ui/antdv-next-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 命名的插槽）",
       "typeParams": [
         {
           "name": "F"
         }
       ]
     },
-    {
-      "name": "ContainerFragment",
-      "type": "component",
-      "package": "@qin-ui/antdv-next-pro",
-      "signature": "<ContainerFragment>",
-      "description": "容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。"
-    },
     {
       "name": "SlotComponent",
       "type": "component",
@@ -38,6 +38,13 @@
       "signature": "<SlotComponent>",
       "description": "插槽渲染辅助组件。用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数或静态字符串。"
     },
+    {
+      "name": "BaseComponentMap",
+      "type": "type",
+      "package": "@qin-ui/antdv-next-pro",
+      "signature": "export type BaseComponentMap =",
+      "description": "内置组件映射表\nantdv-next 内置支持的组件类型映射。\n每个 key 对应 Field 配置中 `component` 可使用的字符串值，\nvalue 为实际渲染的 antdv-next 组件。"
+    },
     {
       "name": "ComponentMap",
       "type": "interface",
@@ -55,13 +62,20 @@
       "signature": "export type ComponentName =\n  | keyof BaseComponentMap\n  | keyof ComponentMap\n  | 'custom';",
       "description": "组件名称联合类型\n所有支持的组件名称"
     },
+    {
+      "name": "componentMap",
+      "type": "function",
+      "package": "@qin-ui/antdv-next-pro",
+      "signature": "export const componentMap: BaseComponentMap =",
+      "description": "组件名称到 antdv-next 组件的运行时映射\nProForm 通过此映射将 Field 配置中的 component 字符串解析为实际 Vue 组件。\n例如 `component: 'input'` → `Input`, `component: 'select'` → `Select`。"
+    },
     {
       "name": "useFormData",
       "type": "function",
       "package": "@qin-ui/antdv-next-pro",
-      "signature": "export const useFormData = <D extends Data = Data>(\n  initFormData?: ExtendWithAny<DeepPartial<D>>\n) =>",
+      "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- 父子表单自动注入（非根表单会从注入中获取数据）",
-      "returns": "{Function} .setFormData(path, value) - 设置指定路径的数据",
+      "returns": "{UseFormDataReturn<D>} 表单数据操作对象",
       "typeParams": [
         {
           "name": "D"
@@ -75,15 +89,16 @@
       "name": "useFields",
       "type": "function",
       "package": "@qin-ui/antdv-next-pro",
-      "signature": "export const useFields = _useFields as",
-      "description": "类型安全的 re-export。将 core useFields 的泛型参数绑定为本地类型：\n- 字段类型 F → Field<ComponentName, D>（支持 antdv-next 组件类型推导）\n- FormItem 实例 → antdv-next 的 FormItemInstance",
+      "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`，将泛型参数绑定为 antdv-next 的本地类型：\n- 字段类型 F → `Field<ComponentName, D>`（支持 antdv-next 组件类型推导）\n- FormItem 实例 → antdv-next 的 `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?)` — 获取父级字段配置",
+      "returns": "字段操作对象，包含以下属性：",
       "typeParams": [
         {
           "name": "D"
         }
       ],
       "examples": [
-        "```ts\ninterface User { name: string; age: number }\n\nconst { fields, getField, setField } = useFields<User>([\n{ path: 'name', label: '姓名', component: 'input' },\n{ path: 'age', label: '年龄', component: 'input-number' },\n])\n```"
+        "```ts\ninterface User { name: string; age: number }\n\nconst { fields, getField, setField } = useFields<User>([\n{ path: 'name', label: '姓名', component: 'input' },\n{ path: 'age', label: '年龄', component: 'input-number' },\n])\n\n// 通过路径获取\ngetField('name')\n// 通过查找函数获取\ngetField(f => f.label === '姓名')\n// 更新字段（合并模式）\nsetField('name', { label: '用户名', disabled: true })\n```"
       ]
     },
     {
@@ -91,14 +106,14 @@
       "type": "type",
       "package": "@qin-ui/antdv-next-pro",
       "signature": "export type UseFields<D extends Data = Data> = ReturnType<typeof useFields<D>>;",
-      "description": "useFields 返回值类型，固定为本地 Fields<D>"
+      "description": "useFields 返回值类型"
     },
     {
       "name": "Form",
       "type": "type",
       "package": "@qin-ui/antdv-next-pro",
       "signature": "export type Form<\n  D extends Data = Data,\n  F extends Field<ComponentName, D> = Field<ComponentName, D>,\n> = _Form<D, F, FormInstance>;",
-      "description": "在 core Form 类型的基础上：\n1. 将字段类型 F 默认绑定为本地 Field<ComponentName, D>，支持 antdv-next 所有内置组件类型\n2. 将底层表单实例 I 绑定为 antdv-next 的 FormInstance，使 formRef 获得完整的类型提示",
+      "description": "表单实例类型\n在 core Form 类型的基础上，将字段类型 F 绑定为本地 Field<ComponentName, D>，\n将底层表单实例 I 绑定为 antdv-next 的 FormInstance，使 formRef 获得完整的类型提示。\n1. `setFormData(path, value)` — 设置指定路径的值<br>\n2. `setFormData(path, prev => newVal)` — 函数式更新<br>\n3. `setFormData({ ... })` — 批量覆盖整个表单",
       "typeParams": [
         {
           "name": "D"
@@ -108,35 +123,50 @@
         }
       ],
       "examples": [
-        "```ts\ninterface User { name: string; age: number }\nconst form: Form<User> = useForm({ name: '张三', age: 25 })\nform.formRef.value?.validate() // 类型安全地访问 antdv-next Form validate 方法\n```"
+        "```ts\ninterface User { name: string; age: number }\nconst form: Form<User> = useForm({ name: '张三', age: 25 })\n\nform.formData.name           // 直接读写响应式数据\nform.getFormData('name')     // 通过路径读取\nform.setFormData('name', '李四')  // 更新数据\nform.formRef.value?.validate()    // 访问底层 Form 实例\n```"
       ]
     },
     {
       "name": "useForm",
       "type": "function",
       "package": "@qin-ui/antdv-next-pro",
-      "signature": "export const useForm = _useForm as",
-      "description": "创建 @qin-ui/antdv-next-pro 表单实例的 Hook\n类型安全的 re-export。将 core useForm 的泛型参数绑定为本地类型：\n- 字段类型 F → Field<ComponentName, D>（支持 antdv-next 组件类型推导）\n- 表单实例 → antdv-next 的 FormInstance",
+      "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`，将泛型参数绑定为 antdv-next 的本地类型：\n- 字段类型 F → `Field<ComponentName, D>`（支持 antdv-next 所有内置组件类型推导）\n- 表单实例 → antdv-next 的 `FormInstance`（使 formRef 获得完整的类型提示）\n表单实例组合了三个子模块的能力：\n- **useFormData**：表单数据管理（响应式数据、读写、批量更新）\n- **useFields**：字段配置管理（增删改查字段配置，支持嵌套）\n- **useFormRef**：底层 Form 组件实例引用",
+      "returns": "{Form<D>} 表单实例，包含数据操作、字段操作和 ref 操作",
       "typeParams": [
         {
           "name": "D"
         }
       ],
       "examples": [
-        "```ts\ninterface User { name: string; age: number }\n\nconst form = useForm<User>(\n{ name: '张三', age: 25 },\n[\n{ path: 'name', label: '姓名', component: 'input' },\n{ path: 'age', label: '年龄', component: 'input-number' },\n],\ntrue\n)\n```"
+        "```ts\ninterface User { name: string; age: number }\n\n// 方式一：同时传入初始数据和字段\nconst form = useForm<User>(\n{ name: '张三', age: 25 },\n[\n{ path: 'name', label: '姓名', component: 'input' },\n{ path: 'age', label: '年龄', component: 'input-number' },\n],\ntrue\n)\n\n// 方式二：仅设置 root 标识\nconst form = useForm<User>(true)\n\n// 使用\nconst { formData, formRef, fields, setFormData, getField } = form\nsetFormData('name', '李四')\nawait formRef.value?.validate()\n```"
       ]
     },
     {
       "name": "useFormRef",
       "type": "function",
       "package": "@qin-ui/antdv-next-pro",
-      "signature": "export const useFormRef = _useFormRef as",
-      "description": "类型安全的 re-export。将 core useFormRef 的泛型参数绑定为 antdv-next 的 FormInstance，\n使 formRef 获取到完整的 antdv-next Form 组件 API 类型提示。",
-      "returns": "{Function} .setFormRef(inst) - 设置表单组件实例",
+      "signature": "export function useFormRef(): UseFormRefReturn<FormInstance>",
+      "description": "表单组件实例引用 Hook\n基于 `@qin-ui/pro-components-core` 的 `useFormRef`，将泛型参数绑定为 antdv-next 的 `FormInstance`，\n使 formRef 获取到完整的 antdv-next Form 组件 API 类型提示（如 `validate()`、`resetFields()` 等）。\n`formRef` 由 ProForm 组件内部自动通过 `setFormRef` 绑定，无需手动调用。\n- `formRef` — antdv-next Form 组件实例的响应式引用（`Ref<FormInstance | undefined>`）\n- `setFormRef(inst)` — 设置 Form 组件实例，由 ProForm 内部自动调用",
+      "returns": "表单组件实例引用管理对象：",
       "examples": [
-        "```ts\nconst { formRef, setFormRef } = useFormRef()\nawait formRef.value?.validate()\nformRef.value?.resetFields()\n```"
+        "```ts\nconst { formRef, setFormRef } = useFormRef()\n\n// formRef 由 ProForm 自动绑定，可直接使用\nawait formRef.value?.validate()\nformRef.value?.resetFields()\nformRef.value?.scrollToField('username')\n```"
       ]
     },
+    {
+      "name": "Base",
+      "type": "type",
+      "package": "@qin-ui/antdv-next-pro",
+      "signature": "export type Base<D extends Data = Data> =\n  | BaseWithFields<D>\n  | BaseWithoutFields<D>;",
+      "description": "字段配置的基础公共类型\n定义了 ProForm 字段配置的**保留属性**（由 ProForm 自身消费，不会透传给底层组件）：\n- path, label, component - 字段标识与渲染\n- hidden, disabled, rules - 字段状态与校验\n- span, slots, grid, fields - 布局与嵌套\n- modelProp, valueFormatter - 双向绑定与值转换\n- formItemStyle/Class/Container/DataAttrs - FormItem 容器样式\n- componentStyle/Class/Container/DataAttrs - 输入组件样式\n- extraProps - 自定义扩展属性\n**重要：所有未在此列出的属性将直接 v-bind 透传到底层 antdv-next 组件。**"
+    },
+    {
+      "name": "FieldTypeMap",
+      "type": "type",
+      "package": "@qin-ui/antdv-next-pro",
+      "signature": "export type FieldTypeMap<D extends Data = Data> =",
+      "description": "字段类型映射集合\n将每个 component 字符串映射到其对应的 antdv-next 组件 Props 类型。\n例如 `component: 'select'` 时，Field 获得 Select 组件的所有 Props（options, mode, showSearch 等）作为类型提示。\n`component: 'custom'` 支持通过渲染函数或直接传入 Vue 组件进行完全自定义渲染。"
+    },
     {
       "name": "Field",
       "type": "type",
@@ -181,7 +211,7 @@
       "type": "type",
       "package": "@qin-ui/antdv-next-pro",
       "signature": "export type Table<\n  D extends Data = Data,\n  T extends Data = ExtendWithAny<D>,\n> = _Table<D, T, Column<T>>;",
-      "description": "在 core Table 类型的基础上，将列类型 C 绑定为本地 Column<T>，\n使 columns 操作获得 antdv-next 表格列的完整属性类型提示。",
+      "description": "表格实例类型\n在 core Table 类型的基础上，将列类型 C 绑定为本地 Column\\<T\\>，\n使 columns 操作获得 antdv-next 表格列的完整属性类型提示。",
       "typeParams": [
         {
           "name": "D"
@@ -189,14 +219,26 @@
         {
           "name": "T"
         }
+      ],
+      "examples": [
+        "```ts\ninterface User { name: string; age: number; email: string }\n\nconst table: Table<{}, User> = useTable({\ncolumns: [{ dataIndex: 'name', title: '姓名' }],\n})\n\ntable.columns.value                  // 访问列配置\ntable.setColumn('name', { width: 150 }) // 更新列\ntable.setPageParam({ current: 2 })      // 切换页码\ntable.searchForm.setFormData('keyword', '搜索词') // 操作搜索表单\n```"
       ]
     },
     {
       "name": "useTable",
       "type": "function",
       "package": "@qin-ui/antdv-next-pro",
-      "signature": "export const useTable: <\n  D extends Data = Data,\n  T extends Data = ExtendWithAny<D>,\n>(params:",
-      "description": "创建 @qin-ui/antdv-next-pro 表格实例的 Hook\n类型安全的 re-export。将 core useTable 的列类型绑定为本地 Column<T>，\n使 columns 操作获得 antdv-next 表格列的完整类型提示。",
+      "signature": "export function useTable<\n  D extends Data = Data,\n  T extends Data = ExtendWithAny<D>,\n>(params:",
+      "description": "创建表格实例的 Hook\n基于 `@qin-ui/pro-components-core` 的 `useTable`，将列类型绑定为本地 `Column<T>`。\n是 ProTable 组件的核心 Hook，提供了：\n- 列配置管理（增删改查）\n- 数据源管理\n- 分页管理\n- 搜索表单集成（内部使用 useForm）\n- 查询参数重置",
+      "params": [
+        {
+          "name": "params",
+          "type": "object",
+          "optional": false,
+          "description": "表格配置参数"
+        }
+      ],
+      "returns": "{Table<D, T>} 表格实例",
       "typeParams": [
         {
           "name": "D"
@@ -206,7 +248,7 @@
         }
       ],
       "examples": [
-        "```ts\ninterface User { name: string; age: number; email: string }\n\nconst table = useTable<User>({\ncolumns: [\n{ dataIndex: 'name', title: '姓名', width: 120 },\n{ dataIndex: 'age', title: '年龄', width: 80 },\n],\ndataSource: [],\npageParam: { current: 1, pageSize: 20, total: 0 },\n})\n```"
+        "```ts\ninterface SearchParams { keyword: string; status: string }\ninterface User { name: string; age: number; email: string }\n\nconst table = useTable<SearchParams, User>({\ncolumns: [\n{ dataIndex: 'name', title: '姓名', width: 120 },\n{ dataIndex: 'age', title: '年龄', width: 80 },\n],\ndataSource: [],\npageParam: { current: 1, pageSize: 20, total: 0 },\nsearchParam: { keyword: '', status: '' },\nsearchFields: [\n{ path: 'keyword', label: '关键词', component: 'input' },\n{ path: 'status', label: '状态', component: 'select' },\n],\n})\n\n// 查询\nconst handleSearch = async () => {\nconst res = await fetchUserList({\n...table.searchForm.formData,\n...table.pageParam,\n})\ntable.dataSource.value = res.data\ntable.setPageParam({ total: res.total })\n}\n\n// 重置\nconst handleReset = () => {\ntable.resetQueryParams()\nhandleSearch()\n}\n```"
       ]
     }
   ]