@dazhicheng/ui 1.5.44 → 1.5.47

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

@@ -32,6 +32,23 @@ export declare class FormApi {
     isFieldValid(fieldName: string): Promise<boolean>;
     merge(formApi: FormApi): any;
     mount(formActions: FormActions, componentRefMap: Map<string, unknown>): void;
+    /**
+     * @description 增量追加字段到 schema 中，支持通过 position 指定插入位置
+     * @param {FormSchema[]} fields - 要插入的字段 schema 数组
+     * @param {object} [position] - 插入位置，省略则追加到末尾
+     * @param {string} [position.before] - 在指定 fieldName 之前插入
+     * @param {string} [position.after] - 在指定 fieldName 之后插入
+     * @example
+     * formApi.appendFields([{ fieldName: 'phone', component: 'ElInput', label: '手机号' }]);
+     * @example
+     * formApi.appendFields([newField], { after: 'email' });
+     * @example
+     * formApi.appendFields([newField], { before: 'name' });
+     */
+    appendFields(fields: FormSchema[], position?: {
+        before?: string;
+        after?: string;
+    }): void;
     /**
      * 根据字段名移除表单项
      * @param fields

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

@@ -7,8 +7,8 @@ import { FormSchema } from '../types';
  * @property {FormSchema["rules"]} [rules] - 字段校验规则
  * @property {boolean} [virtual] - 是否启用虚拟化（LazyFormField）
  * @property {Element | null} [scrollElement] - 虚拟化滚动容器
- * @property {string} [virtualRootMargin] - IntersectionObserver rootMargin
- * @property {number} [virtualEstimateHeight] - 预估占位高度
+ * @property {string} [rootMargin] - IntersectionObserver rootMargin
+ * @property {number} [estimateFieldHeight] - 预估占位高度
  */
 export declare const FieldRenderer: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
     /** mergeFieldConfig 合并后的完整字段配置 */
@@ -32,12 +32,12 @@ export declare const FieldRenderer: import('vue').DefineComponent<import('vue').
         default: null;
     };
     /** IntersectionObserver rootMargin */
