@manohub/ui 0.6.0

package/dist/components/form/index.d.ts

@@ -0,0 +1,704 @@
+import { type PropType, type SlotsType, type VNodeChild } from 'vue';
+import { type Padding } from '../part-padding';
+/** 表单内距：与 `PanelPadding` **同一口径同一实现**（`number` = 四边同值；`{ y, x }` = 上下 / 左右分别给） */
+export type FormPadding = Padding;
+/** label 列的水平对齐：`right`（默认，与 farris / 主流水平表单一致）或 `left` */
+export type FormLabelAlign = 'left' | 'right';
+/** 表单值：**字段名 → 值**（键就是 `Form.Item` 的 `name`） */
+export type FormValues = Record<string, unknown>;
+/**
+ * 带 `name` 的 `Form.Item` 的默认插槽作用域：控件由消费方渲染，本件只把绑定值交出去。
+ * 不带 `name` 的项（纯布局 / 只读行）不需要这些，作用域里的值恒为 `undefined`。
+ */
+export interface FormItemSlotScope {
+    /** 当前字段值（Form 里的原值，不做任何归一） */
+    value: unknown;
+    /** 写入该字段（随即可在 `Form` 的 `onChange` 收到新快照） */
+    setValue: (value: unknown) => void;
+    /** 清空该字段（等价于 `setValue(undefined)`） */
+    clear: () => void;
+}
+export interface FormProps {
+    /** 表单级 label 列宽（px）；缺省取令牌 `--ui-form-label-width`（120）。px 不跟随根字号，见 CONTRACT「已知偏差」 */
+    labelWidth?: number;
+    /**
+     * 表单级 label 对齐：`right`（默认，文本贴着控件列）或 `left`（所有 label 起点一致）。
+     * `Form.Item` 上再写则只改那一行。
+     */
+    labelAlign?: FormLabelAlign;
+    /**
+     * 表单级控件列宽上限（px）；缺省**撑满**剩余宽度。
+     *
+     * 宽表单（>600px）里让输入框一路拉到右边缘很难看，两种收法二选一：
+     * ① 收宽度 —— 传 `controlWidth={360}`，控件列封顶、右侧留白；
+     * ② 分两列 —— 传 `columns={2}`，把行并排起来（更充分地用宽度，见下）。
+     */
+    controlWidth?: number;
+    /**
+     * 列数：`1`（默认，逐行）或 `2`（**容器够宽才并排**，窄了按列最小宽度自动回落一列）。
+     *
+     * 两列下每一行都要能独立成格，所以「整行内容」（说明行、卡片组、表格、文本域）记得
+     * 在对应 `Form.Item` 上给 `fullWidth`，否则会被压成半宽。
+     */
+    columns?: 1 | 2;
+    /**
+     * 表单内距（**px 数字**，与 `Panel` 同一口径）：`number` = 四边同值；`{ y, x }` = 上下 / 左右分别给。
+     *
+     * **缺省 0**：表单贴容器边，内距由所在容器给（页面里的表单在 `Panel.Body` 里，那块自带内距）。
+     * 弹窗 / 抽屉里没有别的容器给内距时用它自带 —— 如 `padding={{ y: 16, x: 20 }}`，
+     * 这样就不必再给表单挂一个「只写 padding」的应用侧类。
+     */
+    padding?: FormPadding;
+    /** 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档 */
+    gap?: number;
+    /**
+     * 受控表单值（**字段名 → 值**，键就是 `Form.Item` 的 `name`）；不传即非受控（由 `defaultValue` 起）。
+     *
+     * 值变更时 `emit('update:modelValue')` 与 `onChange` **双走**（`v-model` 落地 + 回调）。
+     */
+    modelValue?: FormValues;
+    /** 非受控初值；其中的键会一并成为快照的键（不必等字段挂载） */
+    defaultValue?: FormValues;
+    /** 值变更（快照含**全部已登记字段**，未设值的字段为 `undefined`） */
+    onChange?: (values: FormValues) => void;
+}
+export interface FormItemProps {
+    /**
+     * **字段名**（绑定的键）：带了它，本行就从 `Form` 取值并把写值交出去
+     * （默认插槽作用域 `{ value, setValue, clear }`）；不带则与从前一样 ——
+     * 纯布局行，值由消费方自己在控件上绑定（静态摘要 / 只读行都属这一类）。
+     */
+    name?: string;
+    /**
+     * 字段名（label 文本）。缺省且非必填时**不渲染 label 列**：控件列占满整行
+     * —— 用于无字段名的整块内容（如列编辑区）与纯说明行。
+     */
+    label?: string;
+    /**
+     * 必填标记：星号渲染在 label 文本**之后**（`服务名称*`）—— 星号是字段名的一部分，
+     * 跟着字段名走；与 farris 动态表单「星号在左」的写法**有意不同**（本仓口径）。
+     */
+    required?: boolean;
+    /** 校验错误文案：非空即进入 invalid 态，文案排布在控件**下方**（不遮挡后续行） */
+    error?: string;
+    /** 字段说明文案（常驻，排在错误之后） */
+    hint?: string;
+    /** 本行 label 列宽（px）；覆盖 `Form` 的表单级设置 */
+    labelWidth?: number;
+    /** 本行 label 对齐；覆盖 `Form` 的表单级设置 */
+    labelAlign?: FormLabelAlign;
+    /**
+     * 本行控件列宽上限（px）；覆盖 `Form` 的表单级设置。
+     * 缺省撑满剩余宽度（宽表单里的选型字段用它收敛，避免长条下拉）。
+     */
+    controlWidth?: number;
+    /** 在两列表单里跨满整行（说明行 / 卡片组 / 表格 / 文本域等整块内容） */
+    fullWidth?: boolean;
+    /**
+     * **只读文本形态**：传了它（含空串）即不走控件插槽，改为在控件位渲染纯文本 ——
+     * 用于「摘要 / 详情」这类静态表单行（同一个表单里 label 列、行距、错误、说明全部复用）。
+     *
+     * 空值（`''` / 全空白）由组件统一显示 `—`，消费方不必每处写 `value || '—'`；
+     * 换行符原样保留（SQL where 这类多行文本回显不会被压成一行）。
+     *
+     * 传了它这一行的 label 会降一档**次要色**（与正文色的值拉开层级），控件行不受影响。
+     */
+    text?: string;
+    /**
+     * **只读展示行**：只把 label 弱化（次要色），内容仍走默认插槽 ——
+     * 用于控件位不是纯文本的只读内容（徽标 / 链接这类）。
+     *
+     * 纯文本一律用 `text`（它自带只读语义，不必再传本开关）；本开关与 `text` 互斥不会冲突 ——
+     * 两个都给时 `text` 优先（`readonly` 只是把 label 的弱化带过去）。
+     */
+    readonly?: boolean;
+}
+/**
+ * 表单行（**自建**）：`label + 控件 + 错误 + 说明` 四件。
+ *
+ * 为什么不封装 farris 的 `FDynamicFormGroup`：那是动态表单（元数据驱动）体系里的分组件 ——
+ * 控件要经 `editor` 描述对象交给它渲染，label 宽度 / 控件限宽由 farris 表单类写死
+ * （inline 6rem 右对齐、字段 max-width 26.625rem），校验信息走**绝对定位的浮层提示条**。
+ * 与本仓三条口径冲突：① 控件由消费方直接写（不构造底层配置对象）；② 数据入参只收朴素业务值；
+ * ③ 错误与说明按文档流排布（浮层在弹窗里会压住下一行的控件）。故按「缺件处置流程」自建，
+ * 必填星号固定在 label 文本**之后**（`服务名称*`，有意偏离 farris 的「星号在左」）；
+ * **label 对齐是维度**（`labelAlign`，
+ * 默认 `right`（与 farris / 主流水平表单一致），`left` 时所有 label 起点一致）。
+ *
+ * ## 宽表单怎么处理（两条杠杆，可叠加）
+ *
+ * - **限宽**：`controlWidth` 封顶控件列（表单级给默认、逐行可覆盖）—— 单列表单不至于把输入框拉成长条；
+ * - **分两列**：`columns={2}` 让行并排，宽度用得更充分；列最小宽度取令牌
+ *   `--ui-form-column-min`（默认 320），所以窄容器会**自动回落成一列**，不需要消费方写媒体查询。
+ *   两列下「整块内容」记得 `fullWidth`。
+ *
+ * `Form.Item` 是唯一入口（`Form` 只承载表单级设置、行间距/列数与容器内距），
+ * 控件从默认插槽进，因此输入框 / 下拉 / 文本域 / 自绘分组卡片共用同一个容器。
+ *
+ * ## 容器内距（`padding`）
+ *
+ * 与 `Panel` **同一口径同一实现**（`src/components/part-padding.ts`）：`number` 四边同值、
+ * `{ y, x }` 上下 / 左右分别给，缺省 0（贴容器边）。页面里的表单在 `Panel.Body` 里、内距由那块给；
+ * **弹窗 / 抽屉里没有别的容器**给内距，就用表单自带的 `padding={{ y: 16, x: 20 }}`。
+ *
+ * ## 静态表单（摘要 / 详情）
+ *
+ * `Form.Item` 传 `text` 即切成**只读文本行**，三类行可以在同一个表单里混排 ——
+ * label 列宽、行距、错误与说明全部共用，所以「向导最后一步的确认摘要」「详情弹窗」不需要
+ * 另起一套描述列表件（自绘表格的 label/value 几何与表单行迟早会漂开）。
+ * 空值占位 `—`、长文案折行、换行符保留都由组件给；只读行的 label 自动降一档次要色，
+ * 字段名与取值一眼分得开（应用侧写不了 `color`，这层区分只能由组件给）。
+ * 控件位要放徽标 / 链接这类**非文本**只读内容时传 `readonly`：内容走默认插槽，label 的弱化照旧。
+ *
+ * @example
+ * <Form labelWidth={120} columns={2}>
+ *   <Form.Item label="编码" required error={errors.code} hint="保存后不可修改">
+ *     <Input modelValue={form.code} onChange={(v) => (form.code = v)} />
+ *   </Form.Item>
+ *   <Form.Item label="缓存策略" controlWidth={360}>
+ *     <Select options={cacheOptions} modelValue={form.cache} onChange={…} />
+ *   </Form.Item>
+ *   <Form.Item label="过滤条件" fullWidth>
+ *     <Textarea modelValue={form.filter} onChange={…} />
+ *   </Form.Item>
+ * </Form>
+ */
+export declare const FormItem: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /** 字段名（绑定的键）；不传即纯布局行（值由消费方自己在控件上绑定） */
+    name: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    label: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    required: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    error: {
+        type: StringConstructor;
+        default: string;
+    };
+    hint: {
+        type: StringConstructor;
+        default: string;
+    };
+    labelWidth: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    labelAlign: {
+        type: PropType<FormLabelAlign>;
+        default: undefined;
+    };
+    controlWidth: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    fullWidth: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
+    text: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+    readonly: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /** 字段名（绑定的键）；不传即纯布局行（值由消费方自己在控件上绑定） */
+    name: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    label: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    required: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    error: {
+        type: StringConstructor;
+        default: string;
+    };
+    hint: {
+        type: StringConstructor;
+        default: string;
+    };
+    labelWidth: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    labelAlign: {
+        type: PropType<FormLabelAlign>;
+        default: undefined;
+    };
+    controlWidth: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    fullWidth: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
+    text: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+    readonly: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{}>, {
+    text: string;
+    name: string;
+    label: string;
+    error: string;
+    required: boolean;
+    readonly: boolean;
+    hint: string;
+    labelWidth: number;
+    labelAlign: FormLabelAlign;
+    controlWidth: number;
+    fullWidth: boolean;
+}, SlotsType<{
+    default?: (scope: FormItemSlotScope) => VNodeChild;
+}>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export interface FormHeaderProps {
+    /**
+     * 表单头标题。不传则该行不渲染标题文本 —— 但给了 `extra` 时这一行**照渲染**
+     * （右端操作位不能凭空消失，与 `Panel`「只给 toolbar / actions、不给 title」同一条口径）。
+     */
+    title?: string;
+    /** 标题下的说明小字（一行话，讲清这块表单是做什么的） */
+    description?: string;
+}
+/**
+ * 表单头（`Form` 的成员件，**单头**）：标题行 + 右端操作位（`extra`）。
+ *
+ * 一个 `Form` 只有一个头，且**渲染在最前** —— 在 default 插槽里写第几个都一样（成员归位，
+ * 与 `Page` / `Panel` 同一手法，所以「读代码的顺序」不必等于「视觉顺序」）。
+ *
+ * 它只做**标题排版**与操作位，不承担区块分组（那是 `Panel` 的职责）；三样（`title` /
+ * `extra` / `description`）都没有时整组不渲染 —— 空盒子同样占一档 `Form` 的 gap，会凭空多出间距。
+ *
+ * @example 筛选条的头（标题 + 右侧查询/重置）—— 插槽走 `h()` 的对象形态：
+ * TSX 的 `v-slots={{…}}` 在 vitest 的 JSX 管线里会被当**普通属性**丢掉（见 `list-view/index.tsx` 同款记录）
+ * {h(Form, {}, {
+ *   default: () => [
+ *     h(Form.Header, { title: '高级筛选' }, { extra: () => h(Button, { variant: 'primary' }, '筛选') }),
+ *     h(Form.Item, { name: 'keyword', label: '技能名称' }, { default: () => h(Input) }),
+ *   ],
+ * })}
+ *
+ * @example 只要操作位（不要标题）：`h(Form.Header, {}, { extra: () => … })`
+ */
+export declare const FormHeader: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    title: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    description: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}>, () => import("vue/jsx-runtime").JSX.Element | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    title: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    description: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    title: string;
+    description: string;
+}, SlotsType<{
+    extra?: () => VNodeChild;
+}>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** 复合件入口：`Form` + `Form.Header` + `Form.Item`（与 `Page` 等同款 Object.assign 复合写法，成员不平级导出） */
+export declare const Form: {
+    new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<import("vue").ExtractPropTypes<{
+        /** 表单级 label 列宽（px）；`Form.Item` 的 `labelWidth` 优先级更高 */
+        labelWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        /** 表单级 label 对齐；`Form.Item` 的 `labelAlign` 优先级更高 */
+        labelAlign: {
+            type: PropType<FormLabelAlign>;
+            default: undefined;
+        };
+        /** 表单级控件列宽上限（px）；`Form.Item` 的 `controlWidth` 优先级更高 */
+        controlWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        /** 列数：1（逐行，默认）/ 2（容器够宽才并排，窄了自动回落一列） */
+        columns: {
+            type: PropType<1 | 2>;
+            default: number;
+        };
+        /** 表单内距（px 数字，或 `{ y, x }`）；缺省 0 = 贴容器边（弹窗 / 抽屉里常用它自带内距） */
+        padding: {
+            type: PropType<FormPadding>;
+            default: undefined;
+        };
+        /**
+         * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。
+         *
+         * 窄容器（抽屉 / 移动端）与「字段名很长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
+         */
+        layout: {
+            type: PropType<"horizontal" | "vertical">;
+            default: string;
+        };
+        /**
+         * 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。
+         *
+         * 筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径）；长表单也可以调松。
+         */
+        gap: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        /** 受控表单值（字段名 → 值）；不传即非受控（由 `defaultValue` 起） */
+        modelValue: {
+            type: PropType<FormValues>;
+            default: undefined;
+        };
+        /** 非受控初值；其中的键会一并成为快照的键（不必等字段挂载） */
+        defaultValue: {
+            type: PropType<FormValues>;
+            default: undefined;
+        };
+        /** 值变更（快照含**全部已登记字段**，未设值的字段为 `undefined`） */
+        onChange: {
+            type: PropType<(values: FormValues) => void>;
+            default: undefined;
+        };
+    }>> & Readonly<{
+        "onUpdate:modelValue"?: ((values: FormValues) => any) | undefined;
+    }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+        'update:modelValue': (values: FormValues) => true;
+    }, import("vue").PublicProps, {
+        padding: Padding;
+        layout: "horizontal" | "vertical";
+        onChange: (values: FormValues) => void;
+        defaultValue: FormValues;
+        gap: number;
+        columns: 1 | 2;
+        modelValue: FormValues;
+        labelWidth: number;
+        labelAlign: FormLabelAlign;
+        controlWidth: number;
+    }, true, {}, SlotsType<{
+        default?: () => VNodeChild;
+    }>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, {}, any, import("vue").ComponentProvideOptions, {
+        P: {};
+        B: {};
+        D: {};
+        C: {};
+        M: {};
+        Defaults: {};
+    }, Readonly<import("vue").ExtractPropTypes<{
+        /** 表单级 label 列宽（px）；`Form.Item` 的 `labelWidth` 优先级更高 */
+        labelWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        /** 表单级 label 对齐；`Form.Item` 的 `labelAlign` 优先级更高 */
+        labelAlign: {
+            type: PropType<FormLabelAlign>;
+            default: undefined;
+        };
+        /** 表单级控件列宽上限（px）；`Form.Item` 的 `controlWidth` 优先级更高 */
+        controlWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        /** 列数：1（逐行，默认）/ 2（容器够宽才并排，窄了自动回落一列） */
+        columns: {
+            type: PropType<1 | 2>;
+            default: number;
+        };
+        /** 表单内距（px 数字，或 `{ y, x }`）；缺省 0 = 贴容器边（弹窗 / 抽屉里常用它自带内距） */
+        padding: {
+            type: PropType<FormPadding>;
+            default: undefined;
+        };
+        /**
+         * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。
+         *
+         * 窄容器（抽屉 / 移动端）与「字段名很长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
+         */
+        layout: {
+            type: PropType<"horizontal" | "vertical">;
+            default: string;
+        };
+        /**
+         * 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。
+         *
+         * 筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径）；长表单也可以调松。
+         */
+        gap: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        /** 受控表单值（字段名 → 值）；不传即非受控（由 `defaultValue` 起） */
+        modelValue: {
+            type: PropType<FormValues>;
+            default: undefined;
+        };
+        /** 非受控初值；其中的键会一并成为快照的键（不必等字段挂载） */
+        defaultValue: {
+            type: PropType<FormValues>;
+            default: undefined;
+        };
+        /** 值变更（快照含**全部已登记字段**，未设值的字段为 `undefined`） */
+        onChange: {
+            type: PropType<(values: FormValues) => void>;
+            default: undefined;
+        };
+    }>> & Readonly<{
+        "onUpdate:modelValue"?: ((values: FormValues) => any) | undefined;
+    }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, {
+        padding: Padding;
+        layout: "horizontal" | "vertical";
+        onChange: (values: FormValues) => void;
+        defaultValue: FormValues;
+        gap: number;
+        columns: 1 | 2;
+        modelValue: FormValues;
+        labelWidth: number;
+        labelAlign: FormLabelAlign;
+        controlWidth: number;
+    }>;
+    __isFragment?: never;
+    __isTeleport?: never;
+    __isSuspense?: never;
+} & import("vue").ComponentOptionsBase<Readonly<import("vue").ExtractPropTypes<{
+    /** 表单级 label 列宽（px）；`Form.Item` 的 `labelWidth` 优先级更高 */
+    labelWidth: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    /** 表单级 label 对齐；`Form.Item` 的 `labelAlign` 优先级更高 */
+    labelAlign: {
+        type: PropType<FormLabelAlign>;
+        default: undefined;
+    };
+    /** 表单级控件列宽上限（px）；`Form.Item` 的 `controlWidth` 优先级更高 */
+    controlWidth: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    /** 列数：1（逐行，默认）/ 2（容器够宽才并排，窄了自动回落一列） */
+    columns: {
+        type: PropType<1 | 2>;
+        default: number;
+    };
+    /** 表单内距（px 数字，或 `{ y, x }`）；缺省 0 = 贴容器边（弹窗 / 抽屉里常用它自带内距） */
+    padding: {
+        type: PropType<FormPadding>;
+        default: undefined;
+    };
+    /**
+     * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。
+     *
+     * 窄容器（抽屉 / 移动端）与「字段名很长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
+     */
+    layout: {
+        type: PropType<"horizontal" | "vertical">;
+        default: string;
+    };
+    /**
+     * 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。
+     *
+     * 筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径）；长表单也可以调松。
+     */
+    gap: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    /** 受控表单值（字段名 → 值）；不传即非受控（由 `defaultValue` 起） */
+    modelValue: {
+        type: PropType<FormValues>;
+        default: undefined;
+    };
+    /** 非受控初值；其中的键会一并成为快照的键（不必等字段挂载） */
+    defaultValue: {
+        type: PropType<FormValues>;
+        default: undefined;
+    };
+    /** 值变更（快照含**全部已登记字段**，未设值的字段为 `undefined`） */
+    onChange: {
+        type: PropType<(values: FormValues) => void>;
+        default: undefined;
+    };
+}>> & Readonly<{
+    "onUpdate:modelValue"?: ((values: FormValues) => any) | undefined;
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    'update:modelValue': (values: FormValues) => true;
+}, string, {
+    padding: Padding;
+    layout: "horizontal" | "vertical";
+    onChange: (values: FormValues) => void;
+    defaultValue: FormValues;
+    gap: number;
+    columns: 1 | 2;
+    modelValue: FormValues;
+    labelWidth: number;
+    labelAlign: FormLabelAlign;
+    controlWidth: number;
+}, {}, string, SlotsType<{
+    default?: () => VNodeChild;
+}>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & {
+    Header: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+        title: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        description: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }>, () => import("vue/jsx-runtime").JSX.Element | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+        title: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        description: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }>> & Readonly<{}>, {
+        title: string;
+        description: string;
+    }, SlotsType<{
+        extra?: () => VNodeChild;
+    }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+    Item: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+        /** 字段名（绑定的键）；不传即纯布局行（值由消费方自己在控件上绑定） */
+        name: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        label: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        required: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        error: {
+            type: StringConstructor;
+            default: string;
+        };
+        hint: {
+            type: StringConstructor;
+            default: string;
+        };
+        labelWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        labelAlign: {
+            type: PropType<FormLabelAlign>;
+            default: undefined;
+        };
+        controlWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        fullWidth: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
+        text: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+        readonly: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+        /** 字段名（绑定的键）；不传即纯布局行（值由消费方自己在控件上绑定） */
+        name: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        label: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        required: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        error: {
+            type: StringConstructor;
+            default: string;
+        };
+        hint: {
+            type: StringConstructor;
+            default: string;
+        };
+        labelWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        labelAlign: {
+            type: PropType<FormLabelAlign>;
+            default: undefined;
+        };
+        controlWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        fullWidth: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
+        text: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+        readonly: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    }>> & Readonly<{}>, {
+        text: string;
+        name: string;
+        label: string;
+        error: string;
+        required: boolean;
+        readonly: boolean;
+        hint: string;
+        labelWidth: number;
+        labelAlign: FormLabelAlign;
+        controlWidth: number;
+        fullWidth: boolean;
+    }, SlotsType<{
+        default?: (scope: FormItemSlotScope) => VNodeChild;
+    }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+};
+export type FormCompound = typeof Form;