@dazhicheng/ui 1.5.155 → 1.5.158

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

@@ -12,4 +12,4 @@ type TtExtendedFormApi = ExtendedFormApi;
 export type { BaseFormComponentMap, BaseFormComponentType, FormSlotSchema, InferredComponentPropsType, TtExtendedFormApi, TtFormProps, TtFormRenderProps, TtFormSchema, };
 export * as z from 'zod';
 export { useGroupForm } from './src/group-form';
-export type { FormGroupSchema, GroupFormNavAnchorProps, GroupFormSchema, UseGroupFormNavAnchorProps, UseGroupFormOptions, } from './src/group-form';
+export type { FormGroupSchema, GroupFormNavAnchorProps, GroupFormSchema, UseGroupFormNavAnchorProps, UseGroupFormOptions, UseGroupFormOptionsWithGroupSchema, UseGroupFormOptionsWithLegacySchema, } from './src/group-form';

package/dist/components/tt-form/src/formApi.d.ts

@@ -40,6 +40,10 @@ export declare class FormApi {
     isFieldValid(fieldName: string): Promise<boolean>;
     merge(formApi: FormApi): any;
     mount(formActions: FormActions, componentRefMap: Map<string, unknown>): void;
+    /**
+     * @description 为 appendFields 新增的字段写入初始值（与 useFormInitial 规则一致，不覆盖已有数据）
+     */
+    protected seedDefaultsForAppendedFields(fields: FormSchema[]): Promise<void>;
     /**
      * @description 增量追加字段到 schema 中，支持通过 position 指定插入位置
      * @param {FormSchema[]} fields - 要插入的字段 schema 数组

package/dist/components/tt-form/src/group-form/groupFormApi.d.ts

@@ -71,7 +71,7 @@ export declare class GroupFormApi extends FormApi {
      */
     get navAnchorProps(): Required<Pick<UseGroupFormNavAnchorProps, "show">> & UseGroupFormNavAnchorProps;
     /**
-     * @description 覆盖基类 setState，扩展支持 GroupFormExtraState 中的字段（navAnchorProps、groupSchema 等）
+     * @description 覆盖基类 setState，扩展支持 GroupFormExtraState 中的字段（navAnchorProps、groupSchema 等）。
      * @param {Partial<GroupFormState> | ((prev: GroupFormState) => Partial<GroupFormState>)} stateOrFn - 新状态或更新函数
      */
     setState(stateOrFn: ((prev: GroupFormState) => Partial<GroupFormState>) | Partial<GroupFormState>): void;

package/dist/components/tt-form/src/group-form/index.d.ts

@@ -1,4 +1,4 @@
 export { GroupFormApi } from './groupFormApi';
 export { useGroupForm } from './useGroupForm';
-export type { FormGroupSchema, FormRowSchema, GroupFormApiOptions, GroupFormNavAnchorProps, GroupFormSchema, UseGroupFormNavAnchorProps, UseGroupFormOptions, } from './types';
-export { isGroupSchema, isRowSchema, isSlotSchema, extractFlatSchemas } from './utils';
+export type { FormGroupSchema, FormRowSchema, GroupFormApiOptions, GroupFormNavAnchorProps, GroupFormSchema, UseGroupFormNavAnchorProps, UseGroupFormOptions, UseGroupFormOptionsWithGroupSchema, UseGroupFormOptionsWithLegacySchema, } from './types';
+export { extractFlatSchemas, isGroupSchema, isRowSchema, isSlotSchema, resolveGroupSchema } from './utils';

package/dist/components/tt-form/src/group-form/types.d.ts

@@ -62,9 +62,8 @@ export type UseGroupFormNavAnchorProps = Omit<NavAnchorPropsBase, "badgeCounts">
  * VirtualGroupForm 组件接收的导航配置；`badgeCounts` 由组件内合并 `navErrorCounts` 与 `extraBadgeCounts` 注入。
  */
 export type GroupFormNavAnchorProps = UseGroupFormNavAnchorProps;
-/** 分组表单组件选项 */
-export interface UseGroupFormOptions extends Omit<TtFormProps, "schema" | "showDefaultActions"> {
-    schema: GroupFormSchema[];
+/** useGroupForm 除分组 schema 外的公共选项 */
+export type UseGroupFormOptionsCommon = Omit<TtFormProps, "schema" | "showDefaultActions"> & {
     /** 是否启用虚拟化，默认 true */
     virtual?: boolean;
     /** 滚动容器高度，默认 '100%' */
@@ -80,9 +79,27 @@ export interface UseGroupFormOptions extends Omit<TtFormProps, "schema" | "showD
     navAnchorProps?: UseGroupFormNavAnchorProps;
     /** 滚动到分组时的顶部偏移量（px），用于补偿页面顶部固定元素（如 header）的遮挡，默认 0 */
     scrollOffset?: number;
+};
+/** 推荐：使用 groupSchema 传入分组树 */
+export interface UseGroupFormOptionsWithGroupSchema extends UseGroupFormOptionsCommon {
+    /** 分组 schema 树形结构 */
+    groupSchema: GroupFormSchema[];
 }
+/**
+ * @description 已废弃的分组表单入参（兼容旧代码）
+ * @deprecated 请改用 {@link UseGroupFormOptionsWithGroupSchema}，通过 `groupSchema` 传入分组树
+ */
+export interface UseGroupFormOptionsWithLegacySchema extends UseGroupFormOptionsCommon {
+    /**
+     * 分组 schema 树形结构
+     * @deprecated 请使用 `groupSchema` 替代
+     */
+    schema: GroupFormSchema[];
+}
+/** groupSchema 与 schema 二选一（至少传一个） */
+export type UseGroupFormOptions = UseGroupFormOptionsWithGroupSchema | UseGroupFormOptionsWithLegacySchema;
 export type GroupFormExtraState = Partial<Pick<UseGroupFormOptions, "virtual" | "navAnchorProps" | "containerHeight" | "rootMargin" | "estimateFieldHeight" | "scrollOffset">> & {
-    /** 分组 schema 树形结构 */
+    /** 分组 schema 树形结构（store 状态，由 GroupFormApi.setState 维护） */
     groupSchema?: GroupFormSchema[];
 };
 /** 分组表单完整 store 状态类型 */
@@ -144,10 +161,10 @@ export interface GroupSectionProps {
 }
 /**
  * @description GroupFormApi 构造函数的分组配置选项，复用 UseGroupFormOptions 中同名字段的类型定义，
- *   额外增加 `groupSchema`（由 useGroupForm 从 `schema` 转换而来）。
+ *   额外增加 `groupSchema`（由 useGroupForm 传入）。
  */
 export type GroupFormApiOptions = Pick<UseGroupFormOptions, "virtual" | "navAnchorProps" | "scrollToFirstError" | "containerHeight" | "rootMargin" | "estimateFieldHeight" | "scrollOffset"> & {
-    /** 分组 schema 树形结构（由 useGroupForm 从 options.schema 传入） */
+    /** 分组 schema 树形结构（由 useGroupForm 传入） */
     groupSchema: GroupFormSchema[];
 };
 export {};

package/dist/components/tt-form/src/group-form/useGroupForm.d.ts

@@ -1,7 +1,14 @@
 import { DefineComponent } from 'vue';
 import { GroupFormApi } from './groupFormApi';
-import { UseGroupFormOptions } from './types';
+import { UseGroupFormOptions, UseGroupFormOptionsCommon, UseGroupFormOptionsWithLegacySchema } from './types';
+type GroupFormOverrideProps = Partial<UseGroupFormOptionsCommon>;
+type UseGroupFormReturn = readonly [DefineComponent<GroupFormOverrideProps>, GroupFormApi];
 /**
  * @description 返回可渲染的包装组件、扩展后的表单 API，以及分组折叠状态对象。
  */
-export declare function useGroupForm(options: UseGroupFormOptions): readonly [DefineComponent<Partial<Omit<UseGroupFormOptions, "schema">>>, GroupFormApi];
+export declare function useGroupForm(options: UseGroupFormOptions): UseGroupFormReturn;
+/**
+ * @deprecated 请改用 `groupSchema` 传入分组树
+ */
+export declare function useGroupForm(options: UseGroupFormOptionsWithLegacySchema): UseGroupFormReturn;
+export {};

package/dist/components/tt-form/src/group-form/utils.d.ts

@@ -42,6 +42,15 @@ export declare function getSchemaKey(schema: GroupFormSchema, idx: number): stri
  * ]);
  * // 返回: [{ fieldName: 'name' }, { fieldName: 'age' }]
  */
