@dazhicheng/ui 1.6.19 → 1.6.21

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

@@ -9,8 +9,8 @@ export { COMPONENT_MAP, useForm };
 export type { FormApi } from './src/formApi';
 type TtFormSchema<TValues extends Record<string, any> = Record<string, any>> = FormSchema<TValues>;
 type TtFormRenderProps<TValues extends Record<string, any> = Record<string, any>> = FormRenderProps<TValues>;
-type TtExtendedFormApi = ExtendedFormApi;
-export type { ArraySchemaContext, BaseFormComponentMap, BaseFormComponentType, ComponentProps, FormArrayActions, FormItemDependenciesCondition, FormItemDependenciesConditionWithProps, FormItemDependenciesConditionWithRules, FormSlotSchema, InferredComponentPropsType, NestedArrayHandle, RenderComponentContentType, } from './src/types';
+type TtExtendedFormApi<TValues extends Record<string, any> = Record<string, any>> = ExtendedFormApi<TValues>;
+export type { ArraySchemaContext, BaseFormComponentMap, BaseFormComponentType, ComponentProps, FormArrayActions, FormItemDependencies, FormItemDependenciesCondition, FormItemDependenciesConditionWithProps, FormItemDependenciesConditionWithRules, FormSlotSchema, FormValuesInput, InferredComponentPropsType, NestedArrayHandle, RenderComponentContentType, } from './src/types';
 export type { FieldArrayContext, FieldEntry, ReadonlyFieldEntry, ResolvedFieldArrayContext } from './src/types/forms';
 export type { TtExtendedFormApi, TtFormProps, TtFormRenderProps, TtFormSchema };
 export * as z from 'zod';

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

@@ -1,7 +1,7 @@
 import { FormState, GenericObject, ResetFormOpts, ValidationOptions } from 'vee-validate';
-import { ComponentPublicInstance } from 'vue';
+import { ComponentPublicInstance, Ref } from 'vue';
 import { Recordable, StateHandler } from '../../../../../utils/src';
-import { FormActions, FormArrayActions, FormSchema, NestedArrayHandle, TtFormProps } from './types';
+import { FormActions, FormArrayActions, FormSchema, NestedArrayHandle, NoInfer, TtFormProps } from './types';
 import { FieldArrayContext, ResolvedFieldArrayContext } from './types/forms';
 import { Store } from './shared/store';
 export type { ArrayPathSegment } from './utils/array-path';
