@qin-ui/vant-pro 1.0.2 → 1.0.3

package/es/index.d.ts

@@ -1,54 +1,33 @@
 import { AllowedComponentProps } from 'vue';
 import { App } from 'vue';
 import { Area } from 'vant';
-import { Attrs } from 'vue';
 import { Button } from 'vant';
 import { Cascader } from 'vant';
-import { CellArrowDirection } from 'vant';
-import { CellSize } from 'vant';
 import { CheckboxGroup } from 'vant';
 import { Component } from 'vue';
-import { ComponentCustomProperties } from 'vue';
 import { ComponentCustomProps } from 'vue';
 import { ComponentExposed } from 'vue-component-type-helpers';
-import { ComponentInternalInstance } from 'vue';
 import { ComponentOptionsBase } from 'vue';
 import { ComponentOptionsMixin } from 'vue';
 import { ComponentProps } from 'vue-component-type-helpers';
 import { ComponentProvideOptions } from 'vue';
-import { ComponentPublicInstance } from 'vue';
 import { ComponentSlots } from 'vue-component-type-helpers';
 import { ComputedRef } from 'vue';
 import { CreateComponentPublicInstanceWithMixins } from 'vue';
 import { CSSProperties } from 'vue';
 import { DatePicker } from 'vant';
-import { DebuggerEvent } from 'vue';
 import { DefineComponent } from 'vue';
-import { ExtractPropTypes } from 'vue';
 import { Field as Field_2 } from 'vant';
-import { FieldAutosizeConfig } from 'vant';
-import { FieldClearTrigger } from 'vant';
-import { FieldEnterKeyHint } from 'vant';
-import { FieldFormatTrigger } from 'vant';
 import { FieldInstance } from 'vant';
 import { FieldProps } from 'vant';
-import { FieldRule } from 'vant';
-import { FieldTextAlign } from 'vant';
-import { FieldType } from 'vant';
 import { FormInstance } from 'vant';
 import { FormProps } from 'vant';
 import { GlobalComponents } from 'vue';
 import { GlobalDirectives } from 'vue';
-import { HTMLAttributes } from 'vue';
-import { InjectionKey } from 'vue';
-import { JSX } from 'vue/jsx-runtime';
 import { MaybeRef } from 'vue';
-import { nextTick } from 'vue';
-import { OnCleanup } from '@vue/reactivity';
 import { Picker } from 'vant';
 import { Plugin as Plugin_2 } from 'vue';
 import { Popup } from 'vant';
-import { PropType } from 'vue';
 import { PublicProps } from 'vue';
 import { RadioGroup } from 'vant';
 import { Rate } from 'vant';
@@ -66,23 +45,13 @@ import { Uploader } from 'vant';
 import { VNode } from 'vue';
 import { VNodeProps } from 'vue';
 import { VNodeTypes } from 'vue';
-import { WatchOptions } from 'vue';
-import { WatchStopHandle } 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_2: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
-
-declare const __VLS_component_3: DefineComponent<Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props_4> & 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];
 } & {};
 
