@qin-ui/antd-vue-pro
Version:
340 lines • 19.5 kB
JSON
{
"generatedAt": "2026-08-05T02:02:12.968Z",
"name": "@qin-ui/antd-vue-pro",
"api": [
{
"name": "ProComponentProvider",
"type": "component",
"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```"
]
},
{
"name": "ComponentVars",
"type": "type",
"package": "@qin-ui/antd-vue-pro",
"signature": "export type ComponentVars = Partial<RequiredComponentVars>;",
"description": "组件全局配置\nRequiredComponentVars 的 Partial 版本，用于 ProComponentProvider 的 props"
},
{
"name": "ContainerFragment",
"type": "component",
"package": "@qin-ui/antd-vue-pro",
"signature": "<ContainerFragment>",
"description": "容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。"
},
{
"name": "ProForm",
"type": "component",
"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"
}
],
"examples": [
"```vue\n<template>\n<ProForm :form=\"form\" @submit=\"handleSubmit\">\n<template #name=\"{ value, disabled }\">\n<a-input :value=\"value\" :disabled=\"disabled\" />\n</template>\n</ProForm>\n</template>\n```"
]
},
{
"name": "SlotComponent",
"type": "component",
"package": "@qin-ui/antd-vue-pro",
"signature": "<SlotComponent>",
"description": "插槽渲染辅助组件。用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数或静态字符串。"
},
{
"name": "ComponentMap",
"type": "interface",
"package": "@qin-ui/antd-vue-pro",
"signature": "export interface ComponentMap {}",
"description": "组件映射扩展接口\n暴露给外部扩充自定义组件类型的接口。\n用户可通过 TypeScript 的声明合并（module augmentation）添加自定义组件。",
"examples": [
"```ts\n// 在项目中任意 .d.ts 文件中\ndeclare module '@qin-ui/antd-vue-pro' {\ninterface ComponentMap {\n'my-custom-input': typeof MyCustomInput;\n'my-editor': typeof MyRichTextEditor;\n}\n}\n```"
]
},
{
"name": "ComponentName",
"type": "type",
"package": "@qin-ui/antd-vue-pro",
"signature": "export type ComponentName =\n | keyof BaseComponentMap\n | keyof ComponentMap\n | 'custom';",
"description": "组件名称联合类型\n所有支持的组件名称，包括内置组件、用户扩展组件和自定义组件 'custom'\n- 内置组件：'input' | 'select' | 'date-picker' 等\n- 扩展组件：通过 ComponentMap 声明的自定义组件名\n- 'custom'：完全自定义渲染组件",
"examples": [
"```ts\ntype Name = ComponentName\n// 'input' | 'select' | 'date-picker' | ... | 'custom'\n```"
]
},
{
"name": "useFormData",
"type": "function",
"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": [
{
"name": "D"
}
],
"examples": [
"```ts\ninterface User { name: string; age: number; address: { city: string } }\n\nconst { formData, getFormData, setFormData } = useFormData<User>({\nname: '张三',\naddress: { city: '北京' }\n})\n\n// 读取\ngetFormData('name') // '张三'\ngetFormData('address.city') // '北京'\nformData.name // '张三'（响应式）\n\n// 设置\nsetFormData('name', '李四')\nsetFormData('address.city', '上海')\nsetFormData({ name: '王五', age: 30 }) // 批量覆盖\nsetFormData(prev => ({ ...prev, name: '赵六' })) // 函数式更新\n```"
]
},
{
"name": "useFields",
"type": "function",
"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": [
{
"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\n// 通过路径获取\ngetField('name')\n// 通过查找函数获取\ngetField(f => f.label === '姓名')\n// 更新字段（合并模式）\nsetField('name', { label: '用户名', disabled: true })\n```"
]
},
{
"name": "UseFields",
"type": "type",
"package": "@qin-ui/antd-vue-pro",
"signature": "export type UseFields<D extends Data = Data> = ReturnType<typeof useFields<D>>;",
"description": "useFields 返回值类型"
},
{
"name": "Form",
"type": "type",
"package": "@qin-ui/antd-vue-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": "表单实例类型\n在 core Form 类型的基础上，将字段类型 F 绑定为本地 Field<ComponentName, D>，\n将底层表单实例 I 绑定为 Ant Design Vue 的 FormInstance，使 formRef 获得完整的类型提示。\n1. `setFormData(path, value)` - 设置指定路径的值<br>\n2. `setFormData(path, prev => newVal)` - 函数式更新<br>\n3. `setFormData({ ... })` - 批量覆盖整个表单",
"typeParams": [
{
"name": "D"
},
{
"name": "F"
}
],
"examples": [
"```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/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": [
{
"name": "D"
}
],
"examples": [
"```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/antd-vue-pro",
"signature": "export function useFormRef(): UseFormRefReturn<FormInstance>",
"description": "表单组件实例引用 Hook\n基于 `@qin-ui/pro-components-core` 的 `useFormRef`，将泛型参数绑定为 Ant Design Vue 的 `FormInstance`，\n使 formRef 获取到完整的 Ant Design Vue Form 组件 API 类型提示（如 `validate()`、`resetFields()` 等）。\n`formRef` 由 ProForm 组件内部自动通过 `setFormRef` 绑定，无需手动调用。\n- `formRef` — Ant Design Vue Form 组件实例的响应式引用（`Ref<FormInstance | undefined>`）\n- `setFormRef(inst)` — 设置 Form 组件实例，由 ProForm 内部自动调用",
"returns": "表单组件实例引用管理对象：",
"examples": [
"```ts\nconst { formRef, setFormRef } = useFormRef()\n\n// formRef 由 ProForm 自动绑定，可直接使用\nawait formRef.value?.validate()\nformRef.value?.resetFields()\nformRef.value?.scrollToField('username')\n```"
]
},
{
"name": "Field",
"type": "type",
"package": "@qin-ui/antd-vue-pro",
"signature": "export type Field<\n C extends ComponentName = ComponentName,\n D extends Data = Data,\n> = FieldTypeMap<D>[C] | WithFields<D>;",
"description": "字段配置类型，包含所有字段属性和响应式支持",
"typeParams": [
{
"name": "D"
}
]
},
{
"name": "Fields",
"type": "type",
"package": "@qin-ui/antd-vue-pro",
"signature": "export type Fields<D extends Data = Data> = Array<Field<ComponentName, D>>;",
"description": "字段数组类型",
"typeParams": [
{
"name": "D"
}
]
},
{
"name": "Table",
"type": "type",
"package": "@qin-ui/antd-vue-pro",
"signature": "export type Table<\n D extends Data = Data,\n T extends Data = ExtendWithAny<D>,\n> = _Table<D, T, Column<T>>;",
"description": "表格实例类型\n在 core Table 类型的基础上，将列类型 C 绑定为本地 Column<T>，\n使 columns 操作获得 Ant Design Vue 表格列的完整属性类型提示。",
"typeParams": [
{
"name": "D"
},
{
"name": "T"
}
],
"examples": [
"```ts\ninterface SearchParams { keyword: string }\ninterface User { name: string; age: number }\n\nconst table: Table<SearchParams, 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/antd-vue-pro",
"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": "表格配置参数"
},
{
"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>} 表格实例",
"typeParams": [
{
"name": "D"
},
{
"name": "T"
}
],
"examples": [
"```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```"
]
},
{
"name": "Column",
"type": "type",
"package": "@qin-ui/antd-vue-pro",
"signature": "export type Column<D extends Data = Data> = Omit<\n ColumnType,\n 'dataIndex' | 'key'\n> &",
"description": "继承 Ant Design Vue 的 ColumnType 列类型，并添加：\n- 类型安全的 dataIndex（基于泛型 D 推导路径），优先使用\n- key 作为辅助标识，当 dataIndex 不满足需求时使用\n- hidden 属性用于控制列显隐\n- 所有 Ant Design Vue 原生的列属性依然可用（title、width、fixed、align 等）",
"typeParams": [
{
"name": "D"
}
],
"examples": [
"```ts\ninterface User { name: string; age: number }\n\nconst columns: Columns<User> = [\n{\n// dataIndex 是主要字段，关联数据源中对应字段路径\ndataIndex: 'name',\ntitle: '姓名',\nwidth: 120,\n},\n{\ndataIndex: 'age',\ntitle: '年龄',\nwidth: 80,\n},\n]\n```"
]
}
]
}