@@ -9,6 +9,15 @@ export { buildArrayFieldPath, collectArrayFieldPathAliases, normalizeArrayFieldP
 export declare class FormApi {
     form: FormActions;
     isMounted: boolean;
+    /**
+     * 订阅 store 状态，由 `useForm` / `useGroupForm` 在创建 api 时挂载。
+     *
+     * 声明在类上是为了让实例本身满足对外的 `ExtendedFormApi`：schema 回调收到的就是这个实例，
+     * 回调签名里写的是对外类型，缺了这一项两边就对不上，只能靠 as 强转补。
+     * 用 `declare` 而不是 `useStore!`：后者在 `useDefineForClassFields` 下会真的产出一个
+     * 值为 undefined 的实例字段，这里只需要类型声明，不能改运行时的对象形状。
+     */
+    useStore: <T = NoInfer<TtFormProps>>(selector?: (state: NoInfer<TtFormProps>) => T) => Readonly<Ref<T>>;
     state: null | TtFormProps;
     stateHandler: StateHandler;
     store: Store<TtFormProps>;

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

@@ -1,12 +1,12 @@
-import { defineComponent as K, unref as i, inject as O, computed as G, ref as E, watch as S, useTemplateRef as J, shallowRef as Q, onMounted as W, onBeforeUnmount as X, createElementBlock as q, openBlock as h, normalizeClass as p, createBlock as T, createCommentVNode as Z, mergeProps as ee, withCtx as V, renderSlot as te, normalizeProps as oe, guardReactiveProps as ne, normalizeStyle as x, createElementVNode as re, createVNode as N, nextTick as le } from "vue";
-import { ElSkeleton as ie, ElSkeletonItem as z } from "element-plus";
+import { defineComponent as ie, unref as l, inject as le, computed as se, ref as A, watch as H, useTemplateRef as ue, shallowRef as ae, onMounted as fe, onBeforeUnmount as ce, createElementBlock as I, openBlock as w, normalizeClass as y, createBlock as D, createCommentVNode as me, mergeProps as de, withCtx as Y, renderSlot as pe, normalizeProps as ve, guardReactiveProps as ge, normalizeStyle as q, createElementVNode as he, createVNode as j, nextTick as ye } from "vue";
+import { ElSkeleton as Re, ElSkeletonItem as K } 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 se } from "../../../../packages/hooks/src/useDesign.js";
+import { useDesign as ke } from "../../../../packages/hooks/src/useDesign.js";
 import "axios";
-import { isFunction as ae, isBoolean as ue } from "../../../../packages/utils/src/is.js";
+import { isFunction as we, isBoolean as _e } from "../../../../packages/utils/src/is.js";
 import "dayjs";
 import "numeral";
-import { clnm as fe } from "../../../../packages/utils/src/tool.js";
+import { clnm as Ce } 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";
@@ -14,12 +14,12 @@ import "../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/mo
 import "../../../../node_modules/.pnpm/crypto-js@4.2.0/node_modules/crypto-js/pad-pkcs7.js";
 import "lodash-es";
 import "vue-router";
-import { useFormValues as ce } from "vee-validate";
-import me from "../form-render/FormField.vue2.js";
-import { injectFormProps as de } from "../useFormContext.js";
-import { RENDER_SCHEDULER_KEY as pe } from "./lazyContext.js";
-import { resolveValueByFieldName as ve } from "../form-render/dependencies.js";
-const ge = ["data-field-anchor"], ze = /* @__PURE__ */ K({
+import { useFormValues as Ee } from "vee-validate";
+import Me from "../form-render/FormField.vue2.js";
+import { injectFormProps as Fe } from "../useFormContext.js";
+import { RENDER_SCHEDULER_KEY as Be, nextFrame as g } from "./lazyContext.js";
+import { resolveValueByFieldName as Pe } from "../form-render/dependencies.js";
+const He = ["data-field-anchor"], We = /* @__PURE__ */ ie({
   name: "LazyFormField",
   inheritAttrs: !1,
   __name: "LazyFormField",
@@ -34,162 +34,210 @@ const ge = ["data-field-anchor"], ze = /* @__PURE__ */ K({
     skeleton: { type: Boolean, default: !0 },
     skeletonAnimated: { type: Boolean, default: !0 }
   },
-  setup(L) {
-    const { prefixCls: u } = se("lazy-form-field"), a = L, [I] = de(), b = i(I).formApi, D = a.fieldProps.fieldName, n = O(pe, void 0), R = ce(), C = G(() => a.fieldProps.dependencies), l = E(!0);
-    let v = 0;
-    S(
+  setup(O) {
+    const { prefixCls: c } = ke("lazy-form-field"), f = O, [U] = Fe(), G = l(U).formApi, J = f.fieldProps.fieldName, n = le(Be, void 0), b = Ee(), L = se(() => f.fieldProps.dependencies), o = A(!0);
+    let R = 0;
+    H(
       () => {
-        var o;
-        const e = C.value;
-        if ((o = e == null ? void 0 : e.triggerFields) != null && o.length)
-          return e.triggerFields.map((t) => ve(R.value, t));
+        var t;
+        const e = L.value;
+        if ((t = e == null ? void 0 : e.triggerFields) != null && t.length)
+          return e.triggerFields.map((r) => Pe(b.value, r));
       },
       async () => {
-        const e = ++v, o = C.value;
-        if (!o || o.if === void 0) {
-          if (e !== v) return;
-          l.value = !0;
+        const e = ++R, t = L.value;
+        if (!t || t.if === void 0) {
+          if (e !== R) return;
+          o.value = !0;
           return;
         }
-        if (ae(o.if)) {
-          const t = !!await o.if(R.value, b);
-          if (e !== v) return;
-          l.value = t;
-        } else if (ue(o.if)) {
-          if (e !== v) return;
-          l.value = o.if;
+        if (we(t.if)) {
+          const r = !!await t.if(b.value, G);
+          if (e !== R) return;
+          o.value = r;
+        } else if (_e(t.if)) {
+          if (e !== R) return;
+          o.value = t.if;
         }
       },
       { deep: !0, immediate: !0 }
     );
-    const s = J("containerRef"), f = E(!1);
+    const s = ue("containerRef"), u = A(!1);
     let m = !1;
-    const H = `${u}--offscreen`, M = Q(a.estimateHeight);
-    let c = null, r = null, y = null;
-    function w(e) {
-      let o = e.parentElement;
-      for (; o; ) {
-        const t = getComputedStyle(o).overflowY;
-        if (t === "auto" || t === "scroll") return o;
-        o = o.parentElement;
+    const T = `${c}--offscreen`, V = ae(f.estimateHeight);
+    let p = null, i = null, h = null, a = null, _ = [], d = null;
+    function $(e) {
+      let t = e.parentElement;
+      for (; t; ) {
+        const r = getComputedStyle(t).overflowY;
+        if (r === "auto" || r === "scroll") return t;
+        t = t.parentElement;
       }
       return null;
     }
-    function k() {
+    function C() {
       const e = s.value;
-      if (!e || f.value) return;
-      const o = e.offsetHeight;
-      e.style.height = `${o}px`, e.style.overflow = "hidden", f.value = !0, le(() => {
-        requestAnimationFrame(() => {
-          const t = s.value;
-          if (!t) return;
-          const B = t.scrollHeight - o;
-          t.style.height = "", t.style.overflow = "", !(Math.abs(B) <= 2) && requestAnimationFrame(() => {
-            const _ = s.value;
-            if (!_) return;
-            const P = y ?? w(_);
+      if (!e || u.value) return;
+      const t = e.offsetHeight;
+      e.style.height = `${t}px`, e.style.overflow = "hidden", u.value = !0, ye(() => {
+        g(() => {
+          const r = s.value;
+          if (!r) return;
+          const N = r.scrollHeight - t;
+          r.style.height = "", r.style.overflow = "", !(Math.abs(N) <= 2) && g(() => {
+            const B = s.value;
+            if (!B) return;
+            const P = h ?? $(B);
             if (!P) return;
-            const U = _.getBoundingClientRect().top, Y = P.getBoundingClientRect().top;
-            U < Y && (P.scrollTop += B);
+            const ne = B.getBoundingClientRect().top, oe = P.getBoundingClientRect().top;
+            ne < oe && (P.scrollTop += N);
           });
         });
       });
     }
-    let F = !1, g = !1;
-    function A() {
-      r = null, l.value && (F = !0, n == null || n.trackMount(), k());
+    let E = !1, k = !1;
+    function S() {
+      i = null, o.value && (E = !0, n == null || n.trackMount(), C());
     }
-    function $() {
-      f.value || r || !l.value || (r = n ? n.request(A) : (() => {
-        const e = requestAnimationFrame(A);
-        return () => cancelAnimationFrame(e);
-      })());
+    function x() {
+      u.value || i || !o.value || (i = n ? n.request(S) : g(S));
     }
-    function j() {
-      !a.progressive || g || !F || (g = !0, n == null || n.settleMount());
+    function Q() {
+      !f.progressive || k || !E || (k = !0, n == null || n.settleMount());
     }
-    return S(l, (e) => {
-      a.progressive && e && $();
-    }), W(() => {
+    function M() {
+      u.value || i || !m || !o.value || (i = n ? n.request(() => {
+        i = null, !(!m || !o.value) && C();
+      }) : g(() => {
+        i = null, !(!m || !o.value) && C();
+      }));
+    }
+    function W() {
+      const e = String(f.rootMargin).trim().split(/\s+/)[0] ?? "", t = Number.parseFloat(e);
+      return Number.isFinite(t) ? t : 0;
+    }
+    function X() {
+      const e = s.value;
+      if (!(e != null && e.isConnected)) return !1;
+      const t = e.getBoundingClientRect();
+      if (t.width === 0 || t.height === 0) return !1;
+      const r = W();
+      if (h) {
+        const v = h.getBoundingClientRect();
+        return t.bottom > v.top - r && t.top < v.bottom + r;
+      }
+      return t.bottom > -r && t.top < window.innerHeight + r;
+    }
+    function F() {
+      u.value || !o.value || !X() || (m = !0, M());
+    }
+    function Z() {
+      if (a) return;
+      if (n) {
+        a = n.registerVisibilityCheck(F);
+        return;
+      }
+      const e = () => {
+        d || (d = g(() => {
+          d = null, F();
+        }));
+      };
+      document.addEventListener("scroll", e, { capture: !0, passive: !0 }), window.addEventListener("resize", e, { passive: !0 }), a = () => {
+        document.removeEventListener("scroll", e, { capture: !0 }), window.removeEventListener("resize", e), d == null || d(), d = null, a = null;
+      };
+    }
+    const ee = [300, 800, 1600, 3200];
+    function te() {
+      for (const e of ee)
+        _.push(
+          setTimeout(() => {
+            u.value || F();
+          }, e)
+        );
+    }
+    function z() {
+      _.forEach(clearTimeout), _ = [];
+    }
+    function re() {
+      u.value || (Z(), te());
+    }
+    return H(u, (e) => {
+      e && (a == null || a(), z());
+    }), H(o, (e) => {
+      e && (f.progressive ? x() : M());
+    }), fe(() => {
       if (s.value) {
-        if (y = w(s.value), a.progressive) {
-          $();
+        if (h = $(s.value), f.progressive) {
+          x();
           return;
         }
-        c = new IntersectionObserver(
+        p = new IntersectionObserver(
           (e) => {
-            const o = e[0];
-            if (o)
-              if (o.isIntersecting) {
+            const t = e[0];
+            if (t)
+              if (t.isIntersecting) {
                 m = !0;
-                const t = s.value;
-                t && (t.style.minHeight = "", t.classList.remove(H)), !f.value && !r && l.value && (r = n ? n.request(() => {
-                  r = null, !(!m || !l.value) && k();
-                }) : (() => {
-                  const d = requestAnimationFrame(() => {
-                    r = null, !(!m || !l.value) && k();
-                  });
-                  return () => cancelAnimationFrame(d);
-                })());
+                const r = s.value;
+                r && (r.style.minHeight = "", r.classList.remove(T)), M();
               } else
-                m = !1, f.value && s.value && requestAnimationFrame(() => {
+                m = !1, u.value && s.value && g(() => {
                   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);
+                  const r = s.value;
+                  if (!(r != null && r.isConnected)) return;
+                  const v = r.offsetHeight;
+                  v !== 0 && (r.style.minHeight = `${v}px`, r.classList.add(T));
+                }), i && (i(), i = null);
           },
           {
-            root: y,
-            rootMargin: a.rootMargin
+            root: h,
+            rootMargin: f.rootMargin
           }
-        ), c.observe(s.value);
+        ), p.observe(s.value), re();
       }
-    }), X(() => {
-      r && (r(), r = null), a.progressive && F && !g && (g = !0, n == null || n.settleMount()), c == null || c.disconnect(), c = null;
-    }), (e, o) => (h(), q("div", {
+    }), ce(() => {
+      a == null || a(), z(), i && (i(), i = null), f.progressive && E && !k && (k = !0, n == null || n.settleMount()), p == null || p.disconnect(), p = null;
+    }), (e, t) => (w(), I("div", {
       ref_key: "containerRef",
       ref: s,
-      "data-field-anchor": i(D),
-      class: p(i(fe)(i(u), e.fieldClass, { [`${i(u)}--hidden`]: !l.value }))
+      "data-field-anchor": l(J),
+      class: y(l(Ce)(l(c), e.fieldClass, { [`${l(c)}--hidden`]: !o.value }))
     }, [
-      f.value ? (h(), T(me, ee({ key: 0 }, e.fieldProps, {
+      u.value ? (w(), D(Me, de({ key: 0 }, e.fieldProps, {
         rules: e.rules,
-        onVnodeMounted: j
+        onVnodeMounted: Q
       }), {
-        default: V((t) => [
-          te(e.$slots, "default", oe(ne(t)))
+        default: Y((r) => [
+          pe(e.$slots, "default", ve(ge(r)))
         ]),
         _: 3
-      }, 16, ["rules"])) : e.skeleton && l.value ? (h(), T(i(ie), {
+      }, 16, ["rules"])) : e.skeleton && o.value ? (w(), D(l(Re), {
         key: 1,
         animated: e.skeletonAnimated,
-        class: p(`${i(u)}__skeleton`),
-        style: x({ minHeight: `${M.value}px` })
+        class: y(`${l(c)}__skeleton`),
+        style: q({ minHeight: `${V.value}px` })
       }, {
-        template: V(() => [
-          re("div", {
-            class: p(`${i(u)}__row`)
+        template: Y(() => [
+          he("div", {
+            class: y(`${l(c)}__row`)
           }, [
-            N(i(z), {
+            j(l(K), {
               variant: "text",
-              class: p(`${i(u)}__label`)
+              class: y(`${l(c)}__label`)
             }, null, 8, ["class"]),
-            N(i(z), {
+            j(l(K), {
               variant: "rect",
-              class: p(`${i(u)}__control`)
+              class: y(`${l(c)}__control`)
             }, null, 8, ["class"])
           ], 2)
         ]),
         _: 1
-      }, 8, ["animated", "class", "style"])) : l.value ? (h(), q("div", {
+      }, 8, ["animated", "class", "style"])) : o.value ? (w(), I("div", {
         key: 2,
-        style: x({ height: `${M.value}px` })
-      }, null, 4)) : Z("", !0)
-    ], 10, ge));
+        style: q({ height: `${V.value}px` })
+      }, null, 4)) : me("", !0)
+    ], 10, He));
   }
 });
 export {
-  ze as default
+  We as default
 };

package/dist/components/tt-form/src/group-form/groupFormApi.js

@@ -96,12 +96,6 @@ class ye extends j {
     l(this, "_navSyncLoopWarned", !1);
     /** VirtualGroupForm 组件实例引用，由 useGroupForm 的 h() 渲染时赋值 */
     l(this, "groupFormRef", T(null));
-    /**
-     * @description 响应式读取 store 状态，由 useGroupForm 在运行时注入实现
-     * @param {Function} [selector] - 可选的状态选择器
-     * @returns {Readonly<Ref<T>>} 响应式状态引用
-     */
-    l(this, "useStore");
     const {
       groupSchema: s,
       virtual: r = !0,

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

@@ -29,7 +29,25 @@ export interface RenderScheduler {
      * @returns {Promise<void>}
      */
     whenAllSettled: () => Promise<void>;
+    /**
+     * @description 注册「兜底可见性检查」回调，由调度器用共享的 scroll / resize 监听统一驱动。
+     *   微前端 iframe 沙箱下 IntersectionObserver 只在初始观测一次，之后滚动不再上报，需要主动测量补齐；
+     *   若每个字段各自绑定监听，长表单会产生大量重复监听与重复几何读取，故在此集中为一份监听 + 一次节流帧。
+     * @param {() => void} check - 字段的可见性检查回调（内部自行判断是否已挂载）
+     * @returns {() => void} 注销函数
+     */
+    registerVisibilityCheck: (check: () => void) => () => void;
 }
+/**
+ * @description 调度一次「下一帧」回调，rAF 与 setTimeout 竞速，只执行一次。
+ *   微前端 iframe 沙箱（如 micro-app）下子应用运行在 display:none 的 iframe 中，该文档不参与渲染，
+ *   requestAnimationFrame 无法被持续驱动（首帧后即停止回调）。若仅依赖 rAF，分批渲染队列会在
+ *   scheduled 标记为 true 后永久卡住（后续 schedule 与 resume 全部空转），导致剩余字段永久停留骨架屏。
+ *   故用 setTimeout 兜底，保证队列一定能被推进。
+ * @param {() => void} callback - 下一帧要执行的回调
+ * @returns {() => void} 取消函数
+ */
+export declare function nextFrame(callback: () => void): () => void;
 /**
  * @description 创建分批渲染调度器
  * @param {number} [batchSize=4] - 每帧最多渲染的字段数

package/dist/components/tt-form/src/group-form/lazyContext.js

@@ -1,54 +1,82 @@
-function R(f = 4) {
-  const n = [];
-  let l = !1, u = !1, r = 0, c = [];
-  function i() {
-    return n.length === 0 && !l && r === 0;
-  }
-  function o() {
-    if (i() && c.length > 0) {
-      const e = c;
-      c = [], e.forEach((t) => t());
+function E(a) {
+  let t = !1;
+  const n = () => {
+    t || (t = !0, a());
+  }, u = requestAnimationFrame(n), l = setTimeout(n, 32);
+  return () => {
+    t = !0, cancelAnimationFrame(u), clearTimeout(l);
+  };
+}
+function w(a = 4) {
+  const t = [];
+  let n = !1, u = !1, l = 0, o = [];
+  function h() {
+    return t.length === 0 && !n && l === 0;
+  }
+  function m() {
+    if (h() && o.length > 0) {
+      const e = o;
+      o = [], e.forEach((i) => i());
     }
   }
-  function a() {
-    if (l = !1, u) return;
+  function _() {
+    if (n = !1, u) return;
     let e = 0;
-    for (; n.length > 0 && e < f; ) {
-      const t = n.shift();
-      t.cancelled || (t.cb(), e++);
+    for (; t.length > 0 && e < a; ) {
+      const i = t.shift();
+      i.cancelled || (i.cb(), e++);
     }
-    n.length > 0 ? s() : o();
+    t.length > 0 ? d() : m();
   }
-  function s() {
-    l || u || (l = !0, requestAnimationFrame(a));
+  function d() {
+    n || u || (n = !0, E(_));
   }
-  function d(e) {
-    const t = { cb: e, cancelled: !1 };
-    return n.push(t), s(), () => {
-      t.cancelled = !0;
+  function S(e) {
+    const i = { cb: e, cancelled: !1 };
+    return t.push(i), d(), () => {
+      i.cancelled = !0;
     };
   }
-  function h() {
+  function p() {
     u = !0;
   }
-  function S() {
-    u = !1, n.length > 0 && s();
+  function v() {
+    u = !1, t.length > 0 && d();
   }
-  function m() {
-    r++;
+  function L() {
+    l++;
   }
-  function E() {
-    r > 0 && r--, o();
+  function A() {
+    l > 0 && l--, m();
   }
-  function p() {
-    return i() ? Promise.resolve() : new Promise((e) => c.push(e));
+  function b() {
+    return h() ? Promise.resolve() : new Promise((e) => o.push(e));
+  }
+  const c = /* @__PURE__ */ new Set();
+  let s = null, r = null;
+  function f() {
+    r || (r = E(() => {
+      r = null;
+      for (const e of [...c]) e();
+    }));
+  }
+  function R() {
+    s || (document.addEventListener("scroll", f, { capture: !0, passive: !0 }), window.addEventListener("resize", f, { passive: !0 }), s = () => {
+      document.removeEventListener("scroll", f, { capture: !0 }), window.removeEventListener("resize", f), r == null || r(), r = null, s = null;
+    });
+  }
+  function C(e) {
+    return c.add(e), R(), () => {
+      c.delete(e), c.size === 0 && (s == null || s());
+    };
   }
-  return { request: d, pause: h, resume: S, trackMount: m, settleMount: E, whenAllSettled: p };
+  return { request: S, pause: p, resume: v, trackMount: L, settleMount: A, whenAllSettled: b, registerVisibilityCheck: C };
 }
-const _ = Symbol("VirtualRenderScheduler"), b = Symbol("GroupVisibilityCallback"), g = Symbol("HiddenGroupKeys");
+const y = Symbol("VirtualRenderScheduler"), K = Symbol("GroupVisibilityCallback"), g = Symbol("HiddenGroupKeys");
 export {
-  b as GROUP_VISIBILITY_CALLBACK_KEY,
+  K as GROUP_VISIBILITY_CALLBACK_KEY,
   g as HIDDEN_GROUP_KEYS_KEY,
-  _ as RENDER_SCHEDULER_KEY,
-  R as createRenderScheduler
+  y as RENDER_SCHEDULER_KEY,
+  w as createRenderScheduler,
+  E as nextFrame
 };

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

@@ -1,7 +1,9 @@
-import { FormCommonConfig, FormSchema, FormSlotSchema, CustomRenderType, TtFormProps, WrapperClassType } from '../types';
+import { Ref } from 'vue';
+import { FormCommonConfig, FormSchema, FormSlotSchema, CustomRenderType, FormValuesInput, NoInfer, TtFormProps, WrapperClassType } from '../types';
 import { FormApi } from '../formApi';
 import { TtNavAnchorProps } from '../../../tt-nav-anchor';
 import { GroupFormApi } from './groupFormApi';
+import { InsertPosition } from './utils';
 export type CollapsibleType<TValues extends Record<string, any> = Record<string, any>> = boolean | ((values: TValues, formApi: FormApi) => boolean | PromiseLike<boolean>);
 /** 控制 group / row / slot 是否显示，支持布尔值或函数（接收表单值与 formApi，可返回 Promise） */
 export type IfShowConditionType<TValues extends Record<string, any> = Record<string, any>> = boolean | ((values: TValues, formApi: FormApi) => boolean | PromiseLike<boolean>);
@@ -105,12 +107,12 @@ export interface UseGroupFormOptionsWithLegacySchema<TValues extends Record<stri
 }
 /** groupSchema 与 schema 二选一（至少传一个） */
 export type UseGroupFormOptions<TValues extends Record<string, any> = Record<string, any>> = UseGroupFormOptionsWithGroupSchema<TValues> | UseGroupFormOptionsWithLegacySchema<TValues>;
-export type GroupFormExtraState = Partial<Pick<UseGroupFormOptions, "virtual" | "progressive" | "navAnchorProps" | "containerHeight" | "rootMargin" | "estimateFieldHeight" | "scrollOffset">> & {
+export type GroupFormExtraState<TValues extends Record<string, any> = Record<string, any>> = Partial<Pick<UseGroupFormOptions, "virtual" | "progressive" | "navAnchorProps" | "containerHeight" | "rootMargin" | "estimateFieldHeight" | "scrollOffset">> & {
     /** 分组 schema 树形结构（store 状态，由 GroupFormApi.setState 维护） */
-    groupSchema?: GroupFormSchema[];
+    groupSchema?: GroupFormSchema<TValues>[];
 };
 /** 分组表单完整 store 状态类型 */
-export type GroupFormState<TValues extends Record<string, any> = Record<string, any>> = TtFormProps<TValues> & GroupFormExtraState;
+export type GroupFormState<TValues extends Record<string, any> = Record<string, any>> = TtFormProps<TValues> & GroupFormExtraState<TValues>;
 /** LazyFormField 组件 props */
 export interface LazyFormFieldProps {
     /** 传给 FormField 的完整 props（通过 v-bind 透传） */
@@ -174,7 +176,38 @@ export interface GroupSectionProps {
  * @description GroupFormApi 构造函数的分组配置选项，复用 UseGroupFormOptions 中同名字段的类型定义，
  *   额外增加 `groupSchema`（由 useGroupForm 传入）。
  */
-export type GroupFormApiOptions = Pick<UseGroupFormOptions, "virtual" | "progressive" | "navAnchorProps" | "scrollToFirstError" | "containerHeight" | "rootMargin" | "estimateFieldHeight" | "scrollOffset"> & {
+export type GroupFormApiOptions<TValues extends Record<string, any> = Record<string, any>> = Pick<UseGroupFormOptions, "virtual" | "progressive" | "navAnchorProps" | "scrollToFirstError" | "containerHeight" | "rootMargin" | "estimateFieldHeight" | "scrollOffset"> & {
     /** 分组 schema 树形结构（由 useGroupForm 传入） */
-    groupSchema: GroupFormSchema[];
+    groupSchema: GroupFormSchema<TValues>[];
 };
+/**
+ * 分组表单 api 对外类型。
+ *
+ * 与 {@link ExtendedFormApi} 同一个思路：`GroupFormApi` 类内部按 `Record<string, any>` 处理，
+ * 泛型在这一层收窄。分组独有的 `groupSchema` / `appendFields` 也跟着 `TValues` 走，
+ * `useGroupForm<Data>()` 之后再 `setState({ groupSchema })`，回调里依旧能推断出 `Data`。
+ *
+ * 写成「收窄签名 & 类」而不是 `Omit<类, ...> & 收窄签名`：类带私有成员，是名义类型，
+ * `Omit` 会把私有成员抹掉，业务把 api 标注成 `GroupFormApi` 就会报缺属性。
+ * 交叉后属性变成重载对，收窄签名在前所以优先匹配，匹配不上再退回类的宽松签名。
+ */
+export type ExtendedGroupFormApi<TValues extends Record<string, any> = Record<string, any>> = {
+    /** 设置表单状态，支持 `groupSchema` 等分组扩展字段 */
+    setState: (stateOrFn: ((prev: GroupFormState<TValues>) => Partial<GroupFormState<TValues>>) | Partial<GroupFormState<TValues>>) => void;
+    /** 读取当前表单状态 */
+    getState: () => null | GroupFormState<TValues>;
+    /**
+     * 获取表单值
+     * @param isGroup - 为 true 时返回按分组 key 嵌套的对象，默认 false 返回扁平值
+     */
+    getValues: <T = TValues>(isGroup?: boolean) => Promise<T>;
+    /** 写入表单值，已声明字段按 `TValues` 校验类型 */
+    setValues: (fields: FormValuesInput<TValues>, filterFields?: boolean, shouldValidate?: boolean) => Promise<void>;
+    /** 按 fieldName 局部更新已展平的 schema */
+    updateSchema: (schema: Partial<FormSchema<TValues>>[]) => void;
+    /** 在分组树中增量插入字段或子结构 */
+    appendFields: (fields: GroupFormSchema<TValues>[], position?: InsertPosition) => void;
+    /** 校验表单，第二个参数控制是否滚动到第一个错误分组 */
+    validate: (opts?: any, scrollToError?: boolean) => ReturnType<GroupFormApi["validate"]>;
+    useStore: <T = NoInfer<GroupFormState<TValues>>>(selector?: (state: NoInfer<GroupFormState<TValues>>) => T) => Readonly<Ref<T>>;
+} & GroupFormApi;

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

@@ -1,10 +1,12 @@
 import { DefineComponent } from 'vue';
-import { GroupFormApi } from './groupFormApi';
-import { UseGroupFormOptions, UseGroupFormOptionsCommon } from './types';
-type GroupFormOverrideProps = Partial<UseGroupFormOptionsCommon>;
-type UseGroupFormReturn = readonly [DefineComponent<GroupFormOverrideProps>, GroupFormApi];
+import { ExtendedGroupFormApi, UseGroupFormOptions, UseGroupFormOptionsCommon } from './types';
+type GroupFormOverrideProps<TValues extends Record<string, any> = Record<string, any>> = Partial<UseGroupFormOptionsCommon<TValues>>;
+type UseGroupFormReturn<TValues extends Record<string, any> = Record<string, any>> = readonly [
+    DefineComponent<GroupFormOverrideProps<TValues>>,
+    ExtendedGroupFormApi<TValues>
+];
 /**
  * @description 返回可渲染的包装组件、扩展后的表单 API，以及分组折叠状态对象。
  */
-export declare function useGroupForm<TValues extends Record<string, any> = Record<string, any>>(options: UseGroupFormOptions<TValues>): UseGroupFormReturn;
+export declare function useGroupForm<TValues extends Record<string, any> = Record<string, any>>(options: UseGroupFormOptions<TValues>): UseGroupFormReturn<TValues>;
 export {};