-declare type __VLS_Props = {
-    path?: string | number | (string | number)[];
-};
-
 declare function __VLS_template(): {
     attrs: Partial<{}>;
     slots: {
@@ -93,59 +62,25 @@ declare function __VLS_template(): {
     rootEl: any;
 };
 
-declare function __VLS_template_2(): {
-    attrs: Partial<{}>;
-    slots: {
-        default?(_: {
-            path: string | undefined;
-        }): any;
-    };
-    refs: {};
-    rootEl: any;
-};
-
-declare function __VLS_template_3(): {
-    attrs: Partial<{}>;
-    slots: {
-        default?(_: {
-            componentProps: Record<string, any>;
-        }): any;
-    };
-    refs: {};
-    rootEl: any;
-};
-
 declare type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
 
-declare type __VLS_TemplateResult_2 = ReturnType<typeof __VLS_template_2>;
-
-declare type __VLS_TemplateResult_3 = ReturnType<typeof __VLS_template_3>;
-
 declare type __VLS_WithTemplateSlots<T, S> = T & {
     new (): {
         $slots: S;
     };
 };
 
-declare type __VLS_WithTemplateSlots_2<T, S> = T & {
-    new (): {
-        $slots: S;
-    };
-};
-
-declare type __VLS_WithTemplateSlots_3<T, S> = T & {
-    new (): {
-        $slots: S;
-    };
-};
-
+/**
+ * FormItem 实例提供的额外方法
+ * @template FormItemInstance - FormItem 组件实例类型
+ */
 declare type AdditionalMethods<FormItemInstance> = {
     /**
-     * @description 获取FormItem实例的方法
+     * @description 获取 FormItem 实例的方法
      */
     getFormItemRef?: () => FormItemInstance;
     /**
-     * @description 获取传入FormItem组件的属性
+     * @description 获取传入 FormItem 组件的属性
      */
     getFormItemComputedProps?: () => Readonly<{
         [x: string]: any;
@@ -155,7 +90,7 @@ declare type AdditionalMethods<FormItemInstance> = {
      */
     getComponentRef?: () => any;
     /**
-     * @description 获取传入Component组件的属性
+     * @description 获取传入 Component 组件的属性
      */
     getComponentComputedProps?: () => Readonly<{
         disabled?: boolean;
@@ -167,7 +102,7 @@ declare type AllowStringKey<T, Prefix extends string = ''> = {
     [K in keyof T as string extends K ? never : number extends K ? never : K extends string ? K : never]: T[K] extends (infer U)[] ? `${Prefix}${K & string}` | (IsRecord<U> extends true ? AllowStringKey<U, `${Prefix}${K & string}[index].`> : never) : IsRecord<T[K]> extends true ? `${Prefix}${K & string}` | AllowStringKey<T[K], `${Prefix}${K & string}.`> : `${Prefix}${K & string}`;
 } extends infer Obj ? Obj[keyof Obj] : never;
 
-export declare type Base<D extends Data = Data> = BaseWithFields<D> | BaseWithoutFields<D>;
+declare type Base<D extends Data = Data> = BaseWithFields<D> | BaseWithoutFields<D>;
 
 declare type BaseCommon<D extends Data = Data> = {
     /**
@@ -200,7 +135,11 @@ declare type BaseCommon<D extends Data = Data> = {
     extraProps?: Record<string, any>;
 };
 
-export declare type BaseComponentMap = {
+/**
+ * 内置组件映射表
+ * @description Vant 内置支持的组件类型映射
+ */
+declare type BaseComponentMap = {
     field: typeof Field_2;
     switch: typeof Switch;
     stepper: typeof Stepper;
@@ -218,430 +157,49 @@ export declare type BaseComponentMap = {
     button: typeof Button;
 };
 
-export declare const BaseField: DefineComponent<Props, {
-getComponentRef: () => any;
-getComponentComputedProps: () => any;
-}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
-fieldRef: ({
-$: ComponentInternalInstance;
-$data: {};
-$props: Partial<{
-type: FieldType;
-tag: keyof HTMLElementTagNameMap;
-center: boolean;
-autofocus: boolean;
-disabled: boolean;
-border: boolean;
-isLink: boolean;
-required: boolean | "auto";
-clickable: boolean | null;
-clearable: boolean;
-clearIcon: string;
-modelValue: string | number;
-clearTrigger: FieldClearTrigger;
-formatTrigger: FieldFormatTrigger;
-spellcheck: boolean;
-error: boolean;
-readonly: boolean;
-showWordLimit: boolean;
-colon: boolean;
-}> & Omit<{
-readonly tag: keyof HTMLElementTagNameMap;
-readonly center: boolean;
-readonly isLink: boolean;
-readonly border: boolean;
-readonly required: boolean | "auto";
-readonly clickable: boolean | null;
-readonly autofocus: boolean;
-readonly clearable: boolean;
-readonly clearIcon: string;
-readonly modelValue: string | number;
-readonly clearTrigger: FieldClearTrigger;
-readonly formatTrigger: FieldFormatTrigger;
-readonly spellcheck: boolean;
-readonly error: boolean;
-readonly disabled: boolean;
-readonly readonly: boolean;
-readonly type: FieldType;
-readonly showWordLimit: boolean;
-readonly colon: boolean;
-readonly icon?: string | undefined;
-readonly size?: CellSize | undefined;
-readonly title?: string | number | undefined;
-readonly value?: string | number | undefined;
-readonly label?: string | number | undefined;
-readonly iconPrefix?: string | undefined;
-readonly valueClass?: unknown;
-readonly labelClass?: unknown;
-readonly titleClass?: unknown;
-readonly titleStyle?: string | CSSProperties | undefined;
-readonly arrowDirection?: CellArrowDirection | undefined;
-readonly id?: string | undefined;
-readonly name?: string | undefined;
-readonly leftIcon?: string | undefined;
-readonly rightIcon?: string | undefined;
-readonly maxlength?: string | number | undefined;
-readonly max?: number | undefined;
-readonly min?: number | undefined;
-readonly formatter?: ((value: string) => string) | undefined;
-readonly inputAlign?: FieldTextAlign | undefined;
-readonly placeholder?: string | undefined;
-readonly autocomplete?: string | undefined;
-readonly autocapitalize?: string | undefined;
-readonly autocorrect?: string | undefined;
-readonly errorMessage?: string | undefined;
-readonly enterkeyhint?: FieldEnterKeyHint | undefined;
-readonly inputmode?: "search" | "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | undefined;
-readonly rows?: string | number | undefined;
-readonly rules?: FieldRule[] | undefined;
-readonly autosize?: boolean | FieldAutosizeConfig | undefined;
-readonly labelWidth?: string | number | undefined;
-readonly labelAlign?: FieldTextAlign | undefined;
-readonly errorMessageAlign?: FieldTextAlign | undefined;
-readonly onFocus?: ((...args: any[]) => any) | undefined | undefined;
-readonly onBlur?: ((...args: any[]) => any) | undefined | undefined;
-readonly onKeypress?: ((...args: any[]) => any) | undefined | undefined;
-readonly onClear?: ((...args: any[]) => any) | undefined | undefined;
-readonly onClickInput?: ((...args: any[]) => any) | undefined | undefined;
-readonly onEndValidate?: ((...args: any[]) => any) | undefined | undefined;
-readonly onStartValidate?: ((...args: any[]) => any) | undefined | undefined;
-readonly onClickLeftIcon?: ((...args: any[]) => any) | undefined | undefined;
-readonly onClickRightIcon?: ((...args: any[]) => any) | undefined | undefined;
-readonly "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined | undefined;
-} & VNodeProps & AllowedComponentProps & ComponentCustomProps, "tag" | "center" | "isLink" | "border" | "required" | "clickable" | "autofocus" | "clearable" | "clearIcon" | "modelValue" | "clearTrigger" | "formatTrigger" | "spellcheck" | "error" | "disabled" | "readonly" | "type" | "showWordLimit" | "colon">;
-$attrs: Attrs;
-$refs: {
-[x: string]: unknown;
-};
-$slots: Readonly<{
-[name: string]: Slot<any> | undefined;
-}>;
-$root: ComponentPublicInstance | null;
-$parent: ComponentPublicInstance | null;
-$host: Element | null;
-$emit: (event: "focus" | "clear" | "blur" | "keypress" | "clickInput" | "endValidate" | "startValidate" | "clickLeftIcon" | "clickRightIcon" | "update:modelValue", ...args: any[]) => void;
-$el: any;
-$options: ComponentOptionsBase<Readonly<ExtractPropTypes<    {
-tag: {
-type: PropType<keyof HTMLElementTagNameMap>;
-default: keyof HTMLElementTagNameMap;
-};
-icon: StringConstructor;
-size: PropType<CellSize>;
-title: (NumberConstructor | StringConstructor)[];
-value: (NumberConstructor | StringConstructor)[];
-label: (NumberConstructor | StringConstructor)[];
-center: BooleanConstructor;
-isLink: BooleanConstructor;
-border: {
-type: BooleanConstructor;
-default: true;
-};
-iconPrefix: StringConstructor;
-valueClass: PropType<unknown>;
-labelClass: PropType<unknown>;
-titleClass: PropType<unknown>;
-titleStyle: PropType<string | CSSProperties>;
-arrowDirection: PropType<CellArrowDirection>;
-required: {
-type: PropType<boolean | "auto">;
-default: null;
-};
-clickable: {
-type: PropType<boolean | null>;
-default: null;
-};
-} & {
-id: StringConstructor;
-name: StringConstructor;
-leftIcon: StringConstructor;
-rightIcon: StringConstructor;
-autofocus: BooleanConstructor;
-clearable: BooleanConstructor;
-maxlength: (NumberConstructor | StringConstructor)[];
-max: NumberConstructor;
-min: NumberConstructor;
-formatter: PropType<(value: string) => string>;
-clearIcon: {
-type: PropType<string>;
-default: string;
-};
-modelValue: {
-type: (NumberConstructor | StringConstructor)[];
-default: string;
-};
-inputAlign: PropType<FieldTextAlign>;
-placeholder: StringConstructor;
-autocomplete: StringConstructor;
-autocapitalize: StringConstructor;
-autocorrect: StringConstructor;
-errorMessage: StringConstructor;
-enterkeyhint: PropType<FieldEnterKeyHint>;
-clearTrigger: {
-type: PropType<FieldClearTrigger>;
-default: FieldClearTrigger;
-};
-formatTrigger: {
-type: PropType<FieldFormatTrigger>;
-default: FieldFormatTrigger;
-};
-spellcheck: {
-type: BooleanConstructor;
-default: null;
-};
-error: {
-type: BooleanConstructor;
-default: null;
-};
-disabled: {
-type: BooleanConstructor;
-default: null;
-};
-readonly: {
-type: BooleanConstructor;
-default: null;
-};
-inputmode: PropType<HTMLAttributes["inputmode"]>;
-} & {
-rows: (NumberConstructor | StringConstructor)[];
-type: {
-type: PropType<FieldType>;
-default: FieldType;
-};
-rules: PropType<FieldRule[]>;
-autosize: PropType<boolean | FieldAutosizeConfig>;
-labelWidth: (NumberConstructor | StringConstructor)[];
-labelClass: PropType<unknown>;
-labelAlign: PropType<FieldTextAlign>;
-showWordLimit: BooleanConstructor;
-errorMessageAlign: PropType<FieldTextAlign>;
-colon: {
-type: BooleanConstructor;
-default: null;
-};
-}>> & Readonly<{
-onFocus?: ((...args: any[]) => any) | undefined;
-onBlur?: ((...args: any[]) => any) | undefined;
-onKeypress?: ((...args: any[]) => any) | undefined;
-onClear?: ((...args: any[]) => any) | undefined;
-onClickInput?: ((...args: any[]) => any) | undefined;
-onEndValidate?: ((...args: any[]) => any) | undefined;
-onStartValidate?: ((...args: any[]) => any) | undefined;
-onClickLeftIcon?: ((...args: any[]) => any) | undefined;
-onClickRightIcon?: ((...args: any[]) => any) | undefined;
-"onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
-}>, () => JSX.Element, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, ("focus" | "clear" | "blur" | "keypress" | "clickInput" | "endValidate" | "startValidate" | "clickLeftIcon" | "clickRightIcon" | "update:modelValue")[], string, {
-type: FieldType;
-tag: keyof HTMLElementTagNameMap;
-center: boolean;
-autofocus: boolean;
-disabled: boolean;
-border: boolean;
-isLink: boolean;
-required: boolean | "auto";
-clickable: boolean | null;
-clearable: boolean;
-clearIcon: string;
-modelValue: string | number;
-clearTrigger: FieldClearTrigger;
-formatTrigger: FieldFormatTrigger;
-spellcheck: boolean;
-error: boolean;
-readonly: boolean;
-showWordLimit: boolean;
-colon: boolean;
-}, {}, string, {}, GlobalComponents, GlobalDirectives, string, ComponentProvideOptions> & {
-beforeCreate?: (() => void) | (() => void)[];
-created?: (() => void) | (() => void)[];
-beforeMount?: (() => void) | (() => void)[];
-mounted?: (() => void) | (() => void)[];
-beforeUpdate?: (() => void) | (() => void)[];
-updated?: (() => void) | (() => void)[];
-activated?: (() => void) | (() => void)[];
-deactivated?: (() => void) | (() => void)[];
-beforeDestroy?: (() => void) | (() => void)[];
-beforeUnmount?: (() => void) | (() => void)[];
-destroyed?: (() => void) | (() => void)[];
-unmounted?: (() => void) | (() => void)[];
-renderTracked?: ((e: DebuggerEvent) => void) | ((e: DebuggerEvent) => void)[];
-renderTriggered?: ((e: DebuggerEvent) => void) | ((e: DebuggerEvent) => void)[];
-errorCaptured?: ((err: unknown, instance: ComponentPublicInstance | null, info: string) => boolean | void) | ((err: unknown, instance: ComponentPublicInstance | null, info: string) => boolean | void)[];
-};
-$forceUpdate: () => void;
-$nextTick: nextTick;
-$watch<T extends string | ((...args: any) => any)>(source: T, cb: T extends (...args: any) => infer R ? (...args: [R, R, OnCleanup]) => any : (...args: [any, any, OnCleanup]) => any, options?: WatchOptions): WatchStopHandle;
-} & Readonly<{
-type: FieldType;
-tag: keyof HTMLElementTagNameMap;
-center: boolean;
-autofocus: boolean;
-disabled: boolean;
-border: boolean;
-isLink: boolean;
-required: boolean | "auto";
-clickable: boolean | null;
-clearable: boolean;
-clearIcon: string;
-modelValue: string | number;
-clearTrigger: FieldClearTrigger;
-formatTrigger: FieldFormatTrigger;
-spellcheck: boolean;
-error: boolean;
-readonly: boolean;
-showWordLimit: boolean;
-colon: boolean;
-}> & Omit<Readonly<ExtractPropTypes<    {
-tag: {
-type: PropType<keyof HTMLElementTagNameMap>;
-default: keyof HTMLElementTagNameMap;
-};
-icon: StringConstructor;
-size: PropType<CellSize>;
-title: (NumberConstructor | StringConstructor)[];
-value: (NumberConstructor | StringConstructor)[];
-label: (NumberConstructor | StringConstructor)[];
-center: BooleanConstructor;
-isLink: BooleanConstructor;
-border: {
-type: BooleanConstructor;
-default: true;
-};
-iconPrefix: StringConstructor;
-valueClass: PropType<unknown>;
-labelClass: PropType<unknown>;
-titleClass: PropType<unknown>;
-titleStyle: PropType<string | CSSProperties>;
-arrowDirection: PropType<CellArrowDirection>;
-required: {
-type: PropType<boolean | "auto">;
-default: null;
-};
-clickable: {
-type: PropType<boolean | null>;
-default: null;
-};
-} & {
-id: StringConstructor;
-name: StringConstructor;
-leftIcon: StringConstructor;
-rightIcon: StringConstructor;
-autofocus: BooleanConstructor;
-clearable: BooleanConstructor;
-maxlength: (NumberConstructor | StringConstructor)[];
-max: NumberConstructor;
-min: NumberConstructor;
-formatter: PropType<(value: string) => string>;
-clearIcon: {
-type: PropType<string>;
-default: string;
-};
-modelValue: {
-type: (NumberConstructor | StringConstructor)[];
-default: string;
-};
-inputAlign: PropType<FieldTextAlign>;
-placeholder: StringConstructor;
-autocomplete: StringConstructor;
-autocapitalize: StringConstructor;
-autocorrect: StringConstructor;
-errorMessage: StringConstructor;
-enterkeyhint: PropType<FieldEnterKeyHint>;
-clearTrigger: {
-type: PropType<FieldClearTrigger>;
-default: FieldClearTrigger;
-};
-formatTrigger: {
-type: PropType<FieldFormatTrigger>;
-default: FieldFormatTrigger;
-};
-spellcheck: {
-type: BooleanConstructor;
-default: null;
-};
-error: {
-type: BooleanConstructor;
-default: null;
-};
-disabled: {
-type: BooleanConstructor;
-default: null;
-};
-readonly: {
-type: BooleanConstructor;
-default: null;
-};
-inputmode: PropType<HTMLAttributes["inputmode"]>;
-} & {
-rows: (NumberConstructor | StringConstructor)[];
-type: {
-type: PropType<FieldType>;
-default: FieldType;
-};
-rules: PropType<FieldRule[]>;
-autosize: PropType<boolean | FieldAutosizeConfig>;
-labelWidth: (NumberConstructor | StringConstructor)[];
-labelClass: PropType<unknown>;
-labelAlign: PropType<FieldTextAlign>;
-showWordLimit: BooleanConstructor;
-errorMessageAlign: PropType<FieldTextAlign>;
-colon: {
-type: BooleanConstructor;
-default: null;
-};
-}>> & Readonly<{
-onFocus?: ((...args: any[]) => any) | undefined;
-onBlur?: ((...args: any[]) => any) | undefined;
-onKeypress?: ((...args: any[]) => any) | undefined;
-onClear?: ((...args: any[]) => any) | undefined;
-onClickInput?: ((...args: any[]) => any) | undefined;
-onEndValidate?: ((...args: any[]) => any) | undefined;
-onStartValidate?: ((...args: any[]) => any) | undefined;
-onClickLeftIcon?: ((...args: any[]) => any) | undefined;
-onClickRightIcon?: ((...args: any[]) => any) | undefined;
-"onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
-}>, "tag" | "center" | "isLink" | "border" | "required" | "clickable" | "autofocus" | "clearable" | "clearIcon" | "modelValue" | "clearTrigger" | "formatTrigger" | "spellcheck" | "error" | "disabled" | "readonly" | "type" | "showWordLimit" | "colon"> & {} & {} & ComponentCustomProperties & {} & {
-$props: {
-onClick?: (...args: any[]) => void;
-};
-}) | null;
-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<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
-    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{} & VNodeProps & AllowedComponentProps & ComponentCustomProps, never>, never> & {
-        form?: F;
-    } & 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_5, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<Props_5> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
-
 declare type BaseWithFields<D extends Data = Data> = BaseCommon<D> & {
     /**
      * @description 嵌套子字段配置 (Vant 中主要用于分组，或者通过 CellGroup 包裹)
@@ -699,11 +257,30 @@ declare type BaseWithoutFields<D extends Data = Data> = BaseCommon<D> & {
     popup?: boolean | Partial<PopupProps>;
 };
 
+/**
+ * 组件映射扩展接口
+ * @description 通过 TypeScript 声明合并添加自定义组件
+ *
+ * @example
+ * ```ts
+ * declare module '@qin-ui/vant-pro' {
+ *   interface ComponentMap {
+ *     'my-custom': typeof MyComponent;
+ *   }
+ * }
+ * ```
+
+ * @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>;
@@ -711,39 +288,113 @@ export declare type ComponentVars = Partial<RequiredComponentVars>;
 /**
  * @description 容器组件类型
  */
-export declare type ContainerComponent = Component<PathProps> | DefineComponent<PathProps> | VNodeTypes | symbol;
+declare type ContainerComponent = Component<PathProps> | DefineComponent<PathProps> | VNodeTypes | symbol;
 
 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/vant-pro 安装方法
+     * @description 全局注册所有组件（ProForm、ProComponentProvider）
+     *
+     * @param {App} app - Vue 应用实例
+     *
+     * @example
+     * ```ts
+     * import { createApp } from 'vue'
+     * import QinUI from '@qin-ui/vant-pro'
+     * const app = createApp(App)
+     * app.use(QinUI)
+     * ```
+     */
     install(app: App): void;
 };
 export default _default;
 
-export declare type DisplayFormatter = (val: any) => string;
+declare const _default_2: <F extends Form<any> = Form>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{} & VNodeProps & AllowedComponentProps & ComponentCustomProps, never>, never> & {
+        form?: F;
+    } & 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 ensureInjectConfig: (key: string) => InjectConfigEntry;
+declare type DisplayFormatter = (val: any) => string;
 
+/**
+ * 用 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>;
 
 export declare type Field<C extends ComponentName = ComponentName, D extends Data = Data> = FieldTypeMap<D>[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;
 
 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;
@@ -754,73 +405,161 @@ export declare type FieldTypeMap<D extends Data = Data> = {
     };
 };
 
+/**
+ * @qin-ui/vant-pro 的表单实例类型
+ *
+ * @description 在 core Form 类型的基础上：
+ * 1. 将字段类型 F 绑定为本地 Field<ComponentName, D>
+ * 2. 将底层表单实例绑定为 Vant 的 FormInstance
+ * 3. 额外包含 formPopup 对象，用于管理弹出层表单
+ *
+ * @template D - 表单数据类型
+ * @template F - 字段配置类型
+
+ * @public
+ */
 export declare type Form<D extends Data = Data, F extends Field<ComponentName, D> = Field<ComponentName, D>> = Form_2<D, F, FormInstance> & {
     formPopup: FormPopup;
 };
 
-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>>;
+/**
+ * 表单实例类型
+ * @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>>;
 
-export { FormInstance }
+/**
+ * 表单弹出层管理对象
+ * @description Vant 移动端特有的表单弹出层功能
 
-export declare type FormPopup = {
+ * @public
+ */
+declare type FormPopup = {
+    /** Popup 组件属性 */
     props: PopupProps;
+    /** 打开指定路径字段的弹出层 */
     open: (path: string) => void;
+    /** 关闭弹出层 */
     close: () => void;
+    /** 更新 Popup 组件属性 */
     updateProps: (props: Partial<PopupProps>) => void;
+    /** 弹出层是否可见 */
     visible: ComputedRef<boolean>;
+    /** 当前弹出层对应的字段路径 */
     popupFieldPath: Ref<string | undefined>;
+    /** 当前弹出层字段的值 */
     popupFieldValue: Ref<any | undefined>;
 };
 
 declare type FP<T extends Record<string, any>> = Partial<T & Pick<Base, 'valueFormatter' | 'displayFormatter' | 'componentContainer' | 'modelProp' | 'popup'> & 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 const GroupedFieldAttrs: __VLS_WithTemplateSlots_3<typeof __VLS_component_3, __VLS_TemplateResult_3["slots"]>;
-
-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>;
-
-export declare const InjectionPathKey: InjectionKey<ComputedRef<string | undefined>>;
-
-export declare const InjectionPopupKey: unique symbol;
+/**
+ * 根据组件名获取组件类型
+ * @template K - 组件名称
+ */
+declare type GetComponentType<K extends ComponentName> = K extends keyof ComponentMap ? ComponentMap[K] : K extends keyof BaseComponentMap ? BaseComponentMap[K] : never;
 
+/**
+ * 判断类型是否为对象（排除函数、数组和 null）
+ * @template T - 要判断的类型
+ */
 declare type IsRecord<T> = T extends object ? T extends ((...args: any[]) => any) | any[] | null ? false : true : false;
 
+/**
+ * 展开字符串联合类型，保留字符串字面量，同时兼容 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>;
 
 declare type NotSupportedRefOrGetterProps = 'component' | 'fieldContainer' | 'componentContainer' | 'valueFormatter' | 'displayFormatter' | 'fields' | 'slots' | 'modelProp' | 'popup';
 
+/**
+ * 路径类型，用于类型安全的深层属性访问
+ * @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;
 
-export declare const PathProvider: __VLS_WithTemplateSlots_2<typeof __VLS_component_2, __VLS_TemplateResult_2["slots"]>;
+/**
+ * Vant Popup 组件属性类型
+ * @description 用于配置表单弹出层的属性
 
-export declare type PopupProps = ComponentProps<typeof Popup> & {
+ * @public
+ */
+declare type PopupProps = ComponentProps<typeof Popup> & {
     container: ContainerComponent;
 };
 
@@ -897,37 +636,24 @@ 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_2>;
 
-export declare type ProFormProps = ComponentProps<typeof BaseForm>;
+export declare type ProFormProps = ComponentProps<typeof _default_2>;
 
 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 = {
-    field: Field;
-};
-
-declare type Props_5 = {
-    fields?: Fields;
-};
-
 /**
  * @description 自定义组件
  */
-export declare type RenderComponentType = Component<VModelProps & PathProps>;
+declare type RenderComponentType = Component<VModelProps & PathProps>;
 
-export declare type RequiredComponentVars = {
+declare type RequiredComponentVars = {
     'pro-form': PP<Omit<ProFormProps & FormProps, 'form'>>;
 } & {
     [K in Exclude<ComponentName, 'custom'>]: FP<ComponentProps<GetComponentType<K>>>;
@@ -935,33 +661,114 @@ export declare type RequiredComponentVars = {
 
 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;
 };
 
-export declare const TeleportComponentNamePrefix = "TeleportComponent_";
-
 declare type UpdateFieldOptions = {
     all?: boolean;
 };
 
+/** useFields 返回值类型，固定为本地 Fields<D>
+ * @public
+ */
 export declare type UseFields<D extends Data = Data> = ReturnType<typeof useFields<D>>;
 
+/**
+ * @qin-ui/vant-pro 的字段配置管理 Hook
+ *
+ * @description 类型安全的 re-export。将 core useFields 的泛型参数绑定为本地类型：
+ * - 字段类型 F → Field<ComponentName, D>（支持 Vant 组件类型推导）
+ * - Field 实例 → Vant 的 FieldInstance
+ *
+ * @template D - 表单数据类型
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number }
+ *
+ * const { fields, getField, setField } = useFields<User>([
+ *   { path: 'name', label: '姓名', component: 'field' },
+ *   { path: 'age', label: '年龄', component: 'stepper' },
+ * ])
+ * ```
+
+ * @public
+ */
 export declare const useFields: {
     <D extends Data = Data>(initFields?: Fields<D>): ReturnType<typeof useFields_2<D, Field<ComponentName, D>, FieldInstance>>;
 };
 
-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;
@@ -989,14 +796,73 @@ declare const useFields_2: <D extends Data = Data, F extends BaseField_2<D> = Ba
     };
 };
 
+/**
+ * 创建 @qin-ui/vant-pro 表单实例的 Hook
+ *
+ * @description 基于 core useForm 封装，额外提供了 formPopup 用于移动端弹窗表单。
+ *
+ * @template D - 表单数据类型
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number }
+ *
+ * const form = useForm<User>(
+ *   { name: '张三' },
+ *   [
+ *     { path: 'name', label: '姓名', component: 'field' },
+ *   ]
+ * )
+ *
+ * // 打开弹出层表单
+ * form.formPopup.open('address')
+ * form.formPopup.close()
+ * ```
+
+ * @public
+ */
 export declare function useForm<D extends Data = Data>(initFormData?: ExtendWithAny<DeepPartial<D>>, initFields?: Field<ComponentName, D>[], root?: boolean): Form<D, Field<ComponentName, D>>;
 
 export declare function useForm<D extends Data = Data>(root?: boolean): Form<D, Field<ComponentName, D>>;
 
 /**
- * 表单数据处理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>>;
@@ -1014,25 +880,59 @@ export declare const useFormData: <D extends Data = Data>(initFormData?: ExtendW
     };
 };
 
-export declare function useFormPopup(root?: boolean): FormPopup;
-
+/**
+ * @qin-ui/vant-pro 的表单组件实例引用 Hook
+ *
+ * @description 类型安全的 re-export。将 core useFormRef 的泛型参数绑定为 Vant 的 FormInstance。
+ *
+ * @returns {object} 表单组件实例引用管理对象
+ * @returns {Ref<FormInstance | undefined>} .formRef - Vant Form 实例的响应式引用
+ * @returns {Function} .setFormRef(inst) - 设置表单组件实例
+ *
+ * @example
+ * ```ts
+ * const { formRef, setFormRef } = useFormRef()
+ * formRef.value?.submit()
+ * ```
+
+ * @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;
 };
 
-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> = {
     modelValue?: T;
     'onUpdate:modelValue'?: (val: T) => void;
 };
@@ -1047,7 +947,7 @@ declare type WithComponent<T extends abstract new (...args: any) => any, D exten
 
 declare type WithFields<D extends Data = Data> = WithRef<WithCommonBase & BaseWithFields<D>>;
 
-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]>;
 };