-    virtualRootMargin: {
+    rootMargin: {
         type: StringConstructor;
         default: string;
     };
     /** 预估占位高度（px） */
-    virtualEstimateHeight: {
+    estimateFieldHeight: {
         type: NumberConstructor;
         default: number;
     };
@@ -63,19 +63,19 @@ export declare const FieldRenderer: import('vue').DefineComponent<import('vue').
         default: null;
     };
     /** IntersectionObserver rootMargin */
-    virtualRootMargin: {
+    rootMargin: {
         type: StringConstructor;
         default: string;
     };
     /** 预估占位高度（px） */
-    virtualEstimateHeight: {
+    estimateFieldHeight: {
         type: NumberConstructor;
         default: number;
     };
 }>> & Readonly<{}>, {
     rules: import('../types').FormSchemaRuleType | undefined;
     virtual: boolean;
+    rootMargin: string;
+    estimateFieldHeight: number;
     scrollElement: Element | null;
-    virtualRootMargin: string;
-    virtualEstimateHeight: number;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

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

@@ -2,7 +2,9 @@ import { GroupFormSectionProps } from './types';
 /**
  * @description 滚动到指定分组（通过 data-group-key 定位 DOM）。
  *   滚动期间暂停 LazyFormField 渲染，滚动结束后才恢复，
- *   避免途经字段挂载导致高度变化引起布局抖动
+ *   避免途经字段挂载导致高度变化引起布局抖动。
+ *   虚拟滚动场景下，通过 ResizeObserver 监听容器高度变化，
+ *   在字段渲染导致高度变化时自动校正位置，高度稳定后停止。
  * @param {string} key 分组 key
  */
 declare function scrollToGroup(key: string): void;

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

@@ -11,9 +11,9 @@ declare const __VLS_component: import('vue').DefineComponent<GroupSectionProps,
     layout: string;
     globalCommonConfig: import('../types').FormCommonConfig;
     virtual: boolean;
+    rootMargin: string;
+    estimateFieldHeight: number;
     scrollElement: Element | null;
-    virtualRootMargin: string;
-    virtualEstimateHeight: number;
     depth: number;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;

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

@@ -1,55 +1,78 @@
 import { FormState, GenericObject, ResetFormOpts, ValidationOptions } from 'vee-validate';
+import { Ref } from 'vue';
 import { FormApi } from '../formApi';
 import { TtFormProps } from '../types';
-import { AutoScrollPosition, GroupFormApiOptions, GroupFormSchema, UseGroupFormNavAnchorProps } from './types';
+import { GroupFormApiOptions, GroupFormSchema, GroupFormState, UseGroupFormNavAnchorProps } from './types';
 import { InsertPosition } from './utils';
 /**
  * @description 分组表单 API 类，继承 {@link FormApi}，封装分组场景下的校验、导航错误计数、
  */
 export declare class GroupFormApi extends FormApi {
     /** 是否启用虚拟化（IntersectionObserver 懒渲染） */
-    readonly enableVirtual: boolean;
-    /** 导航锚点配置（含 show、title 等），由构造参数合并默认值后保存 */
-    readonly navAnchorProps: Required<Pick<UseGroupFormNavAnchorProps, "show">> & UseGroupFormNavAnchorProps;
-    /** 校验失败时是否自动滚动到第一个有错误的分组 */
-    readonly enableScrollToFirstError: boolean;
+    readonly virtual: boolean;
+    /** 构造时的导航锚点默认配置，作为 store 未设置时的 fallback */
+    private readonly _defaultNavAnchorProps;
+    /** 校验失败时是否自动滚动到第一个有错误的分组，默认 true */
+    private readonly _scrollToFirstError;
     /** 滚动容器高度 */
-    readonly containerHeight: number | string;
+    private readonly _containerHeight;
     /** IntersectionObserver rootMargin */
-    readonly rootMargin: string;
+    private readonly _rootMargin;
     /** 预估每个表单项高度（px） */
-    readonly estimateFieldHeight: number;
-    /** 初始化后自动滚动到的分组位置 */
-    readonly autoScrollToGroup: AutoScrollPosition;
+    private readonly _estimateFieldHeight;
+    /** 滚动到分组时的顶部偏移量（px），补偿固定元素遮挡 */
+    private readonly _scrollOffset;
     /** 各分组折叠状态（key → 是否折叠） */
     readonly collapseStates: Record<string, boolean>;
+    /** 当前被 ifShow 隐藏的分组 key 集合 */
+    readonly hiddenGroupKeys: Set<string>;
     /** 导航各分组的错误数量，validate 后自动更新 */
     readonly navErrorCounts: Record<string, number>;
     /** 共享错误缓存，validate 写入 → LazyFormField 挂载时读取恢复 */
     readonly errorCacheMap: Map<string, string>;
     /** 重置信号，递增时通知所有 LazyFormField 清空 cachedError */
-    readonly resetSignal: import('vue').Ref<number, number>;
+    readonly resetSignal: Ref<number, number>;
     /** 初始传入的分组 schema（用于 fallback） */
     private readonly _initialGroupSchema;
     /** 初始展平后的 flatSchema（用于 fallback） */
     private readonly _initialFlatSchema;
     /** 各分组 key → 其直属字段名（不含子分组的字段） */
     private _groupFieldMap;
+    /** 字段名 → 所属分组 key 的反向映射，用于快速判断字段是否属于隐藏分组 */
+    private _fieldToGroupKey;
+    /** 子分组 key → 父分组 key 的映射，用于递归向上查找祖先分组是否被隐藏 */
+    private _groupParentMap;
     /** 是否已执行过 validate，用于控制导航栏错误同步是否需要重新校验未挂载字段 */
     private _hasValidated;
     /** VirtualGroupForm 组件实例引用，由 useGroupForm 的 h() 渲染时赋值 */
-    groupFormRef: import('vue').Ref<{
+    groupFormRef: Ref<{
         scrollToGroup?: ((key: string) => void) | undefined;
     } | null, {
         scrollToGroup?: (key: string) => void;
     } | {
         scrollToGroup?: ((key: string) => void) | undefined;
     } | null>;
+    /**
+     * @description 响应式读取 store 状态，由 useGroupForm 在运行时注入实现
+     * @param {Function} [selector] - 可选的状态选择器
+     * @returns {Readonly<Ref<T>>} 响应式状态引用
+     */
+    useStore: <T = GroupFormState>(selector?: (state: GroupFormState) => T) => Readonly<Ref<T>>;
     /**
      * @param {TtFormProps} formProps - 底层表单配置（已展平的 schema、layout 等）
      * @param {GroupFormApiOptions} groupOptions - 分组场景专属配置
      */
     constructor(formProps: TtFormProps, groupOptions: GroupFormApiOptions);
+    /**
+     * @description 从 store 响应式读取 navAnchorProps，支持通过 setState({ navAnchorProps }) 动态修改
+     * @returns {Required<Pick<UseGroupFormNavAnchorProps, "show">> & UseGroupFormNavAnchorProps} 导航锚点配置
+     */
+    get navAnchorProps(): Required<Pick<UseGroupFormNavAnchorProps, "show">> & UseGroupFormNavAnchorProps;
+    /**
+     * @description 覆盖基类 setState，扩展支持 GroupFormExtraState 中的字段（navAnchorProps、groupSchema 等）
+     * @param {Partial<GroupFormState> | ((prev: GroupFormState) => Partial<GroupFormState>)} stateOrFn - 新状态或更新函数
+     */
+    setState(stateOrFn: ((prev: GroupFormState) => Partial<GroupFormState>) | Partial<GroupFormState>): void;
     /**
      * @description 分组表单以 `groupSchema` 展平结果为字段全集。仅依赖 store 中的 `schema` 时，若与 `groupSchema` 不同步（例如外部只 `setState` 了 `groupSchema`、或合并顺序导致 `schema` 滞后），`setValues` 默认过滤会误删合法字段；此处优先按 `groupSchema` 展平生成白名单。
      * @returns {string[]} 允许 `setValues` 写入的 fieldName 列表
@@ -63,7 +86,7 @@ export declare class GroupFormApi extends FormApi {
     /**
      * @description 校验表单（含未挂载的虚拟字段），支持通过第二个参数控制是否滚动到第一个错误分组
      * @param {Partial<ValidationOptions>} [opts] - 原始 validate 选项
-     * @param {boolean} [scrollToError] - 是否滚动到第一个错误分组，不传时使用全局配置 enableScrollToFirstError
+     * @param {boolean} [scrollToError] - 是否滚动到第一个错误分组，不传时使用全局配置 scrollToFirstError
      * @returns {Promise<{valid: boolean; errors: Record<string, string>; results?: any}>} 校验结果
      * @example
      * await formApi.validate();
@@ -104,6 +127,18 @@ export declare class GroupFormApi extends FormApi {
      * @param {string} key - 分组 key
      */
     toggleCollapse(key: string): void;
+    /**
+     * @description 设置分组的可见性状态，由 GroupSection 组件在 ifShow 求值后调用
+     * @param {string} key - 分组 key
+     * @param {boolean} visible - 是否可见
+     */
+    setGroupVisible(key: string, visible: boolean): void;
+    /**
+     * @description 判断字段是否属于被 ifShow 隐藏的分组（含递归祖先分组）
+     * @param {string} fieldName - 字段名
+     * @returns {boolean} 是否属于隐藏分组
+     */
+    private _isFieldInHiddenGroup;
     /**
      * @description 按当前 store 中的 groupSchema（若无则用初始 schema）重置折叠状态：
      *   先清空已有 key，再按 `defaultCollapsed` 写入默认值。
@@ -111,24 +146,23 @@ export declare class GroupFormApi extends FormApi {
      */
     resetCollapseStatesToDefault(): void;
     /**
-     * @description 动态更新分组 schema（同时更新 UI 渲染和底层字段注册）
-     * @param {GroupFormSchema[]} newSchema - 新的分组 schema
+     * @description 全量应用分组 schema 树到 store（扁平 schema、groupSchema、分组字段映射、折叠默认值）。
      */
-    updateGroupSchema(newSchema: GroupFormSchema[]): void;
+    _applyGroupSchema(newSchema: GroupFormSchema[]): void;
     /**
-     * @description 在指定分组中增量插入字段，无需全量重建 schema。
-     *   支持在 group 的 children 或 row 的 children 中定位插入
-     * @param {string} groupKey - 目标分组的 key
+     * @description 增量插入字段到分组 schema 树中，无需全量重建 schema。
+     *   通过 position 的 before/after 在整棵树中递归查找锚点并就地插入；
+     *   不传 position 时追加到顶层 schema 末尾。
      * @param {GroupFormSchema[]} fields - 要插入的字段或子结构（字段、slot、row 等均可）
-     * @param {InsertPosition} [position] - 插入位置，省略则追加到分组末尾
+     * @param {InsertPosition} [position] - 插入位置，省略则追加到顶层末尾
      * @example
-     * formApi.appendFields('basic', [newField], { before: 'phone' });
+     * formApi.appendFields([newField], { before: 'phone' });
      * @example
-     * formApi.appendFields('basic', [newField], { after: 'email' });
+     * formApi.appendFields([newField], { after: 'email' });
      * @example
-     * formApi.appendFields('basic', [newField]);
+     * formApi.appendFields([newGroup]);
      */
-    appendFields(groupKey: string, fields: GroupFormSchema[], position?: InsertPosition): void;
+    appendFields(fields: GroupFormSchema[], position?: InsertPosition): void;
     /**
      * @description 按标识从 groupSchema 树中移除节点，无需全量重建 schema。
      *   支持匹配 fieldName（普通字段 / row 内字段）和 slot 的字符串 content
@@ -141,7 +175,7 @@ export declare class GroupFormApi extends FormApi {
      * @description 合并 vee-validate 实时 errors 与虚拟列表未挂载字段的 errorCacheMap，用于导航徽标与输入联动
      * @returns {Record<string, string>} 合并后的错误映射
      */
-    mergeErrorsForNav(): Record<string, string>;
+    private _mergeErrorsForNav;
     /**
      * @description 同步导航错误计数。
      *   当开启虚拟列表且已执行过 validate 时，会重新对未挂载字段做可见性检查和校验，
@@ -151,12 +185,18 @@ export declare class GroupFormApi extends FormApi {
     /**
      * @description 清空导航各分组的错误计数
      */
-    clearNavErrorCounts(): void;
+    private _clearNavErrorCounts;
     /**
      * @description 校验失败后展开包含错误的分组，并滚动到该分组标题
      * @param {Record<string, string>} errors - 合并后的所有错误
      */
-    scrollToFirstErrorGroup(errors: Record<string, string>): void;
+    private _scrollToFirstErrorGroup;
+    /**
+     * @description 从校验结果中剔除属于隐藏分组的字段错误，并重新判定 valid 状态
+     * @param {object} result - 校验结果
+     * @returns {object} 过滤后的校验结果
+     */
+    private _stripHiddenGroupErrors;
     /**
      * @description 对单个字段值执行 rules 校验（纯数据，不挂载组件）。
      *   支持字符串规则（"required" / "selectRequired"）和 Zod schema。

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

@@ -35,3 +35,8 @@ export interface RenderScheduler {
  */
 export declare function createRenderScheduler(batchSize?: number): RenderScheduler;
 export declare const RENDER_SCHEDULER_KEY: InjectionKey<RenderScheduler>;
+/**
+ * 分组可见性回调注入 key，由 GroupForm.vue provide，GroupSection.vue inject。
+ * 当分组的 ifShow 求值结果变化时，GroupSection 调用此回调通知 API 层同步隐藏状态。
+ */
+export declare const GROUP_VISIBILITY_CALLBACK_KEY: InjectionKey<(key: string, visible: boolean) => void>;

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

@@ -1,5 +1,6 @@
-import { ExtendedFormApi, FormActions, FormCommonConfig, FormLayout, FormSchema, FormSlotSchema, TtFormProps, WrapperClassType } from '../types';
+import { FormActions, FormCommonConfig, FormLayout, FormSchema, FormSlotSchema, TtFormProps, WrapperClassType } from '../types';
 import { TtNavAnchorProps } from '../../../tt-nav-anchor';
+import { GroupFormApi } from './groupFormApi';
 export type CollapsibleType = boolean | ((values: Record<string, any>, actions: FormActions) => boolean | PromiseLike<boolean>);
 /** 控制 group / row / slot 是否显示，支持布尔值或函数（接收表单值与 formActions，可返回 Promise） */
 export type IfShowConditionType = boolean | ((values: Record<string, any>, actions: FormActions) => boolean | PromiseLike<boolean>);
@@ -72,11 +73,15 @@ export interface UseGroupFormOptions extends Omit<TtFormProps, "schema" | "showD
      * `badgeCounts` 由 formApi 维护，无需在此传入。
      */
     navAnchorProps?: UseGroupFormNavAnchorProps;
-    /** 自动滚动到指定分组，默认 'top' */
-    autoScrollToGroup?: AutoScrollPosition;
-    /** 校验失败时是否自动滚动到第一个有错误的分组，默认 true */
-    scrollToFirstError?: boolean;
+    /** 滚动到分组时的顶部偏移量（px），用于补偿页面顶部固定元素（如 header）的遮挡，默认 0 */
+    scrollOffset?: number;
 }
+export type GroupFormExtraState = Partial<Pick<UseGroupFormOptions, "virtual" | "navAnchorProps" | "containerHeight" | "rootMargin" | "estimateFieldHeight" | "scrollOffset">> & {
+    /** 分组 schema 树形结构 */
+    groupSchema?: GroupFormSchema[];
+};
+/** 分组表单完整 store 状态类型 */
+export type GroupFormState = TtFormProps & GroupFormExtraState;
 /** LazyFormField 组件 props */
 export interface LazyFormFieldProps {
     /** 传给 FormField 的完整 props（通过 v-bind 透传） */
@@ -97,13 +102,13 @@ export interface LazyFormFieldProps {
     skeletonAnimated?: boolean;
 }
 /**
- * 分组表单组件 props：仅保留 `formApi`（数据入口）和少量模板侧可覆盖项。
- * 其余内部数据（collapseStates、errorCacheMap、resetSignal、virtual 等）均从 `formApi`（GroupFormApi 实例）读取。
+ * 分组表单组件 props：`formApi` 为必传数据入口，其余字段均可在模板侧覆盖（优先级：模板 props > store）。
+ * 类型复用 UseGroupFormOptions 中的同名字段。
  */
-export interface GroupFormSectionProps {
+export type GroupFormSectionProps = Partial<Pick<UseGroupFormOptions, "virtual" | "scrollToFirstError" | "containerHeight" | "rootMargin" | "estimateFieldHeight">> & {
     /** 表单 API（必传，所有内部数据的入口） */
-    formApi: ExtendedFormApi;
-    /** 模板侧覆盖：导航锚点配置（与 api.navAnchorProps 合并，模板优先） */
+    formApi: GroupFormApi;
+    /** 模板侧覆盖：导航锚点配置（与 store.navAnchorProps 合并，模板优先） */
     navAnchorProps?: GroupFormNavAnchorProps;
     /** 模板侧覆盖：布局方向 */
     layout?: FormLayout;
@@ -111,7 +116,7 @@ export interface GroupFormSectionProps {
     compact?: boolean;
     /** 模板侧覆盖：通用配置（与 store.commonConfig 合并） */
     commonConfig?: FormCommonConfig;
-}
+};
 /** GroupSection 递归组件 props */
 export interface GroupSectionProps {
     /** 当前节点的 schema（分组 / 行容器 / 字段） */
@@ -132,39 +137,17 @@ export interface GroupSectionProps {
     virtual?: boolean;
     /** 虚拟化时滚动容器引用 */
     scrollElement?: Element | null;
-    /** 虚拟化时 IntersectionObserver rootMargin */
-    virtualRootMargin?: string;
-    /** 虚拟化时预估表单项高度（px） */
-    virtualEstimateHeight?: number;
+    /** IntersectionObserver rootMargin，控制提前渲染的距离 */
+    rootMargin?: string;
+    /** 预估每个表单项高度（px），用于占位 */
+    estimateFieldHeight?: number;
 }
-export type AutoScrollPosition = "top" | "bottom";
 /**
- * @description GroupFormApi 构造函数的分组配置选项
- * @property {GroupFormSchema[]} groupSchema - 分组 schema 树形结构
- * @property {boolean} [enableVirtual] - 是否启用虚拟化（IntersectionObserver 懒渲染），默认 true
- * @property {UseGroupFormNavAnchorProps} [navAnchorProps] - 导航锚点配置（含 show、title 等），默认 `{ show: true }`
- * @property {boolean} [enableScrollToFirstError] - 校验失败时是否自动滚动到第一个有错误的分组，默认 true
- * @property {number | string} [containerHeight] - 滚动容器高度，默认 '100%'
- * @property {string} [rootMargin] - IntersectionObserver rootMargin，默认 '400px 0px'
- * @property {number} [estimateFieldHeight] - 预估每个表单项高度（px），默认 52
- * @property {AutoScrollPosition} [autoScrollToGroup] - 初始化后自动滚动到的分组位置，默认 'top'
+ * @description GroupFormApi 构造函数的分组配置选项，复用 UseGroupFormOptions 中同名字段的类型定义，
+ *   额外增加 `groupSchema`（由 useGroupForm 从 `schema` 转换而来）。
  */
-export interface GroupFormApiOptions {
-    /** 分组 schema 树形结构 */
+export type GroupFormApiOptions = Pick<UseGroupFormOptions, "virtual" | "navAnchorProps" | "scrollToFirstError" | "containerHeight" | "rootMargin" | "estimateFieldHeight" | "scrollOffset"> & {
+    /** 分组 schema 树形结构（由 useGroupForm 从 options.schema 传入） */
     groupSchema: GroupFormSchema[];
-    /** 是否启用虚拟化（IntersectionObserver 懒渲染），默认 true */
-    enableVirtual?: boolean;
-    /** 导航锚点配置（含 show、title 等），默认 `{ show: true }`；`items`、`modelValue`、`badgeCounts` 由内部注入 */
-    navAnchorProps?: UseGroupFormNavAnchorProps;
-    /** 校验失败时是否自动滚动到第一个有错误的分组，默认 true */
-    enableScrollToFirstError?: boolean;
-    /** 滚动容器高度，默认 '100%' */
-    containerHeight?: number | string;
-    /** IntersectionObserver rootMargin，控制提前渲染的距离，默认 '400px 0px' */
-    rootMargin?: string;
-    /** 预估每个表单项高度（px），用于占位，默认 52 */
-    estimateFieldHeight?: number;
-    /** 初始化后自动滚动到的分组位置，默认 'top' */
-    autoScrollToGroup?: AutoScrollPosition;
-}
+};
 export {};

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

@@ -1,7 +1,7 @@
 import { DefineComponent } from 'vue';
-import { ExtendedFormApi } from '../types';
+import { GroupFormApi } from './groupFormApi';
 import { UseGroupFormOptions } from './types';
 /**
  * @description 返回可渲染的包装组件、扩展后的表单 API，以及分组折叠状态对象。
  */
-export declare function useGroupForm(options: UseGroupFormOptions): readonly [DefineComponent<Partial<Omit<UseGroupFormOptions, "schema">>>, ExtendedFormApi];
+export declare function useGroupForm(options: UseGroupFormOptions): readonly [DefineComponent<Partial<Omit<UseGroupFormOptions, "schema">>>, GroupFormApi];

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

@@ -69,6 +69,20 @@ export interface InsertPosition {
  * insertFieldsInGroup(schema, 'basic', [newField], { after: 'v_age' });
  */
 export declare function insertFieldsInGroup(schemas: GroupFormSchema[], groupKey: string, fields: GroupFormSchema[], position?: InsertPosition): boolean;
+/**
+ * @description 在整棵 groupSchema 树中递归查找 position 锚点并就地插入字段，不需要指定 groupKey。
+ *   依次在每层 children 中查找匹配，找到后插入并返回 true；未找到则继续递归子分组。
+ *   不传 position 时不执行任何操作（由调用方处理追加到末尾的逻辑）。
+ * @param {GroupFormSchema[]} schemas - 分组 schema 树（会被原地修改）
+ * @param {GroupFormSchema[]} fields - 要插入的字段
+ * @param {InsertPosition} position - 插入位置
+ * @returns {boolean} 是否找到锚点并完成插入
+ * @example
+ * insertFieldsByPosition(schema, [newField], { before: 'phone' });
+ * @example
+ * insertFieldsByPosition(schema, [newField], { after: 'v_email' });
+ */
+export declare function insertFieldsByPosition(schemas: GroupFormSchema[], fields: GroupFormSchema[], position: InsertPosition): boolean;
 /**
  * 从 groupSchema 树中递归移除指定 fieldName 或 slot content 的节点
  * @param {GroupFormSchema[]} schemas - 分组 schema 树（会被原地修改）

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

@@ -388,7 +388,12 @@ export interface TtFormProps<T extends BaseFormComponentType = BaseFormComponent
      */
     submitOnEnter?: boolean;
 }
-export type ExtendedFormApi = Omit<FormApi, "getValues" | "validate"> & {
+export type ExtendedFormApi = Omit<FormApi, "getValues" | "validate" | "setState"> & {
+    /**
+     * @description 设置表单状态，支持扩展字段（如 navAnchorProps、groupSchema 等）
+     * @param {Partial<TtFormProps & Record<string, any>> | ((prev: TtFormProps & Record<string, any>) => Partial<TtFormProps & Record<string, any>>)} stateOrFn - 新状态或更新函数
+     */
+    setState: (stateOrFn: ((prev: TtFormProps & Record<string, any>) => Partial<TtFormProps & Record<string, any>>) | Partial<TtFormProps & Record<string, any>>) => void;
     /**
      * 校验表单，支持通过第二个参数控制是否滚动到第一个错误分组
      * @param {any} [opts] - 原始 validate 选项
@@ -408,11 +413,6 @@ export type ExtendedFormApi = Omit<FormApi, "getValues" | "validate"> & {
     useStore: <T = NoInfer<TtFormProps>>(selector?: (state: NoInfer<TtFormProps>) => T) => Readonly<Ref<T>>;
     /** 滚动到指定分组（仅 useGroupForm 场景下可用） */
     scrollToGroup?: (key: string) => void;
-    /**
-     * 动态更新分组 schema（同时更新 UI 渲染和底层字段注册），仅 useGroupForm 场景下可用
-     * @param {any[]} newSchema - 新的分组 schema（实际类型为 GroupFormSchema[]，此处用 any[] 避免循环依赖）
-     */
-    updateGroupSchema?: (newSchema: any[]) => void;
     /**
      * 在指定分组中增量插入字段，无需全量重建 schema
      * @param {string} groupKey - 目标分组的 key

package/dist/components/tt-nav-anchor/index.d.ts

@@ -7,6 +7,8 @@ export declare const TtNavAnchor: import('../../../../utils/src').SFCWithInstall
 }>, {
     title: string;
     top: number | string;
+    bottom: number | string;
+    left: number | string;
     right: number | string;
     modelValue: string;
     position: "fixed" | "static" | "sticky";

package/dist/components/tt-nav-anchor/src/TtNavAnchor.vue.d.ts

@@ -8,6 +8,8 @@ declare const _default: import('vue').DefineComponent<TtNavAnchorProps, {}, {},
 }>, {
     title: string;
     top: number | string;
+    bottom: number | string;
+    left: number | string;
     right: number | string;
     modelValue: string;
     position: "fixed" | "static" | "sticky";

package/dist/components/tt-nav-anchor/src/types.d.ts

@@ -26,4 +26,8 @@ export interface TtNavAnchorProps {
     top?: number | string;
     /** fixed/sticky 时距右侧的距离 */
     right?: number | string;
+    /** fixed/sticky 时距左侧的距离 */
+    left?: number | string;
+    /** fixed/sticky 时距底部的距离 */
+    bottom?: number | string;
 }