@dazhicheng/ui 1.5.40 → 1.5.41

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

@@ -50,10 +50,17 @@ export declare class FormApi {
     setFieldValue(field: string, value: any, shouldValidate?: boolean): Promise<void>;
     setLatestSubmissionValues(values: null | Recordable<any>): void;
     setState(stateOrFn: ((prev: TtFormProps) => Partial<TtFormProps>) | Partial<TtFormProps>): void;
+    /**
+     * 供子类覆盖：在 `setValues(fields, true)` 时用于白名单过滤的 fieldName 列表（默认取自 store 中的 `schema`）。
+     * @returns {string[]} 允许写入的字段名
+     */
+    protected getFieldNamesForSetValuesFilter(): string[];
     /**
      * 设置表单值
      * @param fields record
-     * @param filterFields 过滤不在schema中定义的字段 默认为true
+     * @param filterFields 为 true 时仅处理当前 schema 中已声明的 fieldName，并保留与现有值的深度合并规则；为 false 时原样交给 vee-validate。
+     *   配置了 `fieldMappingTime` 时，会先执行拆解→区间合并，再按本参数过滤：只要**区间主字段**在 schema（与 {@link FormApi.getFieldNamesForSetValuesFilter} 一致）中，合并后的主字段会留在 `mergedInput` 里，**默认 true 即可**。
+     *   仅当合并未发生（例如主字段不在 schema、`format` 为函数跳过）且入参里只剩**未在 schema 声明**的拆解键时，才需要传 `false` 才能把拆解字段写入 vee-validate。
      * @param shouldValidate
      */
     setValues(fields: Record<string, any>, filterFields?: boolean, shouldValidate?: boolean): Promise<void>;
@@ -64,8 +71,46 @@ export declare class FormApi {
     validateAndSubmitForm(): Promise<Recordable<any> | undefined>;
     validateField(fieldName: string, opts?: Partial<ValidationOptions>): Promise<import('vee-validate').ValidationResult<any>>;
     private getForm;
+    /**
+     * 将拆解后的起止时间解析为区间组件可用的值（优先 dayjs，失败则保留原值）。
+     * @param {unknown} raw 接口或拆解字段的值
+     * @param {string} _format 与 fieldMappingTime 中 format 对应，预留与 formatDate 对齐
+     * @returns {unknown} 解析后的值
+     */
+    private parseSplitTimeForRange;
+    /**
+     * 判断主字段是否已为「合法」日期区间 [start, end]（两项均可解析为有效日期）。合法则不再用拆解字段覆盖。
+     * @param {unknown} value 主字段值
+     * @returns {boolean} 是否为合法区间
+     */
+    private isValidRangeTimePair;
+    /**
+     * 与 {@link FormApi.handleRangeTimeValue} 相反：在 `fieldMappingTime` 配置下，将拆解起止拼成区间字段。
+     * - 仅当**区间主字段**在当前 schema（{@link FormApi.getFieldNamesForSetValuesFilter}）中有定义时处理。
+     * - 若主字段**已是合法日期区间**，不合并，保持原有值与行为。
+     * - 否则（未赋值、0、空数组、或非合法区间等）在拆解字段有有效数据时合并，并移除拆解键。
+     * @param {Record<string, any>} fields 调用方传入的 setValues 数据
+     * @returns {Record<string, any>} 合并后的浅拷贝对象
+     */
+    private mergeRangeTimeFieldsForSetValues;
+    /**
+     * 拆解字段是否为空（与「无有效起止」一致时不参与拼区间）。
+     * @param {unknown} value 拆解字段值
+     * @returns {boolean} 是否视为空
+     */
+    private isSplitTimeEmptyValue;
     private handleMultiFields;
     private handleRangeTimeValue;
     private processFields;
+    /**
+     * schema 变更后若存在从上一版 schema 中消失的 fieldName，会在 {@link FormApi.updateState} 中调用。
+     * 子类（如分组表单）可覆盖以同步清理虚拟校验缓存等。
+     * @param {string[]} removedFieldNames 已从 schema 中移除的字段名
+     */
+    protected onRemovedSchemaFields(_removedFieldNames: string[]): void;
+    /**
+     * store 更新后对比前后 `schema` 的 fieldName 集合，对已从 schema 中移除的字段清空 vee-validate 值与错误，
+     * 避免 `removeFields` / 删项后 `getValues` 仍带出旧字段。
+     */
     private updateState;
 }

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

@@ -0,0 +1,198 @@
+import { FormState, GenericObject, ResetFormOpts, ValidationOptions } from 'vee-validate';
+import { FormApi } from '../formApi';
+import { TtFormProps } from '../types';
+import { GroupFormApiOptions, GroupFormSchema } from './types';
+import { InsertPosition } from './utils';
+/**
+ * @description 分组表单 API 类，继承 {@link FormApi}，封装分组场景下的校验、导航错误计数、
+ */
+export declare class GroupFormApi extends FormApi {
+    /** 是否启用虚拟化（IntersectionObserver 懒渲染） */
+    readonly enableVirtual: boolean;
+    /** 是否显示悬浮导航锚点 */
+    readonly showNav: boolean;
+    /** 校验失败时是否自动滚动到第一个有错误的分组 */
+    readonly enableScrollToFirstError: boolean;
+    /** 各分组折叠状态（key → 是否折叠） */
+    readonly collapseStates: Record<string, boolean>;
+    /** 导航各分组的错误数量，validate 后自动更新 */
+    readonly navErrorCounts: Record<string, number>;
+    /** 共享错误缓存，validate 写入 → LazyFormField 挂载时读取恢复 */
+    readonly errorCacheMap: Map<string, string>;
+    /** 重置信号，递增时通知所有 LazyFormField 清空 cachedError */
+    readonly resetSignal: import('vue').Ref<number, number>;
+    /** 初始传入的分组 schema（用于 fallback） */
+    private readonly _initialGroupSchema;
+    /** 初始展平后的 flatSchema（用于 fallback） */
+    private readonly _initialFlatSchema;
+    /** 各分组 key → 其直属字段名（不含子分组的字段） */
+    private _groupFieldMap;
+    /** 是否已执行过 validate，用于控制导航栏错误同步是否需要重新校验未挂载字段 */
+    private _hasValidated;
+    /** VirtualGroupForm 组件实例引用，由 useGroupForm 的 h() 渲染时赋值 */
+    groupFormRef: import('vue').Ref<{
+        scrollToGroup?: ((key: string) => void) | undefined;
+    } | null, {
+        scrollToGroup?: (key: string) => void;
+    } | {
+        scrollToGroup?: ((key: string) => void) | undefined;
+    } | null>;
+    /**
+     * @param {TtFormProps} formProps - 底层表单配置（已展平的 schema、layout 等）
+     * @param {GroupFormApiOptions} groupOptions - 分组场景专属配置
+     */
+    constructor(formProps: TtFormProps, groupOptions: GroupFormApiOptions);
+    /**
+     * @description 分组表单以 `groupSchema` 展平结果为字段全集。仅依赖 store 中的 `schema` 时，若与 `groupSchema` 不同步（例如外部只 `setState` 了 `groupSchema`、或合并顺序导致 `schema` 滞后），`setValues` 默认过滤会误删合法字段；此处优先按 `groupSchema` 展平生成白名单。
+     * @returns {string[]} 允许 `setValues` 写入的 fieldName 列表
+     */
+    protected getFieldNamesForSetValuesFilter(): string[];
+    /**
+     * @description schema 中移除字段后清空虚拟列表场景下缓存的校验错误，与 {@link FormApi} 中清空 vee 值保持一致。
+     * @param {string[]} removedFieldNames 已移除的 fieldName 列表
+     */
+    protected onRemovedSchemaFields(removedFieldNames: string[]): void;
+    /**
+     * @description 校验表单（含未挂载的虚拟字段），支持通过第二个参数控制是否滚动到第一个错误分组
+     * @param {Partial<ValidationOptions>} [opts] - 原始 validate 选项
+     * @param {boolean} [scrollToError] - 是否滚动到第一个错误分组，不传时使用全局配置 enableScrollToFirstError
+     * @returns {Promise<{valid: boolean; errors: Record<string, string>; results?: any}>} 校验结果
+     * @example
+     * await formApi.validate();
+     * @example
+     * await formApi.validate(undefined, true);
+     * @example
+     * await formApi.validate(undefined, false);
+     */
+    validate(opts?: Partial<ValidationOptions>, scrollToError?: boolean): Promise<import('vee-validate').FormValidationResult<GenericObject, GenericObject>>;
+    /**
+     * @description 校验并提交表单
+     * @returns {Promise<any>} 提交结果，校验失败时返回 undefined
+     */
+    validateAndSubmitForm(): Promise<import('../../../../../../utils/src').Recordable<any> | undefined>;
+    /**
+     * @description 重置表单（含清空虚拟字段错误缓存和导航错误计数）
+     * @param {Partial<FormState<GenericObject>>} [state] - 重置后的表单状态
+     * @param {Partial<ResetFormOpts>} [opts] - 重置选项
+     */
+    resetForm(state?: Partial<FormState<GenericObject>>, opts?: Partial<ResetFormOpts>): Promise<void>;
+    /**
+     * @description 重置校验状态（含清空虚拟字段错误缓存和导航错误计数）
+     */
+    resetValidate(): Promise<void>;
+    /**
+     * @description 获取表单值
+     * @param {boolean} [isGroup] - 为 true 时返回按分组 key 嵌套的对象，默认 false 返回扁平值
+     * @returns {Promise<T>} 表单值
+     */
+    getValues<T = Record<string, any>>(isGroup?: boolean): Promise<T>;
+    /**
+     * @description 滚动到指定分组（外部可通过 formApi.scrollToGroup 调用）
+     * @param {string} key - 分组 key
+     */
+    scrollToGroup(key: string): void;
+    /**
+     * @description 切换分组折叠状态
+     * @param {string} key - 分组 key
+     */
+    toggleCollapse(key: string): void;
+    /**
+     * @description 按当前 store 中的 groupSchema（若无则用初始 schema）重置折叠状态：
+     *   先清空已有 key，再按 `defaultCollapsed` 写入默认值。
+     *   用于同一 `formApi` 实例下分组表单卸载后再次挂载（如弹框 `destroy-on-close`）时，避免沿用上次折叠状态。
+     */
+    resetCollapseStatesToDefault(): void;
+    /**
+     * @description 动态更新分组 schema（同时更新 UI 渲染和底层字段注册）
+     * @param {GroupFormSchema[]} newSchema - 新的分组 schema
+     */
+    updateGroupSchema(newSchema: GroupFormSchema[]): void;
+    /**
+     * @description 在指定分组中增量插入字段，无需全量重建 schema。
+     *   支持在 group 的 children 或 row 的 children 中定位插入
+     * @param {string} groupKey - 目标分组的 key
+     * @param {GroupFormSchema[]} fields - 要插入的字段或子结构（字段、slot、row 等均可）
+     * @param {InsertPosition} [position] - 插入位置，省略则追加到分组末尾
+     * @example
+     * formApi.appendFields('basic', [newField], { before: 'phone' });
+     * @example
+     * formApi.appendFields('basic', [newField], { after: 'email' });
+     * @example
+     * formApi.appendFields('basic', [newField]);
+     */
+    appendFields(groupKey: string, fields: GroupFormSchema[], position?: InsertPosition): void;
+    /**
+     * @description 按标识从 groupSchema 树中移除节点，无需全量重建 schema。
+     *   支持匹配 fieldName（普通字段 / row 内字段）和 slot 的字符串 content
+     * @param {string[]} fieldNames - 要移除的标识列表（fieldName 或 slot content 字符串）
+     * @example
+     * formApi.removeFields(['v_phone', 'v_email']);
+     */
+    removeFields(fieldNames: string[]): void;
+    /**
+     * @description 合并 vee-validate 实时 errors 与虚拟列表未挂载字段的 errorCacheMap，用于导航徽标与输入联动
+     * @returns {Record<string, string>} 合并后的错误映射
+     */
+    mergeErrorsForNav(): Record<string, string>;
+    /**
+     * @description 同步导航错误计数。
+     *   当开启虚拟列表且已执行过 validate 时，会重新对未挂载字段做可见性检查和校验，
+     *   确保 dependencies 条件变化后错误计数实时更新。
+     */
+    syncNavErrorCountsFromForm(): Promise<void>;
+    /**
+     * @description 清空导航各分组的错误计数
+     */
+    clearNavErrorCounts(): void;
+    /**
+     * @description 校验失败后展开包含错误的分组，并滚动到该分组标题
+     * @param {Record<string, string>} errors - 合并后的所有错误
+     */
+    scrollToFirstErrorGroup(errors: Record<string, string>): void;
+    /**
+     * @description 对单个字段值执行 rules 校验（纯数据，不挂载组件）。
+     *   支持字符串规则（"required" / "selectRequired"）和 Zod schema。
+     * @param {unknown} value - 字段值
+     * @param {FormSchemaRuleType | undefined} rules - 校验规则
+     * @param {string} fieldName - 字段名
+     * @returns {Promise<string | undefined>} 错误信息，无错误返回 undefined
+     */
+    private _validateFieldValue;
+    /**
+     * @description 检查字段的 dependencies 条件，判断字段在当前值下是否应该被校验。
+     *   与 FormField.vue 保持一致：visible = !hide && isIf && isShow
+     * @param {FormSchema} schema - 字段 schema
+     * @param {Record<string, any>} values - 当前表单值
+     * @returns {Promise<boolean>} 字段是否可见
+     */
+    private _isFieldVisible;
+    /**
+     * @description 对所有未挂载的字段做纯值校验，补充到 validate 结果中，
+     *   并将错误写入 errorCacheMap 以便 LazyFormField 挂载时恢复。
+     *   会跳过因 dependencies.if 条件不满足而不应渲染的字段，与原始表单校验行为一致。
+     * @param {object} validateResult - 父类 validate 返回的校验结果
+     * @returns {Promise<object>} 补充未挂载字段错误后的校验结果
+     */
+    private _validateUnmountedFields;
+    /**
+     * @description 清空所有缓存的错误并递增重置信号
+     */
+    private _clearAllCachedErrors;
+    /**
+     * @description 递归构建各分组 key → 其直属字段名的映射
+     * @param {GroupFormSchema[]} schemas - 分组 schema 数组
+     * @param {string} [parentKey] - 父分组 key
+     */
+    private _buildGroupFieldMap;
+    /**
+     * @description 根据错误映射更新导航各分组的错误计数
+     * @param {Record<string, string>} errors - 字段错误映射
+     */
+    private _updateNavErrorCounts;
+    /**
+     * @description 根据错误字段找到第一个包含错误的分组 key（按 schema 定义顺序）
+     * @param {Record<string, string>} errors - 错误字段映射
+     * @returns {string | undefined} 第一个有错误的分组 key
+     */
+    private _findFirstErrorGroupKey;
+}

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

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

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

@@ -7,8 +7,8 @@ import { InjectionKey, Ref } from 'vue';
  */
 export declare const VIRTUAL_ERROR_CACHE_KEY: InjectionKey<Map<string, string>>;
 /**
- * 重置信号（递增计数器），resetForm / resetValidate 时 +1。
- * LazyFormField watch 此值来清空自身 cachedError。
+ * 重置信号（递增计数器），resetForm / resetValidate 清空虚拟字段错误缓存时 +1。
+ * useGroupForm 中 watch 此值以同步导航错误计数；LazyFormField 不依赖 inject 该 key。
  */
 export declare const VIRTUAL_RESET_SIGNAL_KEY: InjectionKey<Ref<number>>;
 /**

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

@@ -145,3 +145,20 @@ export interface GroupSectionProps {
     virtualEstimateHeight?: number;
 }
 export type AutoScrollPosition = "top" | "bottom";
+/**
+ * @description GroupFormApi 构造函数的分组配置选项
+ * @property {GroupFormSchema[]} groupSchema - 分组 schema 树形结构
+ * @property {boolean} [enableVirtual] - 是否启用虚拟化（IntersectionObserver 懒渲染），默认 true
+ * @property {boolean} [showNav] - 是否显示悬浮导航锚点，默认 true
+ * @property {boolean} [enableScrollToFirstError] - 校验失败时是否自动滚动到第一个有错误的分组，默认 true
+ */
+export interface GroupFormApiOptions {
+    /** 分组 schema 树形结构 */
+    groupSchema: GroupFormSchema[];
+    /** 是否启用虚拟化（IntersectionObserver 懒渲染），默认 true */
+    enableVirtual?: boolean;
+    /** 是否显示悬浮导航锚点，默认 true */
+    showNav?: boolean;
+    /** 校验失败时是否自动滚动到第一个有错误的分组，默认 true */
+    enableScrollToFirstError?: boolean;
+}

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

@@ -1,5 +1,15 @@
 import { ExtendedFormApi } from '../types';
 import { UseGroupFormOptions } from './types';
+/**
+ * @description 创建分组表单：返回可渲染的包装组件、扩展后的表单 API，以及分组折叠状态对象。
+ * @param {UseGroupFormOptions} options - 分组 schema 与表单配置；`schema` 为树形结构，内部会展平后写入底层 store
+ * @returns {readonly [import("vue").DefineComponent, ExtendedFormApi, Record<string, boolean>]} 元组：`[GroupForm, formApi, collapseStates]`
+ * @example
+ * const [GroupForm, formApi] = useGroupForm({
+ *   schema: [{ type: "group", key: "basic", title: "基础", children: [{ fieldName: "name", component: "ElInput", label: "姓名" }] }],
+ *   layout: "horizontal",
+ * });
+ */
 export declare function useGroupForm(options: UseGroupFormOptions): readonly [import('vue').DefineComponent<{}, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
     [key: string]: any;
 }>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>, ExtendedFormApi, Record<string, boolean>];

package/dist/components/tt-modal-form/props.d.ts

@@ -11,6 +11,8 @@ export type TtModalFormProps = {
     infoApi?: (...arg: any[]) => Promise<any>;
     /** 详情接口前置钩子 */
     infoApiBefore?: (val: Recordable) => Promise<Recordable> | Recordable;
+    /** 详情接口后置钩子 */
+    infoApiAfter?: (val: Recordable) => Promise<Recordable> | Recordable;
     /** 保存接口前置钩子 */
     saveApiBefore?: (val: Recordable) => Promise<Recordable> | Recordable;
     /** 表单静态数据回显的key */