@qin-ui/antdv-next-pro 1.1.9 → 1.1.11

package/es/index.d.ts

@@ -35,7 +35,6 @@ import { FormTooltipProps } from 'antdv-next/dist/form/FormItemLabel';
 import { GlobalComponents } from 'vue';
 import { GlobalDirectives } from 'vue';
 import { HTMLAttributes } from 'vue';
-import { InjectionKey } from 'vue';
 import { Input } from 'antdv-next';
 import { InputNumber } from 'antdv-next';
 import { InputOTP } from 'antdv-next';
@@ -69,7 +68,7 @@ import { Variant } from 'antdv-next/dist/config-provider/context';
 import { VNode } from 'vue';
 import { VNodeProps } from 'vue';
 
-declare const __VLS_component: DefineComponent<Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props_2> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+declare const __VLS_component: DefineComponent<Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 declare type __VLS_PrettifyLocal<T> = {
     [K in keyof T]: T[K];
@@ -97,13 +96,17 @@ declare type __VLS_WithTemplateSlots<T, S> = T & {
     };
 };
 
+/**
+ * FormItem 实例提供的额外方法
+ * @template FormItemInstance - FormItem 组件实例类型
+ */
 declare type AdditionalMethods<FormItemInstance> = {
     /**
-     * @description 获取FormItem实例的方法
+     * @description 获取 FormItem 实例的方法
      */
     getFormItemRef?: () => FormItemInstance;
     /**
-     * @description 获取传入FormItem组件的属性
+     * @description 获取传入 FormItem 组件的属性
      */
     getFormItemComputedProps?: () => Readonly<{
         [x: string]: any;
@@ -113,7 +116,7 @@ declare type AdditionalMethods<FormItemInstance> = {
      */
     getComponentRef?: () => any;
     /**
-     * @description 获取传入Component组件的属性
+     * @description 获取传入 Component 组件的属性
      */
     getComponentComputedProps?: () => Readonly<{
         disabled?: boolean;
@@ -128,12 +131,49 @@ declare type AllowStringKey<T, Prefix extends string = ''> = {
 /**
  * @type {Object} Base - 基础公共字段类型
  */
-export declare type Base<D extends Data = Data> = BaseWithFields<D> | BaseWithoutFields<D>;
+declare type Base<D extends Data = Data> = BaseWithFields<D> | BaseWithoutFields<D>;
 
+/**
+ * 基础表格列配置接口
+ * @template D - 表格数据类型，应为一个对象类型
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number; address: { city: string } }
+ *
+ * // 简单列
+ * const column: BaseColumn<User> = {
+ *   key: 'name',
+ *   title: '姓名',
+ * }
+ *
+ * // 带数据索引和嵌套列
+ * const column: BaseColumn<User> = {
+ *   key: 'address',
+ *   title: '地址',
+ *   children: [
+ *     { key: 'city', title: '城市' },
+ *   ],
+ * }
+ * ```
+ */
 declare interface BaseColumn<D extends Data = Data> {
+    /**
+     * @description 列字段路径（数据对象的 key 路径），支持点号分隔的深层路径
+     * @example 'name' | 'address.city'
+     */
     key?: Path<D>;
+    /**
+     * @description 数据索引，与 key 作用类似，支持数组格式
+     * @example 'name' | ['address', 'city']
+     */
     dataIndex?: Path<D> | Path<D>[];
+    /**
+     * @description 嵌套子列配置，用于实现表头分组
+     * @example [{ key: 'firstName', title: '名' }, { key: 'lastName', title: '姓' }]
+     */
     children?: BaseColumn<D>[];
+    /** 其他任意自定义属性（如 title、width、fixed 等 UI 属性） */
     [key: string]: any;
 }
 
@@ -195,7 +235,11 @@ declare type BaseCommon<D extends Data = Data> = {
     extraProps?: Record<string, any>;
 };
 
-export declare type BaseComponentMap = {
+/**
+ * 内置组件映射表
+ * @description antdv-next 内置支持的组件类型映射
+ */
+declare type BaseComponentMap = {
     'input': typeof Input;
     'textarea': typeof TextArea;
     'input-search': typeof InputSearch;
@@ -217,49 +261,49 @@ export declare type BaseComponentMap = {
     'transfer': typeof Transfer;
 };
 
-export declare const BaseField: DefineComponent<Props, {
-getComponentRef: () => any;
-getComponentComputedProps: () => any;
-}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
-componentRef: unknown;
-}, any>;
-
-declare interface BaseField_2<D extends Data = Data> {
+/**
+ * 基础字段配置接口
+ * @template D - 表单数据类型，应为一个对象类型
+ *
+ * @example
+ * ```ts
+ * // 简单的文本输入字段
+ * const field: BaseField<{ name: string }> = {
+ *   path: 'name',
+ *   label: '姓名',
+ * }
+ *
+ * // 带嵌套子字段
+ * const field: BaseField<{ address: { city: string; street: string } }> = {
+ *   path: 'address',
+ *   label: '地址',
+ *   fields: [
+ *     { path: 'city', label: '城市' },
+ *     { path: 'street', label: '街道' },
+ *   ],
+ * }
+ * ```
+ */
+declare interface BaseField<D extends Data = Data> {
+    /**
+     * @description 字段路径（数据对象的 key 路径），支持点号分隔的深层路径
+     * @example 'name' | 'user.address.city'
+     */
     path?: Path<D> | any;
+    /**
+     * @description 字段名称，与 path 作用相同，两者选其一即可
+     * @deprecated 推荐使用 path 替代
+     */
     name?: any;
+    /**
+     * @description 嵌套子字段配置数组，用于实现分组/嵌套字段
+     * @example [{ path: 'firstName', label: '名' }, { path: 'lastName', label: '姓' }]
+     */
     fields?: any[];
+    /** 其他任意自定义属性 */
     [key: string]: any;
 }
 
-export declare const BaseForm: <F extends Form<any> = Form>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal_2<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
-    props: __VLS_PrettifyLocal_2<Pick<Partial<{}> & Omit<{} & VNodeProps & AllowedComponentProps & ComponentCustomProps, never>, never> & ({
-        grid?: Grid;
-        form?: F;
-    } & Partial<Omit<FormProps, "model">>) & Partial<{}>> & PublicProps;
-    expose(exposed: ShallowUnwrapRef<    {}>): void;
-    attrs: any;
-    slots: Readonly<Partial<Record<F extends Form<infer D extends Data> ? Path<D> : string, Slot<VModelProps & {
-        path?: string;
-    } & Data & {
-        [x: string]: any;
-        disabled?: boolean;
-    }>> & {
-        default: Slot;
-    }>> & Partial<Record<F extends Form<infer D extends Data> ? Path<D> : string, Slot<VModelProps & {
-        path?: string;
-    } & Data & {
-        [x: string]: any;
-        disabled?: boolean;
-    }>> & {
-        default: Slot;
-    }>;
-    emit: {};
-}>) => VNode & {
-    __ctx?: Awaited<typeof __VLS_setup>;
-};
-
-export declare const BaseFormItem: DefineComponent<Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props_4> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
-
 declare type BaseWithFields<D extends Data = Data> = BaseCommon<D> & {
     /**
      * @description 嵌套子字段配置
@@ -341,34 +385,102 @@ declare type ButtonProps = {
     onClick: () => void;
 };
 
+/**
+ * @qin-ui/antdv-next-pro 表格列配置类型
+ *
+ * @description 继承 antdv-next 的 ColumnType 列类型，并添加：
+ * - 类型安全的 dataIndex（基于泛型 D 推导路径），优先使用
+ * - key 作为辅助标识
+ * - hidden 属性用于控制列显隐
+ *
+ * @template D - 表格行数据类型
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number }
+ *
+ * const columns: Columns<User> = [
+ *   { dataIndex: 'name', title: '姓名', width: 120 },
+ *   { dataIndex: 'age', title: '年龄', width: 80 },
+ * ]
+ * ```
+
+ * @public
+ */
 export declare type Column<D extends Data = Data> = Omit<TableColumnType, 'dataIndex' | 'key'> & {
+    /**
+     * @description 列数据路径（主要字段），优先使用 dataIndex 进行字段匹配
+     * @example 'name' | 'address.city' | ['address', 'city']
+     */
     dataIndex?: KeyExpandString<Extract<keyof D, string>> | Paths<D>;
+    /**
+     * @description 列字段标识（辅助字段），当 dataIndex 不满足需求时使用
+     */
     key?: Path<D>;
+    /**
+     * @description 是否隐藏该列
+     * @default false
+     */
     hidden?: boolean;
 };
 
+/**
+ * 列查找函数类型，通过自定义函数匹配列
+ * @template D - 表格数据类型
+ * @template C - 列配置类型
+ *
+ * @example
+ * ```ts
+ * // 查找 title 为 '姓名' 的列
+ * const findBy: ColumnFindBy<MyData> = (column) => column.title === '姓名'
+ *
+ * // 查找所有宽度小于 100 的列
+ * const findBy: ColumnFindBy<MyData> = (column) => column.width && column.width < 100
+ * ```
+ */
 declare type ColumnFindBy<D extends Data, C extends BaseColumn<D> = BaseColumn<D>> = (column: Readonly<C>) => boolean;
 
+/**
+ * @qin-ui/antdv-next-pro 表格列配置数组类型
+ * @template D - 表格行数据类型
+
+ * @public
+ */
 export declare type Columns<D extends Data = Data> = Array<Column<D>>;
 
+/**
+ * 列配置数组类型
+ * @template D - 表格数据类型
+ * @template C - 列配置类型
+ */
 declare type Columns_2<D extends Data = Data, C extends BaseColumn<D> = BaseColumn<D>> = Array<C>;
 
 /**
- * @description 暴露给外部扩充自定义组件类型的接口
+ * 组件映射扩展接口
+ * @description 暴露给外部扩充自定义组件类型的接口。
+ * 用户可通过 TypeScript 的声明合并（module augmentation）添加自定义组件。
+ *
  * @example
  * ```ts
- * declare module 'antdv-next-pro' {
+ * // 在项目中任意 .d.ts 文件中
+ * declare module '@qin-ui/antdv-next-pro' {
  *   interface ComponentMap {
  *     'my-custom-input': typeof MyCustomInput;
  *   }
  * }
  * ```
+
+ * @public
  */
 export declare interface ComponentMap {
 }
 
-export declare const componentMap: BaseComponentMap;
+/**
+ * 组件名称联合类型
+ * @description 所有支持的组件名称
 
+ * @public
+ */
 export declare type ComponentName = keyof BaseComponentMap | keyof ComponentMap | 'custom';
 
 export declare type ComponentVars = Partial<RequiredComponentVars>;
@@ -376,17 +488,45 @@ export declare type ComponentVars = Partial<RequiredComponentVars>;
 /**
  * @description 容器组件类型
  */
-export declare type ContainerComponent = Component<PathProps>;
+declare type ContainerComponent = Component<PathProps>;
 
 export declare const ContainerFragment: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 
+/**
+ * 基础数据类型，表示任意对象
+ * @description 所有表单数据对象和表格数据对象的基础类型
+ */
 declare type Data = Record<string, any>;
 
+/**
+ * 递归地将对象的所有属性变为可选
+ * @template T - 原始类型
+ *
+ * @example
+ * ```ts
+ * type T = DeepPartial<{ name: string; address: { city: string } }>
+ * // { name?: string; address?: { city?: string } }
+ * ```
+ */
 declare type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
 
 declare const _default: {
+    /**
+     * @qin-ui/antdv-next-pro 安装方法
+     * @description 全局注册所有组件（ProForm、ProTable、ProComponentProvider）
+     *
+     * @param {App} app - Vue 应用实例
+     *
+     * @example
+     * ```ts
+     * import { createApp } from 'vue'
+     * import QinUI from '@qin-ui/antdv-next-pro'
+     * const app = createApp(App)
+     * app.use(QinUI)
+     * ```
+     */
     install(app: App): void;
 };
 export default _default;
@@ -450,9 +590,9 @@ declare const _default_2: <T extends Table<any> = Table>(__VLS_props: NonNullabl
         bodyCell?: (props: {
             text: any;
             value: any;
-            record: T extends Table<infer U extends Data> ? U : never;
+            record: T extends Table<any, infer R extends Data> ? R : never;
             index: number;
-            column: Column<T extends Table<infer U extends Data> ? U : never>;
+            column: Column<T extends Table<any, infer R extends Data> ? R : never>;
         }) => void;
     }> & Readonly<Partial<Record<"table" | "search-form" | "button-bar" | "toolbar", Slot>>>, "default">> & Omit<Omit<Readonly<{
         default?: (() => any) | undefined;
@@ -489,9 +629,9 @@ declare const _default_2: <T extends Table<any> = Table>(__VLS_props: NonNullabl
         bodyCell?: (props: {
             text: any;
             value: any;
-            record: T extends Table<infer U extends Data> ? U : never;
+            record: T extends Table<any, infer R extends Data> ? R : never;
             index: number;
-            column: Column<T extends Table<infer U extends Data> ? U : never>;
+            column: Column<T extends Table<any, infer R extends Data> ? R : never>;
         }) => void;
     }> & Readonly<Partial<Record<"table" | "search-form" | "button-bar" | "toolbar", Slot>>>, "default">;
     emit: ((evt: "update:size", value: ButtonSize) => void) & ((evt: "update:loading", value: boolean) => void);
@@ -499,7 +639,34 @@ declare const _default_2: <T extends Table<any> = Table>(__VLS_props: NonNullabl
     __ctx?: Awaited<typeof __VLS_setup>;
 };
 
-export declare const ensureInjectConfig: (key: string) => InjectConfigEntry;
+declare const _default_3: <F extends Form<any> = Form>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal_2<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal_2<Pick<Partial<{}> & Omit<{} & VNodeProps & AllowedComponentProps & ComponentCustomProps, never>, never> & ({
+        grid?: Grid;
+        form?: F;
+    } & Partial<Omit<FormProps, "model">>) & Partial<{}>> & PublicProps;
+    expose(exposed: ShallowUnwrapRef<    {}>): void;
+    attrs: any;
+    slots: Readonly<Partial<Record<F extends Form<infer D extends Data> ? Path<D> : string, Slot<VModelProps & {
+        path?: string;
+    } & Data & {
+        [x: string]: any;
+        disabled?: boolean;
+    }>> & {
+        default: Slot;
+    }>> & Partial<Record<F extends Form<infer D extends Data> ? Path<D> : string, Slot<VModelProps & {
+        path?: string;
+    } & Data & {
+        [x: string]: any;
+        disabled?: boolean;
+    }>> & {
+        default: Slot;
+    }>;
+    emit: {};
+}>) => VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+
+declare const _default_4: DefineComponent<Props_3, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props_3> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 declare type Expand = {
     minExpandRows?: number;
@@ -510,6 +677,18 @@ declare type ExpandButtonProps = ButtonProps & {
     expandStatus: boolean;
 };
 
+/**
+ * 用 Record<string, any> 扩展对象类型，保留所有原始属性结构，
+ * 同时允许访问任意字符串 key。
+ * @template D - 原始对象类型
+ *
+ * @example
+ * ```ts
+ * type T = ExtendWithAny<{ name: string; age: number }>
+ * // { name: string; age: number } & Record<string, any>
+ * // 可访问任意额外属性: obj.anyKey
+ * ```
+ */
 declare type ExtendWithAny<D> = {
     [K in keyof D]: IsRecord<D[K]> extends true ? ExtendWithAny<D[K]> : D[K];
 } & Record<string, any>;
@@ -517,23 +696,37 @@ declare type ExtendWithAny<D> = {
 /**
  * @description 字段配置类型，包含所有字段属性和响应式支持
  * @template D - 数据对象类型
+
+ * @public
  */
 export declare type Field<C extends ComponentName = ComponentName, D extends Data = Data> = (FieldTypeMap<D>[C] & {
     component?: C extends 'custom' ? FieldTypeMap<D>[C]['component'] : C;
 }) | WithFields<D>;
 
-declare type FieldFindBy<D extends Data, F extends BaseField_2<D> = BaseField_2<D>> = (field: Readonly<F>) => boolean;
+/**
+ * 字段查找函数类型，通过自定义函数匹配字段
+ * @template D - 表单数据类型
+ * @template F - 字段配置类型
+ * @example
+ * ```ts
+ * // 查找 label 为 '姓名' 的字段
+ * const findBy: FieldFindBy<MyData> = (field) => field.label === '姓名'
+ * ```
+ */
+declare type FieldFindBy<D extends Data, F extends BaseField<D> = BaseField<D>> = (field: Readonly<F>) => boolean;
 
 /**
  * @description 字段数组类型
  * @template D - 数据对象类型
+
+ * @public
  */
 export declare type Fields<D extends Data = Data> = Array<Field<ComponentName, D>>;
 
 /**
  * @type {FieldTypeMap} 字段类型集合
  */
-export declare type FieldTypeMap<D extends Data = Data> = {
+declare type FieldTypeMap<D extends Data = Data> = {
     [K in ComponentName]: K extends 'custom' ? WithCommon<{
         slots?: Slots;
         [x: string]: any;
@@ -545,18 +738,63 @@ export declare type FieldTypeMap<D extends Data = Data> = {
 };
 
 /**
- * 重新定义 Form 类型：
- * 1. 将第二个泛型参数 F 默认绑定为本地 Field<ComponentName, D>；
- * 2. 将 core Form 的第三个泛型参数 I 绑定为本地 UI 库（antdv-next）的 FormInstance，
- *    使 formRef 的类型变为 Ref<FormInstance | undefined>。
+ * @qin-ui/antdv-next-pro 的表单实例类型
+ *
+ * @description 在 core Form 类型的基础上：
+ * 1. 将字段类型 F 默认绑定为本地 Field<ComponentName, D>，支持 antdv-next 所有内置组件类型
+ * 2. 将底层表单实例 I 绑定为 antdv-next 的 FormInstance，使 formRef 获得完整的类型提示
+ *
+ * @template D - 表单数据类型
+ * @template F - 字段配置类型，默认使用本地 Field 类型
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number }
+ * const form: Form<User> = useForm({ name: '张三', age: 25 })
+ * form.formRef.value?.validate() // 类型安全地访问 antdv-next Form validate 方法
+ * ```
+
+ * @public
  */
 export declare type Form<D extends Data = Data, F extends Field<ComponentName, D> = Field<ComponentName, D>> = Form_2<D, F, FormInstance>;
 
-declare type Form_2<D extends Data = Data, F extends BaseField_2<D> = BaseField_2<D>, I = any> = ReturnType<typeof useFormData<D>> & ReturnType<typeof useFields_2<D, F>> & ReturnType<typeof useFormRef_2<I>>;
-
-export declare const FORM_ITEM_SLOT_KEYS: readonly ["label", "extra", "help", "tooltip"];
-
-export { FormInstance }
+/**
+ * 表单实例类型
+ * @template D - 表单数据类型
+ * @template F - 字段配置类型
+ * @template I - 底层 UI 框架 Form 组件实例类型
+ *
+ * 组合了表单数据操作、字段操作和表单 ref 操作的能力。
+ *
+ * @example
+ * ```ts
+ * // 定义数据类型
+ * interface User {
+ *   name: string
+ *   age: number
+ *   address: { city: string; street: string }
+ * }
+ *
+ * // 创建表单实例
+ * const form: Form<User> = useForm({
+ *   name: '张三',
+ *   age: 25,
+ * })
+ *
+ * // 读取数据
+ * form.getFormData('name') // '张三'
+ * form.getFormData('address.city') // 支持深层路径
+ *
+ * // 设置数据
+ * form.setFormData('name', '李四')
+ * form.setFormData({ name: '王五', age: 30 }) // 批量设置
+ *
+ * // 字段操作
+ * form.getField('name') // 获取字段配置
+ * form.setField('name', { label: '用户名' }) // 更新字段配置
+ * ```
+ */
+declare type Form_2<D extends Data = Data, F extends BaseField<D> = BaseField<D>, I = any> = ReturnType<typeof useFormData<D>> & ReturnType<typeof useFields_2<D, F>> & ReturnType<typeof useFormRef_2<I>>;
 
 declare type FormItemInstance = InstanceType<typeof FormItem>;
 
@@ -564,32 +802,18 @@ declare type _FormProps = Pick<Partial<FormProps>, 'colon' | 'disabled' | 'label
 
 declare type FP<T extends Record<string, any>> = Partial<T & Pick<Base, 'valueFormatter' | 'componentContainer' | 'modelProp' | 'componentClass' | 'componentStyle'> & AllowedComponentProps>;
 
-export declare type GetComponentType<K extends ComponentName> = K extends keyof ComponentMap ? ComponentMap[K] : K extends keyof BaseComponentMap ? BaseComponentMap[K] : never;
-
-export declare const getInitProps: (field: Field) => Record<string, any>;
-
-export declare const getInjectConfig: (key: string) => InjectConfigEntry | undefined;
-
-export declare type Grid = boolean | (RowProps & {});
-
-export declare const INJECT_COMPONENTS: InjectionKey<Partial<Record<string, Component>>>;
-
-export declare const INJECT_CONFIG: {
-    [key in keyof RequiredComponentVars]: {
-        injectionKey: InjectionKey<RequiredComponentVars[key]>;
-        default: RequiredComponentVars[key];
-    };
-};
-
-export declare type InjectConfigEntry<T = any> = {
-    injectionKey: InjectionKey<T>;
-    default: T;
-};
-
-export declare const InjectionFormKey: InjectionKey<any>;
+/**
+ * 根据组件名获取组件类型
+ * @template K - 组件名称
+ */
+declare type GetComponentType<K extends ComponentName> = K extends keyof ComponentMap ? ComponentMap[K] : K extends keyof BaseComponentMap ? BaseComponentMap[K] : never;
 
-export declare const InjectionPathKey: InjectionKey<ComputedRef<string | undefined>>;
+declare type Grid = boolean | (RowProps & {});
 
+/**
+ * 判断类型是否为对象（排除函数、数组和 null）
+ * @template T - 要判断的类型
+ */
 declare type IsRecord<T> = T extends object ? T extends ((...args: any[]) => any) | any[] | null ? false : true : false;
 
 declare type JoinPath<Prefix extends any[], Key extends PropertyKey> = [
@@ -597,8 +821,34 @@ declare type JoinPath<Prefix extends any[], Key extends PropertyKey> = [
 KeyExpandString<Extract<Key, string>>
 ];
 
+/**
+ * 展开字符串联合类型，保留字符串字面量，同时兼容 string
+ * @template T - 字符串字面量类型
+ */
 declare type KeyExpandString<T extends string> = T | (string & {});
 
+/**
+ * 点号分隔的路径字符串类型
+ * @template D - 数据对象类型
+ *
+ * @description 用于类型安全地表示深层对象属性的路径。
+ * 例如给定 `{ user: { name: string; address: { city: string } } }`，
+ * 路径值可以是 `'user'`、`'user.name'`、`'user.address.city'`。
+ *
+ * 同时兼容 string 类型，用于运行时动态路径。
+ *
+ * @example
+ * ```ts
+ * interface User {
+ *   name: string
+ *   age: number
+ *   address: { city: string; street: string }
+ * }
+ *
+ * type P = KeyPathString<User>
+ * // 'name' | 'age' | 'address' | 'address.city' | 'address.street' | string
+ * ```
+ */
 declare type KeyPathString<D extends Data> = KeyExpandString<AllowStringKey<D>>;
 
 declare type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
@@ -608,28 +858,66 @@ declare type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
  */
 declare type NotSupportedRefOrGetterProps = 'component' | 'formItemContainer' | 'componentContainer' | 'valueFormatter' | 'fields' | 'slots' | 'modelProp';
 
-declare type Option_2 = {
-    label: string;
-    value: any;
-    [x: string]: any;
-};
-export { Option_2 as Option }
-
-export declare type Options = Array<Option_2>;
-
+/**
+ * 分页参数
+ *
+ * @example
+ * ```ts
+ * const pageParam: PageParam = {
+ *   current: 1,
+ *   pageSize: 10,
+ *   total: 100,
+ * }
+ * ```
+ */
 declare interface PageParam {
+    /** 当前页码 */
     current: number;
+    /** 每页条数 */
     pageSize: number;
+    /** 总记录数 */
     total: number;
+    /** 其他自定义分页属性 */
     [key: string]: any;
 }
 
+/**
+ * 路径类型，用于类型安全的深层属性访问
+ * @template D - 数据对象类型
+ *
+ * @description 提供对数据对象的深层路径的类型推导。
+ * 在 useFormData、useFields 等 API 中作为 path 参数的类型。
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; address: { city: string } }
+ *
+ * // 类型安全的路径
+ * const path: Path<User> = 'address.city' // ✅
+ * const path: Path<User> = 'invalid.path' // ❌ 类型错误
+ * ```
+ */
 declare type Path<D extends Data = Data> = KeyPathString<D>;
 
-export declare type PathProps = {
+declare type PathProps = {
     path?: string;
 } & Data;
 
+/**
+ * 路径数组类型（Path 的数组表示）
+ * @template T - 数据对象类型
+ * @template Prefix - 前缀路径数组（内部递归使用）
+ *
+ * @description 与 Path 类似，但以元组数组形式表示路径。
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; address: { city: string } }
+ *
+ * type P = Paths<User>
+ * // ['name'] | ['address'] | ['address', 'city']
+ * ```
+ */
 declare type Paths<T, Prefix extends any[] = []> = T extends object ? {
     [K in keyof T]: IsRecord<T[K]> extends true ? JoinPath<Prefix, K> | Paths<T[K], JoinPath<Prefix, K>> : JoinPath<Prefix, K>;
 }[keyof T] : never;
@@ -697,21 +985,21 @@ export declare const ProForm: SFCWithInstall<(<F extends Form<any> = Form>(__VLS
         prefixCls?: string | undefined;
         wrapperCol?: (ColProps & Partial<HTMLAttributes>) | undefined;
         layout?: FormLayout | undefined;
-        onReset?: FormEmits["reset"] | undefined;
-        onSubmit?: FormEmits["submit"] | undefined;
+        size?: ButtonSize;
         disabled?: boolean | undefined;
-        labelWrap?: boolean | undefined;
+        variant?: Variant | undefined;
         classes?: FormClassNamesType | undefined;
         styles?: FormStylesType | undefined;
+        autoComplete?: string | undefined | undefined;
+        onReset?: FormEmits["reset"] | undefined;
+        onSubmit?: FormEmits["submit"] | undefined;
+        labelWrap?: boolean | undefined;
         feedbackIcons?: FeedbackIcons | undefined;
-        size?: ButtonSize;
         scrollToFirstError?: (ScrollFocusOptions | boolean) | undefined;
-        variant?: Variant | undefined;
         validateMessages?: ValidateMessages | undefined;
         preserve?: boolean | undefined;
         clearOnDestroy?: boolean | undefined;
         validateOnRuleChange?: boolean | undefined;
-        autoComplete?: string | undefined | undefined;
         onFinish?: FormEmits["finish"] | undefined;
         onFinishFailed?: FormEmits["finishFailed"] | undefined;
         onValidate?: FormEmits["validate"] | undefined;
@@ -740,28 +1028,23 @@ export declare const ProForm: SFCWithInstall<(<F extends Form<any> = Form>(__VLS
     __ctx?: Awaited<typeof __VLS_setup>;
 })>;
 
-export declare type ProFormInstance = ComponentExposed<typeof BaseForm>;
+export declare type ProFormInstance = ComponentExposed<typeof _default_3>;
 
-export declare type ProFormItemInstance = ComponentExposed<typeof BaseFormItem>;
+export declare type ProFormItemInstance = ComponentExposed<typeof _default_4>;
 
-export declare type ProFormItemProps = ComponentProps<typeof BaseFormItem>;
+export declare type ProFormItemProps = ComponentProps<typeof _default_4>;
 
-export declare type ProFormProps = ComponentProps<typeof BaseForm>;
+export declare type ProFormProps = ComponentProps<typeof _default_3>;
 
 declare type Props = {
-    component?: string | Component;
-    path?: string;
-};
-
-declare type Props_2 = {
     component?: ContainerComponent;
 };
 
-declare type Props_3 = {
+declare type Props_2 = {
     component?: SlotComponentType;
 };
 
-declare type Props_4 = {
+declare type Props_3 = {
     grid?: Grid;
     fields?: Fields;
     disabled?: boolean;
@@ -777,9 +1060,9 @@ export declare type ProTableProps = ComponentProps<typeof _default_2>;
  * @description 自定义组件
  * @example (p, ctx) => h('div', ctx.attrs)
  */
-export declare type RenderComponentType = Component<VModelProps & PathProps>;
+declare type RenderComponentType = Component<VModelProps & PathProps>;
 
-export declare type RequiredComponentVars = {
+declare type RequiredComponentVars = {
     'pro-table': PP<TableProps & Pick<ProTableProps, 'control' | 'searchFormConfig' | 'immediateSearch' | 'addIndexColumn' | 'tableContainer'>>;
     'pro-form': PP<Omit<ProFormProps, 'form' | 'grid'> & {
         grid: Exclude<Grid, undefined | boolean>;
@@ -811,41 +1094,105 @@ declare type SetPageParam = (pageParam: Partial<PageParam> | ((pre: Readonly<Pag
 
 declare type SFCWithInstall<T> = T & Plugin_2;
 
-export declare const SlotComponent: DefineComponent<Props_3, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props_3> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+export declare const SlotComponent: DefineComponent<Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props_2> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 /**
  * @description 插槽组件类型
  */
-export declare type SlotComponentType = Component<PathProps> | VNode | string | number | boolean | null | undefined | ((...args: any[]) => SlotComponentType);
+declare type SlotComponentType = Component<PathProps> | VNode | string | number | boolean | null | undefined | ((...args: any[]) => SlotComponentType);
 
 /**
  * @description 插槽对象类型
  */
-export declare type Slots = {
+declare type Slots = {
     [name: string]: SlotComponentType;
 };
 
 /**
- * 重新定义 Table 类型，将 Column 类型绑定为 antdv-next 的 Column<T>
+ * @qin-ui/antdv-next-pro 的表格实例类型
+ *
+ * @description 在 core Table 类型的基础上，将列类型 C 绑定为本地 Column<T>，
+ * 使 columns 操作获得 antdv-next 表格列的完整属性类型提示。
+ *
+ * @template D - 搜索表单数据类型
+ * @template T - 表格行数据类型
+
+ * @public
  */
 export declare type Table<D extends Data = Data, T extends Data = ExtendWithAny<D>> = Table_2<D, T, Column<T>>;
 
+/**
+ * 表格实例类型
+ * @template D - 搜索表单数据类型
+ * @template T - 表格数据类型（表格行数据类型），默认为 ExtendWithAny<D>
+ * @template C - 列配置类型，继承自 BaseColumn<T>
+ *
+ * 组合了列操作、数据源管理、分页管理和搜索表单的能力。
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number; }
+ * interface SearchParams { keyword: string }
+ *
+ * const table: Table<SearchParams, User> = useTable({
+ *   columns: [
+ *     { key: 'name', title: '姓名' },
+ *     { key: 'age', title: '年龄' },
+ *   ],
+ *   dataSource: [
+ *     { name: '张三', age: 25 },
+ *   ],
+ *   searchFields: [
+ *     { path: 'keyword', label: '关键词', component: 'input' },
+ *   ],
+ * })
+ *
+ * // 列操作
+ * table.setColumn('name', { title: '用户名' })
+ * table.appendColumn('name', { key: 'email', title: '邮箱' })
+ * table.deleteColumn('age')
+ *
+ * // 分页操作
+ * table.setPageParam({ current: 2, pageSize: 20 })
+ * table.resetQueryParams()
+ *
+ * // 搜索表单
+ * table.searchForm.getFormData('keyword')
+ * table.searchForm.setFormData('keyword', '张三')
+ * ```
+ */
 declare type Table_2<D extends Data = Data, T extends Data = ExtendWithAny<D>, C extends BaseColumn<T> = BaseColumn<T>> = {
+    /** 列配置数组（响应式） */
     columns: Ref<Columns_2<T, C>>;
+    /** 数据源数组（响应式） */
     dataSource: Ref<T[]>;
+    /** 分页参数（响应式） */
     pageParam: Reactive<PageParam>;
+    /** 搜索表单实例 */
     searchForm: Form_2<D>;
+    /** 设置列配置 */
     setColumn: SetColumn<T, C>;
+    /** 删除列 */
     deleteColumn: (path: Path<T> | ColumnFindBy<T, C>, options?: UpdateColumnOptions) => void;
+    /** 在指定列后追加列 */
     appendColumn: (path: Path<T> | ColumnFindBy<T, C> | undefined, column: C | Columns_2<T, C>, options?: UpdateColumnOptions) => void;
+    /** 在指定列前插入列 */
     prependColumn: (path: Path<T> | ColumnFindBy<T, C> | undefined, column: C | Columns_2<T, C>, options?: UpdateColumnOptions) => void;
+    /** 设置分页参数 */
     setPageParam: SetPageParam;
+    /** 重置查询参数（重置分页和搜索条件到初始值） */
     resetQueryParams: () => void;
 };
 
-export declare const TeleportComponentNamePrefix = "TeleportComponent_";
-
+/**
+ * 列更新选项
+ */
 declare type UpdateColumnOptions = {
+    /**
+     * @description 是否更新所有匹配的列
+     * - true: 更新所有匹配的列
+     * - false/undefined: 只更新第一个匹配的列
+     */
     all?: boolean;
 };
 
@@ -853,19 +1200,96 @@ declare type UpdateFieldOptions = {
     all?: boolean;
 };
 
-/** useFields 返回值类型，固定为本地 Fields<D> */
+/** useFields 返回值类型，固定为本地 Fields<D>
+ * @public
+ */
 export declare type UseFields<D extends Data = Data> = ReturnType<typeof useFields<D>>;
 
 /**
- * 类型断言 re-export @qin-ui/core 的 useFields，
- * 将泛型参数 F 的默认值覆盖为本地的 Field<D>，
- * 使得 fields、getField 等方法的类型推断包含 UI 库的完整属性签名。
+ * @qin-ui/antdv-next-pro 的字段配置管理 Hook
+ *
+ * @description 类型安全的 re-export。将 core useFields 的泛型参数绑定为本地类型：
+ * - 字段类型 F → Field<ComponentName, D>（支持 antdv-next 组件类型推导）
+ * - FormItem 实例 → antdv-next 的 FormItemInstance
+ *
+ * @template D - 表单数据类型
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number }
+ *
+ * const { fields, getField, setField } = useFields<User>([
+ *   { path: 'name', label: '姓名', component: 'input' },
+ *   { path: 'age', label: '年龄', component: 'input-number' },
+ * ])
+ * ```
+
+ * @public
  */
 export declare const useFields: {
     <D extends Data = Data>(initFields?: Fields<D>): ReturnType<typeof useFields_2<D, Field<ComponentName, D>, FormItemInstance>>;
 };
 
-declare const useFields_2: <D extends Data = Data, F extends BaseField_2<D> = BaseField_2<D>, FormInstance = any>(initFields?: F[]) => {
+/**
+ * 字段配置管理 Hook
+ *
+ * @description 提供对字段配置数组的增删改查操作，支持：
+ * - 通过路径字符串或查找函数定位字段
+ * - 深层嵌套字段的遍历和匹配
+ * - 字段配置的合并/覆盖更新
+ * - 字段的添加、插入、删除
+ * - 父级字段查找
+ *
+ * @template D - 表单数据类型，用于路径类型推导
+ * @template F - 字段配置类型，继承自 BaseField<D>
+ * @template FormInstance - 底层 FormItem 组件实例类型
+ *
+ * @param {F[]} [initFields] - 初始字段配置数组
+ *
+ * @returns {object} 字段操作对象
+ * @returns {Ref<F[]>} .fields - 字段配置数组（响应式）
+ * @returns {Function} .getField(path) - 获取字段配置
+ * @returns {Function} .setField(path, field) - 更新字段配置
+ * @returns {Function} .deleteField(path) - 删除字段
+ * @returns {Function} .appendField(path, field) - 在指定字段后追加
+ * @returns {Function} .prependField(path, field) - 在指定字段前插入
+ * @returns {Function} .getParentField(path) - 获取父级字段
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number; address: { city: string } }
+ *
+ * const { fields, getField, setField, deleteField } = useFields<User>([
+ *   { path: 'name', label: '姓名', component: 'input' },
+ *   { path: 'age', label: '年龄', component: 'input-number' },
+ *   {
+ *     path: 'address',
+ *     label: '地址',
+ *     fields: [
+ *       { path: 'city', label: '城市' },
+ *     ],
+ *   },
+ * ])
+ *
+ * // 通过路径获取字段
+ * getField('name') // { path: 'name', label: '姓名', ... }
+ * getField('address.city') // { path: 'city', label: '城市', ... }
+ *
+ * // 通过查找函数获取字段
+ * getField(f => f.label === '姓名')
+ *
+ * // 更新字段（合并模式）
+ * setField('name', { label: '用户名' })
+ *
+ * // 删除字段
+ * deleteField('age')
+ *
+ * // 追加/插入字段
+ * appendField('name', { path: 'email', label: '邮箱', component: 'input' })
+ * prependField('name', { path: 'id', label: 'ID', component: 'input' })
+ * ```
+ */
+declare const useFields_2: <D extends Data = Data, F extends BaseField<D> = BaseField<D>, FormInstance = any>(initFields?: F[]) => {
     fields: Ref<F[], F[]>;
     getField: {
         (path: Path<D> | FieldFindBy<D, F>): Readonly<F & AdditionalMethods<FormInstance>> | undefined;
@@ -894,8 +1318,29 @@ declare const useFields_2: <D extends Data = Data, F extends BaseField_2<D> = Ba
 };
 
 /**
- * 类型断言 re-export @qin-ui/core 的 useForm，
- * 将默认返回的 Form<D, BaseField<D>> 覆盖为本地的 Form<D, Field<ComponentName, D>>。
+ * 创建 @qin-ui/antdv-next-pro 表单实例的 Hook
+ *
+ * @description 类型安全的 re-export。将 core useForm 的泛型参数绑定为本地类型：
+ * - 字段类型 F → Field<ComponentName, D>（支持 antdv-next 组件类型推导）
+ * - 表单实例 → antdv-next 的 FormInstance
+ *
+ * @template D - 表单数据类型
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number }
+ *
+ * const form = useForm<User>(
+ *   { name: '张三', age: 25 },
+ *   [
+ *     { path: 'name', label: '姓名', component: 'input' },
+ *     { path: 'age', label: '年龄', component: 'input-number' },
+ *   ],
+ *   true
+ * )
+ * ```
+
+ * @public
  */
 export declare const useForm: {
     <D extends Data = Data>(initFormData?: ExtendWithAny<DeepPartial<D>>, initFields?: Field<ComponentName, D>[], root?: boolean): Form<D, Field<ComponentName, D>>;
@@ -903,9 +1348,43 @@ export declare const useForm: {
 };
 
 /**
- * 表单数据处理hook
- * @param initFormData 初始表单数据
- * @returns {Object} { formData, getFormData, setFormData }
+ * 表单数据处理 Hook
+ *
+ * @description 提供响应式表单数据的管理能力，支持：
+ * - 响应式数据存储（基于 Vue reactive）
+ * - 深层路径读写（支持点号分隔，如 'address.city'）
+ * - 类型安全的路径提示（传入泛型 D 后，path 参数可获得类型推导）
+ * - 父子表单自动注入（非根表单会从注入中获取数据）
+ * @public
+ *
+ * @template D - 表单数据类型，应为一个对象类型
+ * @param {ExtendWithAny<DeepPartial<D>>} [initFormData] - 初始表单数据
+ *
+ * @returns {object} 表单数据操作对象
+ * @returns {D & Record<string, any>} .formData - 响应式表单数据
+ * @returns {Function} .getFormData(path) - 获取指定路径的数据
+ * @returns {Function} .setFormData(path, value) - 设置指定路径的数据
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number; address: { city: string } }
+ *
+ * const { formData, getFormData, setFormData } = useFormData<User>({
+ *   name: '张三',
+ *   address: { city: '北京' }
+ * })
+ *
+ * // 读取
+ * getFormData('name')           // '张三'
+ * getFormData('address.city')   // '北京'
+ * formData.name                 // '张三'（响应式）
+ *
+ * // 设置
+ * setFormData('name', '李四')
+ * setFormData('address.city', '上海')
+ * setFormData({ name: '王五', age: 30 }) // 批量覆盖
+ * setFormData(prev => ({ ...prev, name: '赵六' })) // 函数式更新
+ * ```
  */
 export declare const useFormData: <D extends Data = Data>(initFormData?: ExtendWithAny<DeepPartial<D>>) => {
     formData: Reactive<ExtendWithAny<D>>;
@@ -924,20 +1403,76 @@ export declare const useFormData: <D extends Data = Data>(initFormData?: ExtendW
 };
 
 /**
- * 类型断言 re-export @qin-ui/core 的 useFormRef，
- * 将 FormInstance 泛型参数绑定为本地 UI 库（antdv-next）的 FormInstance。
+ * @qin-ui/antdv-next-pro 的表单组件实例引用 Hook
+ *
+ * @description 类型安全的 re-export。将 core useFormRef 的泛型参数绑定为 antdv-next 的 FormInstance，
+ * 使 formRef 获取到完整的 antdv-next Form 组件 API 类型提示。
+ *
+ * @returns {object} 表单组件实例引用管理对象
+ * @returns {Ref<FormInstance | undefined>} .formRef - antdv-next Form 实例的响应式引用
+ * @returns {Function} .setFormRef(inst) - 设置表单组件实例
+ *
+ * @example
+ * ```ts
+ * const { formRef, setFormRef } = useFormRef()
+ * await formRef.value?.validate()
+ * formRef.value?.resetFields()
+ * ```
+
+ * @public
  */
 export declare const useFormRef: {
     (): ReturnType<typeof useFormRef_2<FormInstance>>;
 };
 
+/**
+ * 表单组件实例引用 Hook
+ *
+ * @description 用于获取和设置底层 UI 框架（如 ant-design-vue、element-plus）的 Form 组件实例。
+ * 在 ProForm 组件内部自动调用 setFormRef 绑定实例，外部可通过 formRef 访问。
+ *
+ * @template F - 底层 Form 组件实例类型，默认为 any
+ *
+ * @returns {object} 表单组件实例引用管理对象
+ * @returns {Ref<F | undefined>} .formRef - 表单组件实例的响应式引用
+ * @returns {Function} .setFormRef(inst) - 设置表单组件实例
+ *
+ * @example
+ * ```ts
+ * const { formRef, setFormRef } = useFormRef<InstanceType<typeof AForm>>()
+ * setFormRef(formComponentInstance)
+ * console.log(formRef.value) // 可通过 formRef 访问底层 Form 实例的方法
+ * ```
+ */
 declare const useFormRef_2: <F = any>() => {
     formRef: Ref<F | undefined, F | undefined>;
     setFormRef: (inst: F) => void;
 };
 
 /**
- * 类型断言 re-export @qin-ui/core 的 useTable，
+ * 创建 @qin-ui/antdv-next-pro 表格实例的 Hook
+ *
+ * @description 类型安全的 re-export。将 core useTable 的列类型绑定为本地 Column<T>，
+ * 使 columns 操作获得 antdv-next 表格列的完整类型提示。
+ *
+ * @template D - 搜索表单数据类型
+ * @template T - 表格行数据类型
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number; email: string }
+ *
+ * const table = useTable<User>({
+ *   columns: [
+ *     { dataIndex: 'name', title: '姓名', width: 120 },
+ *     { dataIndex: 'age', title: '年龄', width: 80 },
+ *   ],
+ *   dataSource: [],
+ *   pageParam: { current: 1, pageSize: 20, total: 0 },
+ * })
+ * ```
+
+ * @public
  */
 export declare const useTable: <D extends Data = Data, T extends Data = ExtendWithAny<D>>(params: {
     columns?: Columns<T>;
@@ -947,14 +1482,14 @@ export declare const useTable: <D extends Data = Data, T extends Data = ExtendWi
     searchFields?: Fields<D>;
 }) => Table<D, T>;
 
-export declare type ValueFormatter = {
+declare type ValueFormatter = {
     (val: any, oldVal: any): any;
 } | {
     get?: (val: any) => any;
     set?: (val: any, oldVal: any) => any;
 };
 
-export declare type VModelProps<T = any> = {
+declare type VModelProps<T = any> = {
     value?: T;
     'onUpdate:value'?: (val: T) => void;
 };
@@ -978,7 +1513,7 @@ declare type WithFields<D extends Data = Data> = WithRef<WithCommonBase & BaseWi
  * @description 为对象属性添加响应式支持的类型
  * @template T - 原始类型
  */
-export declare type WithRef<T> = {
+declare type WithRef<T> = {
     [P in keyof T]: P extends NotSupportedRefOrGetterProps ? T[P] : T[P] extends (...args: any[]) => any ? T[P] : MaybeRefOrComputedRef<T[P]>;
 };