+export type GroupSchemaSourceOptions = {
+    groupSchema?: GroupFormSchema[];
+    /** @deprecated 请使用 groupSchema */
+    schema?: GroupFormSchema[];
+};
+/**
+ * @description 解析分组 schema：优先 `groupSchema`，兼容已废弃的 `schema`
+ */
+export declare function resolveGroupSchema(options: GroupSchemaSourceOptions): GroupFormSchema[];
 export declare function extractFlatSchemas(schemas: GroupFormSchema[]): FormSchema[];
 /**
  * 递归收集分组 schema 中 defaultCollapsed 为 true 的分组 key，写入 states

package/dist/components/tt-form/src/hooks/useFieldArray.d.ts

@@ -1,9 +1,7 @@
-import { MaybeRefOrGetter, Ref } from 'vue';
-import { FieldArrayContext, FieldEntry } from '../types/forms';
+import { MaybeRefOrGetter } from 'vue';
+import { FieldArrayContext } from '../types/forms';
 /**
  * 与 vee-validate `useFieldArray` API 对齐：稳定 `key`、`entry.value` 可写（支持 v-model），
  * 外部 `resetForm` / `setValues` 时同步行列表；不使用官方 `computedDeep` 与易递归的深拷贝双向 watch。
  */
-export declare function useFieldArray<TValue extends Record<string, unknown> = Record<string, unknown>>(arrayPath: MaybeRefOrGetter<string>): Omit<FieldArrayContext<TValue>, "fields"> & {
-    fields: Ref<FieldEntry<TValue>[]>;
-};
+export declare function useFieldArray<TValue extends Record<string, unknown> = Record<string, unknown>>(arrayPath: MaybeRefOrGetter<string>): FieldArrayContext<TValue>;

