@dazhicheng/ui 1.5.213 → 1.5.216

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

@@ -12,6 +12,7 @@ declare function __VLS_template(): {
 type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
 declare const __VLS_component: import('vue').DefineComponent<LazyFormFieldProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<LazyFormFieldProps> & Readonly<{}>, {
     rules: import('../types').FormSchemaRuleType;
+    progressive: boolean;
     rootMargin: string;
     fieldClass: string;
     root: Element | null;

package/dist/components/tt-form/src/group-form/LazyFormField.vue.js

@@ -1,22 +1,22 @@
-import { defineComponent as D, inject as A, computed as U, ref as B, watch as Y, useTemplateRef as j, shallowRef as K, onMounted as O, onBeforeUnmount as G, createElementBlock as S, openBlock as h, normalizeClass as m, unref as n, createBlock as V, createCommentVNode as J, mergeProps as Q, withCtx as x, renderSlot as W, normalizeProps as X, guardReactiveProps as Z, normalizeStyle as N, createElementVNode as ee, createVNode as T, nextTick as z } from "vue";
-import { ElSkeleton as te, ElSkeletonItem as L } from "element-plus";
+import { defineComponent as Y, inject as K, computed as O, ref as A, watch as S, useTemplateRef as G, shallowRef as J, onMounted as Q, onBeforeUnmount as W, createElementBlock as q, openBlock as h, normalizeClass as p, unref as i, createBlock as x, createCommentVNode as X, mergeProps as Z, withCtx as T, renderSlot as ee, normalizeProps as te, guardReactiveProps as ne, normalizeStyle as V, createElementVNode as oe, createVNode as N, nextTick as re } from "vue";
+import { ElSkeleton as le, ElSkeletonItem as z } from "element-plus";
 import "../../../../node_modules/.pnpm/vue-types@5.1.3_vue@3.5.21_typescript@5.9.3_/node_modules/vue-types/shim/index.modern.js";
-import { useDesign as re } from "../../../../packages/hooks/src/useDesign.js";
+import { useDesign as ie } from "../../../../packages/hooks/src/useDesign.js";
 import "axios";
-import { isFunction as oe, isBoolean as le } from "../../../../packages/utils/src/is.js";
-import { clnm as ne } from "../../../../packages/utils/src/tool.js";
+import { isFunction as se, isBoolean as ae } from "../../../../packages/utils/src/is.js";
+import { clnm as ue } from "../../../../packages/utils/src/tool.js";
 import "../../../../node_modules/.pnpm/decimal.js@10.6.0/node_modules/decimal.js/decimal.js";
 import "../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/aes.js";
 import "../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/enc-utf8.js";
 import "../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/mode-ecb.js";
 import "../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/pad-pkcs7.js";
 import "lodash-es";
-import { useFormValues as ie } from "vee-validate";
-import se from "../form-render/FormField.vue2.js";
-import { injectRenderFormProps as ae } from "../form-render/context.js";
-import { VIRTUAL_ERROR_CACHE_KEY as ue, RENDER_SCHEDULER_KEY as fe } from "./lazyContext.js";
-import { resolveValueByFieldName as ce } from "../form-render/dependencies.js";
-const Se = /* @__PURE__ */ D({
+import { useFormValues as fe } from "vee-validate";
+import ce from "../form-render/FormField.vue2.js";
+import { injectRenderFormProps as me } from "../form-render/context.js";
+import { RENDER_SCHEDULER_KEY as de } from "./lazyContext.js";
+import { resolveValueByFieldName as pe } from "../form-render/dependencies.js";
+const ve = ["data-field-anchor"], Te = /* @__PURE__ */ Y({
   name: "LazyFormField",
   inheritAttrs: !1,
   __name: "LazyFormField",
@@ -26,137 +26,167 @@ const Se = /* @__PURE__ */ D({
     fieldClass: { default: "" },
     root: { default: null },
     rootMargin: { default: "200px 0px" },
+    progressive: { type: Boolean, default: !1 },
     estimateHeight: { default: 52 },
     skeleton: { type: Boolean, default: !0 },
     skeletonAnimated: { type: Boolean, default: !0 }
   },
-  setup(q) {
-    const { prefixCls: s } = re("lazy-form-field"), d = q, g = ae().form, p = d.fieldProps.fieldName, v = A(ue, void 0), _ = A(fe, void 0), C = ie(), k = U(() => d.fieldProps.dependencies), i = B(!0);
-    Y(
+  setup(L) {
+    const { prefixCls: u } = ie("lazy-form-field"), a = L, I = me().form, b = a.fieldProps.fieldName, o = K(de, void 0), P = fe(), C = O(() => a.fieldProps.dependencies), l = A(!0);
+    let v = 0;
+    S(
       () => {
-        var r;
-        const e = k.value;
-        if ((r = e == null ? void 0 : e.triggerFields) != null && r.length)
-          return e.triggerFields.map((t) => ce(C.value, t));
+        var n;
+        const e = C.value;
+        if ((n = e == null ? void 0 : e.triggerFields) != null && n.length)
+          return e.triggerFields.map((t) => pe(P.value, t));
       },
       async () => {
-        const e = k.value;
-        if (!e || e.if === void 0) {
-          i.value = !0;
+        const e = ++v, n = C.value;
+        if (!n || n.if === void 0) {
+          if (e !== v) return;
+          l.value = !0;
           return;
         }
-        oe(e.if) ? i.value = !!await e.if(C.value, g) : le(e.if) && (i.value = e.if);
+        if (se(n.if)) {
+          const t = !!await n.if(P.value, I);
+          if (e !== v) return;
+          l.value = t;
+        } else if (ae(n.if)) {
+          if (e !== v) return;
+          l.value = n.if;
+        }
       },
       { deep: !0, immediate: !0 }
     );
-    const o = j("containerRef"), u = B(!1);
-    let f = !1;
-    const E = `${s}--offscreen`, H = K(d.estimateHeight);
-    let a = null, l = null, y = null;
-    async function I() {
-      if (!g || !p) return;
-      const r = v == null ? void 0 : v.get(p);
-      r && (v.delete(p), await z(), g.setFieldError(p, r));
-    }
+    const s = G("containerRef"), f = A(!1);
+    let m = !1;
+    const H = `${u}--offscreen`, M = J(a.estimateHeight);
+    let c = null, r = null, y = null;
     function w(e) {
-      let r = e.parentElement;
-      for (; r; ) {
-        const t = getComputedStyle(r).overflowY;
-        if (t === "auto" || t === "scroll") return r;
-        r = r.parentElement;
+      let n = e.parentElement;
+      for (; n; ) {
+        const t = getComputedStyle(n).overflowY;
+        if (t === "auto" || t === "scroll") return n;
+        n = n.parentElement;
       }
       return null;
     }
-    function P() {
-      const e = o.value;
-      if (!e || u.value) return;
-      const r = e.offsetHeight;
-      e.style.height = `${r}px`, e.style.overflow = "hidden", u.value = !0, I(), z(() => {
+    function k() {
+      const e = s.value;
+      if (!e || f.value) return;
+      const n = e.offsetHeight;
+      e.style.height = `${n}px`, e.style.overflow = "hidden", f.value = !0, re(() => {
         requestAnimationFrame(() => {
-          const t = o.value;
+          const t = s.value;
           if (!t) return;
-          const $ = t.scrollHeight - r;
-          t.style.height = "", t.style.overflow = "", !(Math.abs($) <= 2) && requestAnimationFrame(() => {
-            const R = o.value;
+          const E = t.scrollHeight - n;
+          t.style.height = "", t.style.overflow = "", !(Math.abs(E) <= 2) && requestAnimationFrame(() => {
+            const R = s.value;
             if (!R) return;
-            const F = y ?? w(R);
-            if (!F) return;
-            const M = R.getBoundingClientRect().top, b = F.getBoundingClientRect().top;
-            M < b && (F.scrollTop += $);
+            const _ = y ?? w(R);
+            if (!_) return;
+            const j = R.getBoundingClientRect().top, U = _.getBoundingClientRect().top;
+            j < U && (_.scrollTop += E);
           });
         });
       });
     }
-    return O(() => {
-      o.value && (y = w(o.value), a = new IntersectionObserver(
-        (e) => {
-          const r = e[0];
-          if (r)
-            if (r.isIntersecting) {
-              f = !0;
-              const t = o.value;
-              t && (t.style.minHeight = "", t.classList.remove(E)), !u.value && !l && i.value && (l = _ ? _.request(() => {
-                l = null, !(!f || !i.value) && P();
-              }) : (() => {
-                const c = requestAnimationFrame(() => {
-                  l = null, !(!f || !i.value) && P();
-                });
-                return () => cancelAnimationFrame(c);
-              })());
-            } else
-              f = !1, u.value && o.value && requestAnimationFrame(() => {
-                if (f) return;
-                const t = o.value;
-                if (!(t != null && t.isConnected)) return;
-                const c = t.offsetHeight;
-                c !== 0 && (t.style.minHeight = `${c}px`, t.classList.add(E));
-              }), l && (l(), l = null);
-        },
-        {
-          root: y,
-          rootMargin: d.rootMargin
+    let F = !1, g = !1;
+    function $() {
+      r = null, l.value && (F = !0, o == null || o.trackMount(), k());
+    }
+    function B() {
+      f.value || r || !l.value || (r = o ? o.request($) : (() => {
+        const e = requestAnimationFrame($);
+        return () => cancelAnimationFrame(e);
+      })());
+    }
+    function D() {
+      !a.progressive || g || !F || (g = !0, o == null || o.settleMount());
+    }
+    return S(l, (e) => {
+      a.progressive && e && B();
+    }), Q(() => {
+      if (s.value) {
+        if (y = w(s.value), a.progressive) {
+          B();
+          return;
         }
-      ), a.observe(o.value));
-    }), G(() => {
-      l && (l(), l = null), a == null || a.disconnect(), a = null;
-    }), (e, r) => (h(), S("div", {
+        c = new IntersectionObserver(
+          (e) => {
+            const n = e[0];
+            if (n)
+              if (n.isIntersecting) {
+                m = !0;
+                const t = s.value;
+                t && (t.style.minHeight = "", t.classList.remove(H)), !f.value && !r && l.value && (r = o ? o.request(() => {
+                  r = null, !(!m || !l.value) && k();
+                }) : (() => {
+                  const d = requestAnimationFrame(() => {
+                    r = null, !(!m || !l.value) && k();
+                  });
+                  return () => cancelAnimationFrame(d);
+                })());
+              } else
+                m = !1, f.value && s.value && requestAnimationFrame(() => {
+                  if (m) return;
+                  const t = s.value;
+                  if (!(t != null && t.isConnected)) return;
+                  const d = t.offsetHeight;
+                  d !== 0 && (t.style.minHeight = `${d}px`, t.classList.add(H));
+                }), r && (r(), r = null);
+          },
+          {
+            root: y,
+            rootMargin: a.rootMargin
+          }
+        ), c.observe(s.value);
+      }
+    }), W(() => {
+      r && (r(), r = null), a.progressive && F && !g && (g = !0, o == null || o.settleMount()), c == null || c.disconnect(), c = null;
+    }), (e, n) => (h(), q("div", {
       ref_key: "containerRef",
-      ref: o,
-      class: m(n(ne)(n(s), e.fieldClass, { [`${n(s)}--hidden`]: !i.value }))
+      ref: s,
+      "data-field-anchor": i(b),
+      class: p(i(ue)(i(u), e.fieldClass, { [`${i(u)}--hidden`]: !l.value }))
     }, [
-      u.value ? (h(), V(se, Q({ key: 0 }, e.fieldProps, { rules: e.rules }), {
-        default: x((t) => [
-          W(e.$slots, "default", X(Z(t)))
+      f.value ? (h(), x(ce, Z({ key: 0 }, e.fieldProps, {
+        rules: e.rules,
+        onVnodeMounted: D
+      }), {
+        default: T((t) => [
+          ee(e.$slots, "default", te(ne(t)))
         ]),
         _: 3
-      }, 16, ["rules"])) : e.skeleton && i.value ? (h(), V(n(te), {
+      }, 16, ["rules"])) : e.skeleton && l.value ? (h(), x(i(le), {
         key: 1,
         animated: e.skeletonAnimated,
-        class: m(`${n(s)}__skeleton`),
-        style: N({ minHeight: `${H.value}px` })
+        class: p(`${i(u)}__skeleton`),
+        style: V({ minHeight: `${M.value}px` })
       }, {
-        template: x(() => [
-          ee("div", {
-            class: m(`${n(s)}__row`)
+        template: T(() => [
+          oe("div", {
+            class: p(`${i(u)}__row`)
           }, [
-            T(n(L), {
+            N(i(z), {
               variant: "text",
-              class: m(`${n(s)}__label`)
+              class: p(`${i(u)}__label`)
             }, null, 8, ["class"]),
-            T(n(L), {
+            N(i(z), {
               variant: "rect",
-              class: m(`${n(s)}__control`)
+              class: p(`${i(u)}__control`)
             }, null, 8, ["class"])
           ], 2)
         ]),
         _: 1
-      }, 8, ["animated", "class", "style"])) : i.value ? (h(), S("div", {
+      }, 8, ["animated", "class", "style"])) : l.value ? (h(), q("div", {
         key: 2,
-        style: N({ height: `${H.value}px` })
-      }, null, 4)) : J("", !0)
-    ], 2));
+        style: V({ height: `${M.value}px` })
+      }, null, 4)) : X("", !0)
+    ], 10, ve));
   }
 });
 export {
-  Se as default
+  Te as default
 };

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

@@ -1,4 +1,4 @@
-import { FormState, GenericObject, ResetFormOpts, ValidationOptions } from 'vee-validate';
+import { FormState, FormValidationResult, GenericObject, ResetFormOpts, ValidationOptions } from 'vee-validate';
 import { Ref } from 'vue';
 import { FormApi } from '../formApi';
 import { TtFormProps } from '../types';
@@ -10,6 +10,8 @@ import { InsertPosition } from './utils';
 export declare class GroupFormApi extends FormApi {
     /** 是否启用虚拟化（IntersectionObserver 懒渲染） */
     readonly virtual: boolean;
+    /** 是否启用渐进式挂载（分批后台挂载全部字段，挂载后常驻 DOM，用于操作全量 DOM 场景） */
+    readonly progressive: boolean;
     /** 构造时的导航锚点默认配置，作为 store 未设置时的 fallback */
     private readonly _defaultNavAnchorProps;
     /** 校验失败时是否自动滚动到第一个有错误的分组，默认 true */
@@ -28,12 +30,14 @@ export declare class GroupFormApi extends FormApi {
     readonly hiddenGroupKeys: Set<string>;
     /** 当前被 ifShow 隐藏的字段名集合 */
     readonly hiddenFieldNames: Set<string>;
-    /** 导航各分组的错误数量，validate 后自动更新 */
+    /**
+     * 导航各分组的错误数量（派生自 vee-validate 的 form.errors，已内置合并挂载 pathState 与未挂载 extraErrorsBag）。
+     * 通过 computed 惰性求值：读取时依赖收集 form.errors，任何 setFieldError / validate 之后
+     * 只要 form.errors 变化，导航栏渲染时自动重算，无需手动同步。
+     */
     readonly navErrorCounts: Record<string, number>;
-    /** 共享错误缓存，validate 写入 → LazyFormField 挂载时读取恢复 */
-    readonly errorCacheMap: Map<string, string>;
-    /** 重置信号，递增时通知所有 LazyFormField 清空 cachedError */
-    readonly resetSignal: Ref<number, number>;
+    /** navErrorCounts 的响应式来源，reactive Proxy 在读取时依赖注入到此 computed */
+    private _navErrorCountsRef;
     /** 初始传入的分组 schema（用于 fallback） */
     private readonly _initialGroupSchema;
     /** 初始展平后的 flatSchema（用于 fallback） */
@@ -52,13 +56,25 @@ export declare class GroupFormApi extends FormApi {
     private _groupKeySet;
     /** 是否已执行过 validate，用于控制导航栏错误同步是否需要重新校验未挂载字段 */
     private _hasValidated;
+    /** 导航错误同步在单个宏任务窗口内的累计趟数，用于防御非确定性动态规则导致的 errors↔navCount 回环 */
+    private _navSyncPassCount;
+    /** 是否已安排本窗口的计数重置（宏任务后清零） */
+    private _navSyncResetScheduled;
+    /** 本轮回环告警是否已输出，避免刷屏 */
+    private _navSyncLoopWarned;
     /** VirtualGroupForm 组件实例引用，由 useGroupForm 的 h() 渲染时赋值 */
     groupFormRef: Ref<{
         scrollToGroup?: ((key: string) => void) | undefined;
+        scrollToField?: ((fieldName: string) => void) | undefined;
+        whenAllRendered?: (() => Promise<void>) | undefined;
     } | null, {
         scrollToGroup?: (key: string) => void;
+        scrollToField?: (fieldName: string) => void;
+        whenAllRendered?: () => Promise<void>;
     } | {
         scrollToGroup?: ((key: string) => void) | undefined;
+        scrollToField?: ((fieldName: string) => void) | undefined;
+        whenAllRendered?: (() => Promise<void>) | undefined;
     } | null>;
     /**
      * @description 响应式读取 store 状态，由 useGroupForm 在运行时注入实现
@@ -87,7 +103,7 @@ export declare class GroupFormApi extends FormApi {
      */
     protected getFieldNamesForSetValuesFilter(): string[];
     /**
-     * @description schema 中移除字段后清空 vee 值/错误，并同步清理虚拟列表 errorCacheMap
+     * @description schema 中移除字段后清空 vee 值/错误，并注销对应数组字段句柄
      * @param {string[]} removedFieldNames 已移除的 fieldName 列表
      */
     onRemovedSchemaFields(removedFieldNames: string[]): void;
@@ -103,7 +119,30 @@ export declare class GroupFormApi extends FormApi {
      * @example
      * await formApi.validate(undefined, false);
      */
-    validate(opts?: Partial<ValidationOptions>, scrollToError?: boolean): Promise<import('vee-validate').FormValidationResult<GenericObject, GenericObject>>;
+    validate(_opts?: Partial<ValidationOptions>, scrollToError?: boolean): Promise<FormValidationResult<GenericObject, GenericObject>>;
+    /**
+     * @description 对收集到的可见字段逐个用 vee-validate 底层 `validate()` 校验，独立字段并发执行。
+     *   规则引擎与挂载态字段完全一致（含 defineRule 自定义规则、zod typed schema、跨字段 target 解析）。
+     * @param {ResolvedValidationField[]} fields - 待校验字段清单
+     * @param {Record<string, any>} values - 整表值，透传给 vee-validate 做跨字段规则解析
+     * @returns {Promise<Record<string, string>>} 字段名 → 首条错误信息（仅含校验失败字段）
+     */
+    private _runFieldValidations;
+    /**
+     * @description 把校验结果写回 vee-validate 的错误状态（唯一错误 sink）。
+     *   带 diff 保护：只有当目标错误与当前 form.errors 不一致时才写，避免触发 useGroupForm 里
+     *   `watch(form.errors)` → syncNavErrorCountsFromForm 的无谓回环，并保证回环在有限趟内收敛。
+     * @param {ResolvedValidationField[]} fields - 本轮参与校验的字段（决定要清空/设置哪些字段）
+     * @param {Record<string, string>} errorMap - 字段名 → 错误信息
+     */
+    private _applyFieldErrors;
+    /**
+     * @description 清空全部字段错误（含 vee-validate extraErrorsBag 里从未挂载过的残留）。
+     *   vee-validate 的 resetForm 只遍历已挂载的 pathState，不会清 extraErrorsBag 里未挂载路径的错误，
+     *   因此这里显式遍历「展平 schema 顶层字段 + 当前 form.errors 的全部 key（含未挂载/数组行路径）」
+     *   逐个 setFieldError(undefined)，保证重置后未挂载字段的残留错误也被清掉。
+     */
+    private _clearAllFieldErrors;
     /**
      * @description 校验并提交表单
      * @returns {Promise<any>} 提交结果，校验失败时返回 undefined
@@ -116,7 +155,7 @@ export declare class GroupFormApi extends FormApi {
      */
     resetForm(state?: Partial<FormState<GenericObject>>, opts?: Partial<ResetFormOpts>): Promise<void>;
     /**
-     * @description 重置校验状态（含清空虚拟字段错误缓存和导航错误计数）
+     * @description 重置校验状态（同时清空虚拟字段错误缓存；navErrorCounts 由 form.errors 派生，自动更新）
      */
     resetValidate(): Promise<void>;
     /**
@@ -130,6 +169,18 @@ export declare class GroupFormApi extends FormApi {
      * @param {string} key - 分组 key
      */
     scrollToGroup(key: string): void;
+    /**
+     * @description 滚动到指定字段（借助 LazyFormField 容器的 data-field-anchor 锚点，未挂载也可定位）。
+     *   主要用于「无分组、且虚拟懒渲染尚未挂载」的字段——它们没有分组锚点，基类按 [name] 也找不到 DOM。
+     * @param {string} fieldName - 字段名（完整路径）
+     */
+    scrollToField(fieldName: string): void;
+    /**
+     * @description 等待渐进式挂载完成（所有字段已渲染进 DOM）。用于需要操作全量 DOM 的场景
+     *   （截图、导出、爬虫等）前调用。非 progressive 模式下立即 resolve。
+     * @returns {Promise<void>}
+     */
+    whenAllRendered(): Promise<void>;
     /**
      * @description 切换分组折叠状态
      * @param {string} key - 分组 key
@@ -146,7 +197,7 @@ export declare class GroupFormApi extends FormApi {
      *   group 隐藏时额外维护 {@link hiddenGroupKeys} 供导航和渲染判断；
      *   group / row 隐藏时都会清空其下字段校验，并把字段加入 {@link hiddenFieldNames}，使隐藏字段不参与校验。
      *   可见性变化后在下一帧调用 {@link syncNavErrorCountsFromForm}，使「先 validate 再隐藏再显示」时
-     *   导航徽标、{@link errorCacheMap} 与表单项错误展示保持一致。
+     *   导航徽标与表单项错误展示保持一致。
      * @param {string} key - 分组 key
      * @param {boolean} visible - 是否可见
      * @param {string[]} [fieldNames] - 兼容旧内部调用的字段名列表，传入时按字段集合显隐处理
@@ -217,40 +268,46 @@ export declare class GroupFormApi extends FormApi {
      */
     removeGroups(groupKey: string[] | string): void;
     /**
-     * @description 合并 vee-validate 实时 errors 与虚拟列表未挂载字段的 errorCacheMap，用于导航徽标与输入联动
-     * @returns {Record<string, string>} 合并后的错误映射
+     * @description 读取 vee-validate 的实时 errors（已内置合并挂载字段 pathState 与未挂载字段 extraErrorsBag），
+     *   剔除隐藏字段后作为导航徽标计数来源。不再需要外挂 errorCacheMap——未挂载字段的错误由 setFieldError
+     *   直接写入 vee-validate 的 extraErrorsBag，天然进入 form.errors。
+     * @returns {Record<string, string>} 过滤隐藏字段后的错误映射
      */
     private _mergeErrorsForNav;
     /**
-     * @description 同步导航错误计数。
-     *   当开启虚拟列表且已执行过 validate 时，会重新对未挂载字段做可见性检查和校验，
-     *   确保 dependencies 条件变化后错误计数实时更新。
+     * @description 刷新未挂载字段的校验错误，使 dependencies 条件变化后导航徽标即时反映。
+     *   注：`navErrorCounts` 是依赖 form.errors 的 computed 派生量，会自动重算，此方法只负责在
+     *   「已 validate 过」的虚拟列表场景下，重算可见字段错误并写回 form.errors（未挂载字段落 extraErrorsBag）。
+     *   非虚拟化 / 未 validate 过时直接返回，computed 会自然反映 form.errors 现状。
      */
     syncNavErrorCountsFromForm(): Promise<void>;
     /**
-     * @description 清空导航各分组的错误计数
+     * @description 校验失败后滚动到第一个错误字段所属的分组。
+     *   按 fields 的文档顺序取第一个出错字段（不是遍历分组"是否含任意错误"，避免总是命中最外层祖先分组），
+     *   定位到该字段直接所属的最内层分组，并展开其整条折叠的祖先链，保证目标在 DOM 中且可见。
+     * @param {ResolvedValidationField[]} fields - 本轮参与校验的字段（已按文档顺序）
+     * @param {Record<string, string>} errorMap - 字段名 → 错误信息
      */
-    private _clearNavErrorCounts;
+    private _scrollToFirstErrorField;
     /**
-     * @description 校验失败后展开包含错误的分组，并滚动到该分组标题
-     * @param {Record<string, string>} errors - 合并后的所有错误
-     */
-    private _scrollToFirstErrorGroup;
-    /**
-     * @description 从校验结果中剔除属于隐藏字段集合的错误，并重新判定 valid 状态
-     * @param {object} result - 校验结果
-     * @returns {object} 过滤后的校验结果
+     * @description 解析字段在未挂载状态下应使用的有效校验规则：优先取 dependencies.rules 的动态结果，
+     *   为空时回退到静态 schema.rules；两者都为空时，若 dependencies.required 为真则视为 "required"。
+     *   与 FormField.vue 中 currentRules / fieldRules 的计算逻辑保持一致，避免虚拟列表下未挂载字段
+     *   因为只写了 dependencies.required（未写静态 rules）而被漏判为合法。
+     * @param {FormSchema} schema - 字段 schema
+     * @param {Record<string, any>} values - 当前表单值
+     * @returns {Promise<FormSchemaRuleType | undefined>} 有效校验规则
      */
-    private _stripHiddenFieldErrors;
     /**
-     * @description 对单个字段值执行 rules 校验（纯数据，不挂载组件）。
-     *   支持字符串规则（"required" / "selectRequired"）和 Zod schema。
-     * @param {unknown} value - 字段值
-     * @param {FormSchemaRuleType | undefined} rules - 校验规则
-     * @param {string} fieldName - 字段名
-     * @returns {Promise<string | undefined>} 错误信息，无错误返回 undefined
+     * @description 安全执行用户提供的 dependencies 异步回调：捕获异常并降级，避免单个字段的回调抛错
+     *   （或 reject）拖垮整表校验 / 导航同步。故障隔离到字段级，出错时用给定回退值并告警。
+     * @param {() => T | Promise<T>} fn - 用户回调
+     * @param {T} fallback - 出错时的回退值
+     * @param {string} context - 日志上下文（字段名 + 回调类型）
+     * @returns {Promise<T>}
      */
-    private _validateFieldValue;
+    private _safeInvoke;
+    private _resolveEffectiveRules;
     /**
      * @description 检查字段的 dependencies 条件，判断字段在当前值下是否应该被校验。
      *   与 FormField.vue 保持一致：visible = !hide && isIf && isShow
@@ -260,17 +317,25 @@ export declare class GroupFormApi extends FormApi {
      */
     private _isFieldVisible;
     /**
-     * @description 对所有未挂载的字段做纯值校验，补充到 validate 结果中，
-     *   并将错误写入 errorCacheMap 以便 LazyFormField 挂载时恢复。
-     *   会跳过因 dependencies.if 条件不满足而不应渲染的字段，与原始表单校验行为一致。
-     * @param {object} validateResult - 父类 validate 返回的校验结果
-     * @returns {Promise<object>} 补充未挂载字段错误后的校验结果
+     * @description 收集当前需要校验的全部可见字段（顶层字段 + 数组行递归展开的行内字段）。
+     *   统一 validate / syncNavErrorCountsFromForm 的字段来源，避免两份平行遍历逻辑走偏。
+     *   - 顶层字段：遍历展平 schema，逐个走 {@link _isFieldVisible} 过滤（hide / dependencies.if / dependencies.show / 隐藏分组）。
+     *   - 数组字段（useArraySchema）：字段自身规则按普通字段收集（与未挂载路径旧行为一致，也顺带覆盖挂载态），
+     *     再从 form.values 取当前数组值，按行调用 {@link resolveArraySchemasForRuntime}（safeMutations 只读，无副作用）
+     *     展开行内字段，递归处理嵌套数组。行内字段路径与 FormArrayRegister 渲染时的注册键完全一致。
+     * @param {Record<string, any>} values - 当前表单值
+     * @returns {Promise<ResolvedValidationField[]>} 扁平化的待校验字段清单
      */
-    private _validateUnmountedFields;
+    private _collectValidationFields;
     /**
-     * @description 清空所有缓存的错误并递增重置信号
+     * @description 递归收集单个 schema 节点的可校验字段。普通字段直接产出；
+     *   数组字段先产出自身规则，再按当前值逐行展开行内字段（含嵌套数组）。
+     * @param {FormSchema} schema - 字段 schema（顶层或行内）
+     * @param {string} fieldName - 该字段的完整路径（行内字段已拼好数组下标路径）
+     * @param {Record<string, any>} values - 当前表单值
+     * @returns {Promise<ResolvedValidationField[]>} 该节点（含数组行内字段）产出的字段清单，按文档顺序排列
      */
-    private _clearAllCachedErrors;
+    private _collectFieldRecursive;
     /**
      * @description 收集分组 key 及其所有子分组 key（去重）
      * @param keys - 起始分组 key 列表
@@ -286,13 +351,12 @@ export declare class GroupFormApi extends FormApi {
      * @description 根据错误映射更新导航各分组的错误计数
      * @param {Record<string, string>} errors - 字段错误映射
      */
-    private _updateNavErrorCounts;
     /**
-     * @description 根据错误字段找到第一个包含错误的分组 key（按 schema 定义顺序）
-     * @param {Record<string, string>} errors - 错误字段映射
-     * @returns {string | undefined} 第一个有错误的分组 key
+     * @description 计算导航各分组的错误数量（纯函数：读入 form.errors，返回 { groupKey: count }）。
+     *   仅在 {@link _navErrorCountsRef} 的 computed getter 中调用；不再对外暴露 push 式更新入口。
+     * @returns {Record<string, number>} 各分组的错误数量
      */
-    private _findFirstErrorGroupKey;
+    private _computeNavErrorCounts;
     /**
      * @description 获取指定分组下的字段名列表，默认会获取该分组下的所有字段
      * @param {string} key - 分组 key