package/dist/components/tt-form/src/index.vue.d.ts

@@ -28,7 +28,7 @@ declare function __VLS_template(): {
                 readonly fieldMappingTime?: import('./types').FieldMappingTime | undefined;
                 readonly form?: import('vee-validate').FormContext<import('vee-validate').GenericObject> | undefined;
                 readonly layout?: import('./types').FormLayout | undefined;
-                readonly schema?: (import('./types').FormSlotSchema | FormSchema<keyof import('./types').BaseFormComponentMap>)[] | undefined;
+                readonly schema?: (FormSchema<keyof import('./types').BaseFormComponentMap> | import('./types').FormSlotSchema)[] | undefined;
                 readonly showCollapseButton?: boolean | undefined;
                 readonly wrapperClass?: import('./types').WrapperClassType | undefined;
                 readonly globalCommonConfig?: import('./types').FormCommonConfig | undefined;
@@ -115,7 +115,7 @@ declare const __VLS_component: import('vue').DefineComponent<Props, {}, {}, {},
             readonly fieldMappingTime?: import('./types').FieldMappingTime | undefined;
             readonly form?: import('vee-validate').FormContext<import('vee-validate').GenericObject> | undefined;
             readonly layout?: import('./types').FormLayout | undefined;
-            readonly schema?: (import('./types').FormSlotSchema | FormSchema<keyof import('./types').BaseFormComponentMap>)[] | undefined;
+            readonly schema?: (FormSchema<keyof import('./types').BaseFormComponentMap> | import('./types').FormSlotSchema)[] | undefined;
             readonly showCollapseButton?: boolean | undefined;
             readonly wrapperClass?: import('./types').WrapperClassType | undefined;
             readonly globalCommonConfig?: import('./types').FormCommonConfig | undefined;

package/dist/components/tt-form/src/types/forms.d.ts

@@ -94,7 +94,7 @@ export type FieldEntry<TValue = Recordable> = {
     isLast: boolean;
 };
 export type FieldArrayContext<TValue = Recordable> = {
-    fields: FieldEntry<TValue>[];
+    fields: Ref<FieldEntry<TValue>[]>;
     remove: (idx: number) => void;
     replace: (newArray: TValue[]) => void;
     update: (idx: number, value: TValue) => void;

package/dist/components/tt-form/src/types.d.ts

@@ -364,7 +364,7 @@ export interface FormRenderProps<T extends BaseFormComponentType = BaseFormCompo
      */
     layout?: FormLayout;
     /**
-     * 表单定义，支持普通字段和自定义插槽混合
+     * 表单定义，支持普通字段
      */
     schema?: (FormSchema<T> | FormSlotSchema)[];
     /**

package/dist/components/tt-form/src/useFormContext.d.ts

@@ -3,6 +3,7 @@ import { FormSchema, ExtendedFormApi, FormActions, TtFormProps } from './types';
 type ExtendFormProps = TtFormProps & {
     formApi?: ExtendedFormApi;
 };
+export declare function isFormSchema(schema: unknown): schema is FormSchema;
 export declare const injectFormProps: <T extends [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions] | null | undefined = [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions]>(fallback?: T | undefined) => T extends null ? [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions] | null : [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions], provideFormProps: (contextValue: [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions]) => [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions];
 export declare const injectComponentRefMap: <T extends Map<string, unknown> | null | undefined = Map<string, unknown>>(fallback?: T | undefined) => T extends null ? Map<string, unknown> | null : Map<string, unknown>, provideComponentRefMap: (contextValue: Map<string, unknown>) => Map<string, unknown>;
 /** 提取单个字段默认值：defaultValue 优先，其次 Zod rules */
@@ -15,6 +16,14 @@ export declare function resolveSchemaItemDefaultValue(item: FormSchema): unknown
  * - 父行合并后会对嵌套数组递归补全（空嵌套数组、部分行缺字段）
  */
 export declare function resolveArrayFieldInitialValue(item: FormSchema): unknown;
+/**
+ * @description 解析单个字段的初始值（与 useFormInitial.generateInitialValues 单字段逻辑一致）
+ */
+export declare function resolveSchemaFieldInitialValue(item: FormSchema): unknown | undefined;
+/**
+ * @description appendFields 时判断是否需要为新字段写入初始值（不覆盖已有非空数据）
+ */
+export declare function shouldSeedAppendedFieldValue(values: Record<string, unknown>, item: FormSchema): boolean;
 export declare function useFormInitial(props: ComputedRef<TtFormProps> | TtFormProps): {
     delegatedSlots: ComputedRef<string[]>;
     form: import('vee-validate').FormContext<Record<string, unknown>, Record<string, unknown>>;