@neatui/vue 5.0.0 → 5.1.1

package/src/components/loader/FormLoader/FormLoader.vue

@@ -1,173 +1,143 @@
 <template>
-  <div :ui-row="rows" :class="rootClass">
+  <Level :bare="bare" v-bind="bare ? undefined : { 'ui-row': rows || undefined, class: rootClass }">
     <template v-for="(col, idx) in state.form" :key="idx">
-      <div
-        v-if="isGroup(col) || !isCleared(col)"
-        :id="col._fid"
-        :ui-col="col.media"
-        :ui-flex="`${isVertical(col) ? 'col xm' : 'row lt'}`"
-        :data-path="debug ? fieldPath(col) || undefined : undefined"
-        :title="debug ? debugInfo(col) : undefined"
-        v-bind="col.attrs || {}"
-        :style="isCleared(col) ? { display: 'none' } : undefined"
-        v-on="isGroup(col) || col._array ? eventsOf(col, context()) : {}"
-      >
-        <!-- ${field}-row：整行自定义，包括标签 -->
-        <div v-if="rowSlot(col)" class="flex-block" @focusout="col._touched = true">
-          <slot :name="rowSlot(col)" v-bind="fieldScope(col)"></slot>
-          <FieldMessage :col="col" :mode="mode" />
-        </div>
-        <template v-else>
-          <!-- 标签：${field}-label / array-label / child-label / label 插槽可以接管 -->
-          <FormLoader
-            v-if="labelNodes(col.label)"
-            :form="labelNodes(col.label)"
-            :clearContext="{ value: isCleared(col), restore: canRestore(col) }"
-            :arrayContext="col._array ? arrayContext(col) : arrayContextProp"
-            :data="col._data"
-            :root="rootData"
-            :path="[path, col.paths].filter(Boolean).join('.')"
-            :index="index"
-            :idx="`${childIdx(col, idx)}-label`"
-            :mode="mode"
-            :interacted="touched"
-            :debug="debug"
-            rows=""
-            class="w-full"
-            ui-flex="row lm"
-          />
-          <template v-else-if="labelText(col.label)">
-            <h6 v-if="isVertical(col)" :style="`${showStar(col) ? 'text-indent: -1em' : ''}`" :class="labelClass" v-bind="labelAttrs(col.label)">
-              <slot v-if="labelSlot(col)" :name="labelSlot(col)" :col="col" :node="col" :data="col._data" :text="formatLabel(col)"></slot>
-              <template v-else-if="labelText(col.label) !== '*'">
-                <b v-if="showStar(col)" class="co-risk pr" style="left: 0.1em">﹡</b>
-                <span>{{ formatLabel(col) }}</span>
-              </template>
-            </h6>
-            <p
-              v-else
-              :class="[labelClass, `${clh({ ...(col.model[1] || {}) })}`]"
-              :style="labelStyle(col)"
-              class="ar nr-sm flex-fixed o-ls"
-              v-bind="labelAttrs(col.label)"
-            >
-              <slot v-if="labelSlot(col)" :name="labelSlot(col)" :col="col" :node="col" :data="col._data" :text="formatLabel(col)"></slot>
-              <template v-else-if="labelText(col.label) !== '*'">
-                <b v-if="showStar(col)" class="co-risk">﹡</b>
-                <span>{{ formatLabel(col) }}</span>
-              </template>
-            </p>
-          </template>
+      <template v-if="isGroup(col) || !isCleared(col)">
+        <FormRender v-if="isBareContent(col)" bare :col="col" :mode="mode" :interacted="touched" :ctx="context()" v-bind="nodeAttrs(col)" />
+
+        <div v-else v-bind="nodeAttrs(col)" v-on="isGroup(col) || col._array ? eventsOf(col, context()) : {}">
+          <div v-if="rowSlot(col)" class="flex-block" @focusout="col._touched = true">
+            <slot :name="rowSlot(col)" v-bind="fieldScope(col)"></slot>
+            <FieldMessage :col="col" :mode="mode" />
+          </div>
 
-          <!-- 分组：递归渲染，带 field 时写入 data[field]，否则和当前层共用数据 -->
-          <div v-if="isGroup(col)" class="flex-block" :style="col.attrs?.['ui-flex'] ? { display: 'contents' } : undefined">
+          <FormLoader v-else-if="isGroup(col) && !hasLabel(col)" v-bind="childProps(col)">
+            <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
+          </FormLoader>
+
+          <template v-else>
             <FormLoader
-              :form="col.child || []"
+              v-if="labelNodes(col.label)"
+              :form="labelNodes(col.label)"
               :clearContext="{ value: isCleared(col), restore: canRestore(col) }"
-              :arrayContext="arrayContextProp"
-              :data="childData(col)"
+              :arrayContext="col._array ? arrayContext(col) : arrayContextProp"
+              :data="col._data"
               :root="rootData"
-              :path="fieldPath(col)"
+              :path="[path, col.paths].filter(Boolean).join('.')"
               :index="index"
-              :idx="childIdx(col, idx)"
-              :rows="col.attrs?.['ui-row'] ?? rows"
-              :style="col.attrs?.['ui-flex'] ? { display: 'contents' } : undefined"
+              :idx="baseIdx"
               :mode="mode"
-              :interacted="interacted"
-              :colon="colon"
-              :labelClass="labelClass"
-              :labelWidth="labelWidth"
-              :vertical="vertical"
+              :interacted="touched"
               :debug="debug"
-            >
-              <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
-            </FormLoader>
-          </div>
+              rows=""
+              class="w-full"
+              ui-flex="row lm"
+            />
+            <h6 v-else-if="labelText(col.label) && isVertical(col)" :style="showStar(col) ? 'text-indent: -1em' : undefined" :class="labelClass || undefined" v-bind="labelAttrs(col.label)">
+              <slot v-if="labelSlot(col)" :name="labelSlot(col)" :col="col" :node="col" :data="col._data" :text="formatLabel(col)"></slot>
+              <template v-else-if="labelText(col.label) !== '*' && showStar(col)"><b class="co-risk pr" style="left: 0.1em">﹡</b>{{ formatLabel(col) }}</template>
+              <template v-else-if="labelText(col.label) !== '*'">{{ formatLabel(col) }}</template>
+            </h6>
+            <p v-else-if="labelText(col.label)" :class="[labelClass, clh({ ...(col.model[1] || {}) })]" :style="labelStyle(col)" class="ar nr-sm flex-fixed o-ls" v-bind="labelAttrs(col.label)">
+              <slot v-if="labelSlot(col)" :name="labelSlot(col)" :col="col" :node="col" :data="col._data" :text="formatLabel(col)"></slot>
+              <template v-else-if="labelText(col.label) !== '*' && showStar(col)"><b class="co-risk">﹡</b>{{ formatLabel(col) }}</template>
+              <template v-else-if="labelText(col.label) !== '*'">{{ formatLabel(col) }}</template>
+            </p>
 
-          <!-- 数组：每一行是一个子表单，支持增删和排序 -->
-          <div v-else-if="col._array" class="flex-block">
-            <div ui-row="">
-              <div v-for="(row, i) in listOf(col)" :key="rowKey(row)" :ui-col="col._array.attrs?.['ui-col'] || 'mob-24'" ui-flex="row lt" class="mb-xs" v-bind="col._array.attrs || {}">
-                <div class="flex-block">
-                  <FormLoader
-                    :form="col._array.child"
-                    :arrayContext="arrayContext(col, row)"
-                    :data="row"
-                    :root="rootData"
-                    :path="`${fieldPath(col)}.${i}`"
-                    :index="i"
-                    :idx="`${childIdx(col, idx)}-${i}`"
-                    :rows="col._array.rows || col.attrs?.['ui-row'] || rows"
-                    :mode="mode"
-                    :interacted="interacted"
-                    :colon="colon"
-                    :labelClass="labelClass"
-                    :labelWidth="labelWidth"
-                    :vertical="vertical"
-                    :debug="debug"
-                  >
+            <div v-if="isGroup(col)" v-bind="boxAttrs(col)">
+              <FormLoader v-bind="childProps(col)">
+                <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
+              </FormLoader>
+            </div>
+
+            <div v-else-if="col._array" class="flex-block">
+              <div v-if="listOf(col).length" ui-row>
+                <div v-for="(row, i) in listOf(col)" :key="rowKey(row)" v-bind="rowAttrs(col)">
+                  <div v-if="hasActions(col)" v-bind="rowBox(col)">
+                    <FormLoader v-bind="rowProps(col, row, i)">
+                      <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
+                    </FormLoader>
+                  </div>
+                  <FormLoader v-else v-bind="rowProps(col, row, i)">
                     <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
                   </FormLoader>
-                </div>
-                <div v-if="editable && (hasSlot(`${col.field}-actions`) || col._array.sortable || col._array.del !== false)" class="flex-fixed nl-sm" ui-flex="row lm">
-                  <slot v-if="hasSlot(`${col.field}-actions`)" :name="`${col.field}-actions`" v-bind="rowScope(col, i)"></slot>
-                  <template v-else>
-                    <template v-if="col._array.sortable">
-                      <button ui-btn="@a s" type="button" :disabled="i === 0" @click="moveRow(col, i, -1)">上移</button>
-                      <button ui-btn="@a s" type="button" class="ml-xs" :disabled="i === listOf(col).length - 1" @click="moveRow(col, i, 1)">下移</button>
+                  <div v-if="hasActions(col)" class="flex-fixed nl-sm" ui-flex="row lm">
+                    <slot v-if="hasSlot(`${col.field}-actions`)" :name="`${col.field}-actions`" v-bind="rowScope(col, i)"></slot>
+                    <template v-else>
+                      <template v-if="col._array.sortable">
+                        <button ui-btn="@a s" type="button" :disabled="i === 0" @click="moveRow(col, i, -1)">上移</button>
+                        <button ui-btn="@a s" type="button" class="ml-xs" :disabled="i === listOf(col).length - 1" @click="moveRow(col, i, 1)">下移</button>
+                      </template>
+                      <button
+                        v-if="col._array.del !== false"
+                        ui-btn="@a s risk"
+                        type="button"
+                        class="ml-xs"
+                        :disabled="listOf(col).length <= (col._array.min || 0)"
+                        @click="removeRow(col, i)"
+                      >
+                        {{ col._array.del || '删除' }}
+                      </button>
                     </template>
-                    <button
-                      v-if="col._array.del !== false"
-                      ui-btn="@a s risk"
-                      type="button"
-                      class="ml-xs"
-                      :disabled="listOf(col).length <= (col._array.min || 0)"
-                      @click="removeRow(col, i)"
-                    >
-                      {{ col._array.del || '删除' }}
-                    </button>
-                  </template>
+                  </div>
                 </div>
               </div>
+              <template v-if="editable && col._array.add !== false">
+                <slot v-if="hasSlot(`${col.field}-add`)" :name="`${col.field}-add`" :col="col" :list="listOf(col)" :add="() => addRow(col)"></slot>
+                <button v-else ui-btn="@a s" type="button" :disabled="!!col._array.max && listOf(col).length >= col._array.max" @click="addRow(col)">
+                  {{ col._array.add || '+ 添加一项' }}
+                </button>
+              </template>
+              <div v-if="!editable && !listOf(col).length" class="lh-ls">-</div>
+              <FieldMessage :col="col" :mode="mode" />
             </div>
-            <template v-if="editable && col._array.add !== false">
-              <slot v-if="hasSlot(`${col.field}-add`)" :name="`${col.field}-add`" :col="col" :list="listOf(col)" :add="() => addRow(col)"></slot>
-              <button v-else ui-btn="@a s" type="button" :disabled="!!col._array.max && listOf(col).length >= col._array.max" @click="addRow(col)">
-                {{ col._array.add || '+ 添加一项' }}
-              </button>
-            </template>
-            <div v-if="!editable && !listOf(col).length" class="lh-ls">-</div>
-            <FieldMessage :col="col" :mode="mode" />
-          </div>
 
-          <!-- 叶节点：输入、内容、按钮和自定义控件使用相同的 value / event -->
-          <FormRender v-else :col="col" :mode="mode" :entry="resolveEntry(col)" :interacted="touched" :ctx="context()" :custom="(!editable && hasSlot(`${col.field}-value`)) || !resolveEntry(col)">
-            <slot v-if="!editable && hasSlot(`${col.field}-value`)" :name="`${col.field}-value`" v-bind="fieldScope(col)"></slot>
-            <template v-else>
-              <slot v-if="col.model[0]" :name="col.model[0]" v-bind="fieldScope(col)"></slot>
-              <slot v-else :name="col.field" v-bind="fieldScope(col)"></slot>
-            </template>
-          </FormRender>
-        </template>
-      </div>
+            <FormRender v-else :col="col" :mode="mode" :entry="resolveEntry(col)" :interacted="touched" :ctx="context()" :custom="(!editable && hasSlot(`${col.field}-value`)) || !resolveEntry(col)">
+              <slot v-if="!editable && hasSlot(`${col.field}-value`)" :name="`${col.field}-value`" v-bind="fieldScope(col)"></slot>
+              <template v-else>
+                <slot v-if="col.slot" :name="col.slot" v-bind="fieldScope(col)"></slot>
+                <slot v-else-if="col.model[0]" :name="col.model[0]" v-bind="fieldScope(col)"></slot>
+                <slot v-else :name="col.field" v-bind="fieldScope(col)"></slot>
+              </template>
+            </FormRender>
+          </template>
+        </div>
+      </template>
     </template>
-    <div v-if="$slots.submit" :ui-flex="`${vertical ? 'col xm' : 'row xt'}`">
-      <div v-if="vertical">
-        <slot name="submit"></slot>
-      </div>
-      <div v-else :style="submitStyle">
+    <div v-if="!bare && $slots.submit" :ui-flex="vertical ? 'col xm' : 'row xt'">
+      <div :style="vertical ? undefined : submitStyle || undefined">
         <slot name="submit"></slot>
       </div>
     </div>
-  </div>
+  </Level>
 </template>
 <script lang="ts" setup>
-  import { watch, reactive, shallowRef, onMounted, onBeforeUnmount, useAttrs, useSlots, computed, provide, inject, toRaw, nextTick, readonly, watchEffect } from 'vue';
+  import { Comment, h, watch, reactive, shallowRef, onMounted, onBeforeUnmount, useAttrs, useSlots, computed, provide, inject, toRaw, nextTick, watchEffect, useId, isReactive, isReadonly } from 'vue';
   import { useRoute, useRouter } from 'vue-router';
   import { isString, isObject, deepcopy, isArray, isFunction } from '@fekit/utils';
   import FormRender, { getField, emptyValueOf, clh, isEmpty, labelText, labelAttrs, rulesOf, displayOf, valueBinding, labelNodes, eventsOf, writeValue, FieldMessage } from './FormRender.vue';
-  import type { FormArrayContext, FormContext, FormError, FormValidateResult, LinkageTask, FormRule } from './FormRender.vue';
+  import type { PropType, ShallowRef } from 'vue';
+  import type { FormItem, FormArrayContext, FormContext, FormError, FormValidateResult, LinkageTask, FormRule } from './FormRender.vue';
+
+  // 层级根：最外层输出 div（接收透传属性），分组 / 数组内部的层级（bare）只输出子节点；
+  // 顶层的条件占位注释（没有 submit 等）一并过滤，客户端与 SSR 一致。模板根部不能有注释，否则透传属性失效。
+  const Level: any = (props: { bare?: boolean }, { slots, attrs }: any) => {
+    const children = (slots.default?.() || []).filter((node: any) => node.type !== Comment);
+    return props.bare ? children : h('div', attrs, children);
+  };
+  Level.props = ['bare'];
+  Level.inheritAttrs = false;
+
+  // 未传 idx 时的 id 前缀：由 useId 算出的 6 位短串，SSR 与客户端一致，同页多个表单不冲突
+  const shortHash = (text: string) => {
+    let h = 2166136261;
+    for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619);
+    return (h >>> 0).toString(36).padStart(6, '0').slice(-6);
+  };
 
+  // child 两种写法：节点数组，或 { attrs, lists }（兼容 child 作为 lists 的别名）；动态配置交给联动
+  const isChildBox = (child: any) => isObject(child) && !isArray(child) && !isFunction(child.setup) && child.watch === undefined
+    && (isArray(child.lists) || isArray(child.child) || child.attrs !== undefined);
+  const childList = (child: any): any[] | null => (isArray(child) ? child : isChildBox(child) ? child.lists || child.child || [] : null);
   // 计算Label宽度
   const clw = (label: any = '') => {
     let emWidth = 0;
@@ -185,12 +155,12 @@
     return emWidth;
   };
 
-  // 路径缺失时补全对象，不把嵌套字段静默写到根层。
-  const resolvePath = (data: any, paths: string = '') => {
+  // 路径缺失时补全对象，不把嵌套字段静默写到根层；onCreate 用于记录新建对象的初始值。
+  const ensurePath = (data: any, paths: string = '', onCreate?: (target: any, key: string) => void) => {
     let target = data;
     (paths?.split('.') || []).forEach((key: string) => {
       if (!key) return;
-      if (target[key] == null) { target[key] = {}; recordInitial(target, key); }
+      if (target[key] == null) { target[key] = {}; onCreate?.(target, key); }
       if (!isObject(target[key])) throw new TypeError(`[FormLoader] paths 的 ${key} 必须是对象`);
       target = target[key];
     });
@@ -254,6 +224,13 @@
     return _model;
   };
 
+  // child: { attrs, lists } 拆成子节点数组和容器属性
+  const splitChild = (item: any) => {
+    if (!isChildBox(item.child)) return;
+    item._childAttrs = item.child.attrs;
+    item.child = childList(item.child);
+  };
+
   // 规范化数组配置，兼容旧版 array: 'field' 和 lists
   const normalizeArray = (array: any) => {
     if (isString(array)) return { child: [{ field: array }] };
@@ -266,12 +243,13 @@
     const row: any = {};
     list.forEach((item: any = {}) => {
       if (!isObject(item)) return;
-      const target = resolvePath(row, item.paths);
-      if (isArray(item.child) && !item.array) {
+      const target = ensurePath(row, item.paths);
+      const child = childList(item.child);
+      if (child && !item.array) {
         if (item.field) {
-          target[item.field] = createRow(item.child, getEmpty);
+          target[item.field] = createRow(child, getEmpty);
         } else {
-          Object.assign(target, createRow(item.child, getEmpty));
+          Object.assign(target, createRow(child, getEmpty));
         }
       } else if (item.field) {
         target[item.field] = getEmpty(item);
@@ -314,18 +292,83 @@
     });
   };
 
+  // 可写的数据视图：未写入的字段直接读原数据（响应式读取，便于精确追踪依赖），写入与删除只进入覆盖层。
+  const DELETED = Symbol('deleted');
+  const plainObject = (value: any) => !!value && typeof value === 'object' && !(value instanceof Date);
+  const dataView = (source: any, onRead?: () => void): any => {
+    if (!plainObject(source)) return source;
+    const src = isReactive(source) || isReadonly(source) ? source : reactive(source);
+    const array = isArray(toRaw(src));
+    const overlay = new Map<PropertyKey, any>();
+    const children = new Map<PropertyKey, { raw: any; view: any }>();
+    const read = (key: PropertyKey) => {
+      // Vue 内部标记（__v_raw、__v_isReactive 等）按普通对象处理，视图本身不是响应式对象。
+      if (typeof key === 'string' && key.startsWith('__v_')) return undefined;
+      if (overlay.has(key)) {
+        const value = overlay.get(key);
+        return value === DELETED ? undefined : value;
+      }
+      // 方法取原生函数（不走 Vue 的数组方法包装），调用时通过视图逐项读取，依赖仍然精确。
+      const native = Reflect.get(toRaw(src), key);
+      if (typeof native === 'function') return native;
+      onRead?.();
+      const value = Reflect.get(src, key);
+      if (!plainObject(value) || typeof key === 'symbol') return value;
+      const cached = children.get(key);
+      if (cached && cached.raw === toRaw(value)) return cached.view;
+      const view = dataView(value, onRead);
+      children.set(key, { raw: toRaw(value), view });
+      return view;
+    };
+    const exists = (key: PropertyKey) => (typeof key === 'string' && key.startsWith('__v_') ? false : overlay.has(key) ? overlay.get(key) !== DELETED : (onRead?.(), Reflect.has(src, key)));
+    return new Proxy(array ? [] : {}, {
+      get: (_, key) => read(key),
+      set: (_, key, value) => { overlay.set(key, value); children.delete(key); return true; },
+      deleteProperty: (_, key) => { overlay.set(key, DELETED); children.delete(key); return true; },
+      defineProperty: (_, key, descriptor) => { overlay.set(key, descriptor.value); children.delete(key); return true; },
+      has: (_, key) => exists(key),
+      ownKeys: () => {
+        onRead?.();
+        const keys = new Set<string | symbol>(Reflect.ownKeys(src));
+        overlay.forEach((value, key) => (value === DELETED ? keys.delete(key as string | symbol) : keys.add(key as string | symbol)));
+        if (array) {
+          const length = read('length');
+          keys.forEach((key) => { if (typeof key === 'string' && /^\d+$/.test(key) && Number(key) >= length) keys.delete(key); });
+        }
+        return [...keys];
+      },
+      getOwnPropertyDescriptor: (_, key) => {
+        if (!exists(key)) return undefined;
+        if (array && key === 'length') return { value: read(key), writable: true, enumerable: false, configurable: false };
+        return { value: read(key), writable: true, enumerable: true, configurable: true };
+      },
+      getPrototypeOf: () => Reflect.getPrototypeOf(toRaw(src)),
+    });
+  };
+
+  // 动态属性联动：函数或 { value, setup, watch }；按实际读取的字段追踪依赖，丢弃过期的异步结果
+  // 联动引擎需要的共享状态：数据版本（watch: true 与 await 后读取的回退）、结构版本、未完成的异步任务
+  interface LinkageShared {
+    dataVersion: ShallowRef<number>;
+    revision: number;
+    pending: Set<Promise<any>>;
+  }
+
   interface LinkageOptions {
     // 按下标取当前渲染的字段
     target: (idx: number) => any;
-    // 联动上下文：根数据、当前层数据、行下标、路由等
+    // 联动上下文：根数据、当前层数据、行下标、路由等；属性按需读取，未用到的不产生依赖
     context: () => FormContext;
+    shared: LinkageShared;
+    // 把联动结果写回字段（规范化 model / array、初始化子结构由表单负责）
+    apply: (target: any, key: string, result: any) => void;
   }
 
   // 带 setup 或 watch 的对象才是联动配置，attrs 等普通对象原样保留
   const isLinkage = (val: any) => isObject(val) && (isFunction(val.setup) || isArray(val.watch) || val.watch === true);
 
   // 动态属性：函数或 { value, setup, watch }，监听字段变化时重新计算，支持 Promise
-  const useLinkage = ({ target: getTarget, context }: LinkageOptions) => {
+  const useLinkage = ({ target: getTarget, context, shared, apply: applyResult }: LinkageOptions) => {
     // 结构变化时重建字段监听；普通字段变化只触发对应的联动任务
     const unwatchs: Array<() => void> = [];
     const pendingRuns = new Map<LinkageTask, () => void>();
@@ -339,14 +382,11 @@
       });
     };
 
-    // 传给联动函数的根数据是只读的，联动只改字段配置，不改数据
-    const call = (setup: any, item: any, used?: () => void) => {
+    // 联动函数拿到的是可写的数据视图：读取直接访问表单数据，Vue 只按实际读到的字段收集依赖；
+    // 写入只落在视图自己的覆盖层，不改动表单数据（与 4.x 传副本的语义一致）。
+    const call = (setup: any, item: any, onRead?: () => void) => {
       const ctx = context();
-      const track = (data: any) => new Proxy(readonly(data), {
-        get(target, key, receiver) { used?.(); return Reflect.get(target, key, receiver); },
-        ownKeys(target) { used?.(); return Reflect.ownKeys(target); },
-        has(target, key) { used?.(); return Reflect.has(target, key); },
-      });
+      const track = (data: any) => dataView(data, onRead);
       // 统一回调协议，不通过参数个数猜测用途。path 保持已发布版路由含义。
       const scope = new Proxy(ctx, {
         get: (target, key) => key === 'path' ? ctx.route?.path : key === 'formPath' ? ctx.path
@@ -370,15 +410,25 @@
         // 处理函数
         if (isFunction(val)) {
           const fn = val;
-          let usesData = false;
+          // 同步读取由 computed 精确追踪；异步函数在 await 之后才读取的数据无法追踪，
+          // 一旦出现就退回到跟随根数据版本重算。
+          let lateReads = false;
           const version = shallowRef(0);
-          unwatchs.push(watch(() => context().root, () => {
-            if (usesData) version.value++;
-          }, { deep: true, flush: 'sync' }));
+          unwatchs.push(watch(shared.dataVersion, () => {
+            if (lateReads) version.value++;
+          }));
           // 初次解析与监听共用计算结果，避免异步函数被重复调用。
           const evaluated = computed(() => {
             version.value;
-            return call(fn, reactive(item), () => { usesData = true; });
+            let evaluating = true;
+            let settled = false;
+            const result = call(fn, reactive(item), () => {
+              if (!evaluating && !settled) lateReads = true;
+            });
+            evaluating = false;
+            if (result instanceof Promise) result.then(() => (settled = true), () => (settled = true));
+            else settled = true;
+            return result;
           });
           val = evaluated.value;
           if (isLinkage(val)) {
@@ -396,12 +446,12 @@
           } else {
             hasInitialResult = true;
             initialResult = val;
-            val = { value: val instanceof Promise ? undefined : val, setup: () => evaluated.value, watch: true };
+            val = { value: val instanceof Promise ? undefined : val, setup: () => evaluated.value, watch: true, source: () => evaluated.value };
           }
         }
         if (isLinkage(val)) {
-          const { value = null, setup = () => {}, watch: _watch = [] } = val || {};
-          tasks.push({ idx, key, value, setup, watch: _watch, hasInitialResult, initialResult });
+          const { value = null, setup = () => {}, watch: _watch = [], source } = val || {};
+          tasks.push({ idx, key, value, setup, watch: _watch, hasInitialResult, initialResult, source });
           item[key] = value;
         } else {
           item[key] = val;
@@ -415,7 +465,7 @@
       const taskRuns = new Map<LinkageTask, number>();
       const runsetup = (task: LinkageTask) => {
         if (current !== generation) return;
-        const { idx, key, value, setup } = task;
+        const { idx, key, setup } = task;
         const target = getTarget(idx);
         if (target && isFunction(setup)) {
           pendingRuns.get(task)?.();
@@ -426,12 +476,10 @@
           const isCurrent = () => current === generation && getTarget(idx) === target && taskRuns.get(task) === runId;
           const apply = (result: any) => {
             shared.revision++;
-            target[key] = key === 'model' ? normalizeModel(result) : result;
-            if (key === 'array') target._array = result ? normalizeArray(result) : null;
-            if (key === 'child' || key === 'array') initializeField(target);
+            applyResult(target, key, result);
           };
           if (v instanceof Promise) {
-            nextTick(() => { if (isCurrent()) apply(value); });
+            // 等待期间保留上一次的结果，避免选项、标题等先变空再出现。
             let release!: () => void;
             const pending = new Promise<void>(resolve => { release = resolve; });
             const finish = () => {
@@ -466,10 +514,10 @@
           const { watch: keys } = task;
           if (keys === true) {
             task.hasInitialResult = false;
-            unwatchs.push(watchEffect(() => {
-              deepcopy(context().root);
+            // 函数属性只在计算结果变化时应用；联动配置的 watch: true 跟随根数据版本。
+            unwatchs.push(watch(task.source || shared.dataVersion, () => {
               runsetup(task);
-            }));
+            }, { immediate: true }));
             return;
           }
           unwatchs.push(
@@ -487,6 +535,7 @@
     return { stop, resolve, start };
   };
 
+
   const route = useRoute();
   const router = useRouter();
   const attrs = useAttrs();
@@ -503,12 +552,12 @@
     },
     // JSON规则
     form: {
-      type: Array,
+      type: Array as PropType<FormItem[]>,
       default: () => [],
     },
     // 表单数据
     data: {
-      type: Object as any,
+      type: Object as PropType<Record<string, any>>,
       default: () => ({}),
     },
     // 栅格系统
@@ -552,6 +601,11 @@
       default: false,
     },
     // 以下由分组和数组内部传递
+    // 内部层级：不输出根元素，子节点直接落在上一层的容器里
+    bare: {
+      type: Boolean,
+      default: false,
+    },
     // 根表单数据，联动函数和 watch 都基于它
     root: {
       type: Object as any,
@@ -575,7 +629,7 @@
   interface Shared {
     state: { lw: number; validated: boolean };
     cache: ClearCache;
-    instances: Set<{ collect: () => any[] }>;
+    instances: Set<{ collect: () => any[]; hidden: () => string[] }>;
     snapshot: any;
     initialObjects: WeakMap<object, any>;
     pending: Set<Promise<any>>;
@@ -583,6 +637,10 @@
     validationEpoch: number;
     cancelChecks: Set<() => void>;
     validations: WeakMap<object, { input: any; epoch: number; pending: boolean; result: Promise<any> }>;
+    // 根数据任意变化时递增，供 watch: true 的联动共用
+    dataVersion: ShallowRef<number>;
+    // 外部回填的错误（如服务端校验），按字段路径保存；字段值变化后自动失效
+    serverErrors: Map<string, { msg: string; type: string; input: any }>;
   }
   const FORM_SHARED = Symbol.for('neatui:form-loader');
   const shared: Shared = (props.root && inject<Shared | null>(FORM_SHARED, null)) || {
@@ -596,10 +654,15 @@
     validationEpoch: 0,
     cancelChecks: new Set(),
     validations: new WeakMap(),
+    dataVersion: shallowRef(0),
+    serverErrors: reactive(new Map()),
   };
   provide(FORM_SHARED, shared);
 
   const rootData = computed(() => props.root || props.data);
+  // 根表单未传 idx 时用 useId 生成前缀，同页多个表单的同名字段 id 不再冲突；SSR 与客户端一致。
+  const autoIdx = `f${shortHash(useId())}`;
+  const baseIdx = computed(() => (props.idx !== '' ? String(props.idx) : props.root ? '' : autoIdx));
   const cancelValidation = () => {
     shared.validationEpoch++;
     shared.cancelChecks.forEach(cancel => cancel());
@@ -616,7 +679,7 @@
   };
   const captureInitial = () => {
     shared.initialObjects = new WeakMap();
-    shared.snapshot = cloneInitial(props.data);
+    shared.snapshot = cloneInitial(rootData.value);
     shared.cache = new WeakMap();
     cancelValidation();
   };
@@ -627,6 +690,7 @@
   if (!props.root) captureInitial();
   watch(() => props.data, () => {
     shared.revision++;
+    if (!props.root) shared.dataVersion.value++;
   }, { deep: true, flush: 'sync' });
   const editable = computed(() => props.mode !== 'view');
   // 调用过 validate 后所有字段展示校验状态
@@ -666,6 +730,10 @@
     const label = labelText(col.label);
     if (!label) return '';
     if (/[:：]\s*$/.test(label)) return label;
+    // 4.x 兼容：字段级 colon 优先，false 不显示，string 自定义字符，true 为 ':'
+    if (col.colon === false) return label;
+    if (isString(col.colon)) return `${label}${col.colon}`;
+    if (col.colon === true) return `${label}:`;
     // 自定义节点树和标签属性可以直接决定呈现；默认文本标签跟随表单冒号。
     if ((isGroup(col) || col._array || col.array) && isVertical(col)) return label;
     const suffix = isString(props.colon) ? props.colon : props.colon ? ':' : '';
@@ -679,6 +747,106 @@
   // 整行插槽
   const rowSlot = (col: any = {}) => (col.field && hasSlot(`${col.field}-row`) ? `${col.field}-row` : '');
 
+  // ---- 渲染结构：节点即元素，只补 id / ui-col / 布局 / 调试 / 隐藏，空值不输出 ----
+  // 模板分支：${field}-row 整行插槽 → 无标题分组（节点元素即容器）→ 标题（节点树 / h6 / p，插槽 ${field}-label、array-label、child-label、label）
+  // → 有标题分组（标题 + 内容容器）→ 数组（行；有操作按钮时分字段区与按钮区）→ 字段（控件 + 错误提示；字段级 slot 兼容 4.x）
+  const hasLabel = (col: any = {}) => !!labelNodes(col.label) || !!labelText(col.label);
+  // 无标题的 Text / Html / Button 内容节点直接输出内容元素
+  const isBareContent = (col: any = {}) => !col.field && !isGroup(col) && !col._array && !hasLabel(col) && !rowSlot(col)
+    && ['Text', 'Html', 'Button'].includes(col.model?.[0]);
+  // 所在层有栅格时才输出 ui-col；分组、数组默认占满一行；false 不用栅格
+  const mediaOf = (col: any = {}) => (!props.rows || col.media === false ? undefined : col.media || (isGroup(col) || col._array ? 'mob-24' : undefined));
+  const joinClass = (...list: any[]) => {
+    const out = list.filter((v) => v !== undefined && v !== null && v !== '' && !(isArray(v) && !v.length));
+    return out.length ? (out.length === 1 ? out[0] : out) : undefined;
+  };
+  // 子节点容器：child.attrs（可为函数）+ 这一层的栅格；ui-flex 布局时不加栅格和默认间距；写了 class 时由外部接管间距（与根元素一致）
+  const childAttrsOf = (col: any) => {
+    const attrs = col._childAttrs;
+    return (isFunction(attrs) ? attrs(col._data, col, context()) : attrs) || {};
+  };
+  const levelOf = (col: any, flex?: string, styled = false) => {
+    const { 'ui-row': row, ...own } = childAttrsOf(col);
+    const layout = own['ui-flex'] ?? flex;
+    const rows = col.media === false || layout ? '' : String(row ?? col.attrs?.['ui-row'] ?? props.rows ?? '');
+    return { rows, attrs: { ...own, 'ui-row': rows || undefined, class: 'class' in own ? own.class : layout || styled ? undefined : 'n-sl-sub' } };
+  };
+  // 节点元素；无标题分组的节点元素同时是下一层容器
+  const nodeAttrs = (col: any) => {
+    const { 'ui-row': _row, ...own } = col.attrs || {};
+    const out: Record<string, any> = { ...own };
+    const group = isGroup(col);
+    const box = group && !hasLabel(col) && !rowSlot(col);
+    if (col._fid) out.id = col._fid;
+    const media = mediaOf(col);
+    if (media) out['ui-col'] = media;
+    if (box) {
+      // 无标题分组的节点元素就是容器：节点写了 class 时不再加默认间距
+      const level = levelOf(col, own['ui-flex'], own.class !== undefined).attrs;
+      Object.assign(out, level, { class: joinClass(own.class, level.class) });
+    } else if (!isBareContent(col) && own['ui-flex'] === undefined) {
+      out['ui-flex'] = isVertical(col) ? 'col xm' : 'row lt';
+    }
+    if (props.debug) {
+      out['data-path'] = fieldPath(col) || undefined;
+      out.title = debugInfo(col);
+    }
+    if (isCleared(col)) out.style = joinClass(own.style, { display: 'none' });
+    return out;
+  };
+  // 有标题分组的子节点容器
+  const boxAttrs = (col: any) => {
+    const { attrs } = levelOf(col);
+    return { ...attrs, class: joinClass('flex-block', attrs.class) };
+  };
+  const levelProps = () => ({
+    bare: true,
+    root: rootData.value,
+    mode: props.mode,
+    interacted: props.interacted,
+    colon: props.colon,
+    labelClass: props.labelClass,
+    labelWidth: props.labelWidth,
+    vertical: props.vertical,
+    debug: props.debug,
+    idx: baseIdx.value,
+  });
+  const childProps = (col: any) => ({
+    ...levelProps(),
+    form: col.child || [],
+    clearContext: { value: isCleared(col), restore: canRestore(col) },
+    arrayContext: props.arrayContext,
+    data: childData(col),
+    path: fieldPath(col),
+    index: props.index,
+    rows: levelOf(col, hasLabel(col) ? undefined : col.attrs?.['ui-flex']).rows,
+  });
+  // 数组：行栅格、行元素、行内字段区
+  const hasActions = (col: any) => editable.value && (hasSlot(`${col.field}-actions`) || !!col._array.sortable || col._array.del !== false);
+  const rowRows = (col: any) => (col.media === false ? '' : col._array.rows || col.attrs?.['ui-row'] || props.rows || '');
+  const rowAttrs = (col: any) => {
+    const own = col._array.attrs || {};
+    const out: Record<string, any> = { ...own, 'ui-col': own['ui-col'] || 'mob-24', class: joinClass('mb-xs', own.class) };
+    if (hasActions(col)) {
+      if (own['ui-flex'] === undefined) out['ui-flex'] = 'row lt';
+    } else if (own['ui-flex'] === undefined) {
+      // 没有操作按钮时行元素本身承载这一行的字段
+      out['ui-row'] = rowRows(col) || undefined;
+      out.class = joinClass('mb-xs', own.class ?? 'n-sl-sub');
+    }
+    return out;
+  };
+  const rowBox = (col: any) => ({ class: 'flex-block n-sl-sub', 'ui-row': rowRows(col) || undefined });
+  const rowProps = (col: any, row: any, i: number) => ({
+    ...levelProps(),
+    form: col._array.child,
+    arrayContext: arrayContext(col, row),
+    data: row,
+    path: `${fieldPath(col)}.${i}`,
+    index: i,
+    rows: hasActions(col) || (col._array.attrs || {})['ui-flex'] === undefined ? rowRows(col) : '',
+  });
+
   // 表单默认标签宽度；单个标签用 label[1].style 覆盖。
   const widthOf = (value: any) => {
     if (value === 'auto') return '';
@@ -691,9 +859,8 @@
     return style ? style.replace(/^width:([^;]+);.*$/, 'padding-left:$1;') : '';
   });
 
-  // 分组、数组的路径和 id 前缀
+  // 字段数据路径（也是字段 id 的主体）
   const fieldPath = (col: any = {}) => [props.path, col.paths, col.field].filter(Boolean).join('.');
-  const childIdx = (col: any = {}, idx: number) => [props.idx, col.field || `g${idx}`].filter((v: any) => v !== '').join('-');
   const childData = (col: any = {}) => (col.field ? col._data[col.field] : col._data);
   const listOf = (col: any = {}) => (isArray(col._data?.[col.field]) ? col._data[col.field] : []);
 
@@ -703,6 +870,7 @@
   // 控件：已注册的 model；没写 model 且没有对应插槽时默认 Input
   const resolveEntry = (col: any = {}) => {
     const model = col.model?.[0];
+    if (col.slot && !getField(model)) return undefined;
     if (model) return getField(model);
     if (col.field && hasSlot(col.field)) return undefined;
     return getField(col.field ? 'Input' : 'Text');
@@ -712,7 +880,7 @@
   const initialOf = (item: any = {}) => {
     if (valueBinding(item.value) && item.value.default !== undefined) return deepcopy(item.value.default);
     if (item.array) return [];
-    if (isArray(item.child)) return {};
+    if (childList(item.child)) return {};
     return emptyValueOf(isString(item.model) || isArray(item.model) ? normalizeModel(item.model) : ['']);
   };
 
@@ -776,7 +944,31 @@
     form: [],
   });
 
-  const linkage = useLinkage({ target: (idx) => state.form[idx], context });
+  // 路径缺失时补全对象，并把新建的对象记入重置基线
+  const resolvePath = (data: any, paths: string = '') => ensurePath(data, paths, recordInitial);
+
+  // 按需读取的联动上下文：函数没用到的属性（如数组行上下文）变化时不触发重算。
+  const lazyContext = (): FormContext => ({
+    get root() { return rootData.value; },
+    get data() { return props.data; },
+    get index() { return props.index; },
+    get array() { return props.arrayContext; },
+    get path() { return props.path; },
+    get mode() { return props.mode; },
+    route,
+    router,
+  });
+  const linkage = useLinkage({
+    target: (idx) => state.form[idx],
+    context: lazyContext,
+    shared,
+    apply: (target, key, result) => {
+      target[key] = key === 'model' ? normalizeModel(result) : result;
+      if (key === 'array') target._array = result ? normalizeArray(result) : null;
+      if (key === 'child') splitChild(target);
+      if (key === 'child' || key === 'array') initializeField(target);
+    },
+  });
 
   // 初始结构和异步生成的子树都经过相同的数据初始化。
   const initializeField = (item: any) => {
@@ -814,6 +1006,7 @@
       if (isObject(item)) {
         linkage.resolve(item, idx, tasks);
       }
+      splitChild(item);
 
       item._array = item.array ? normalizeArray(item.array) : item._kind === 'array' ? { child: [] } : null;
 
@@ -830,7 +1023,7 @@
       }
 
       // 添加ID
-      item._fid = `form-${props.idx !== '' ? props.idx + '-' : ''}${!item.field && isGroup(item) ? `group-${idx}` : `field-${item.field || `node-${idx}`}`}`;
+      item._fid = item.field ? [baseIdx.value, fieldPath(item).replace(/\./g, '-')].filter(Boolean).join('-') : '';
 
       // 数据路径处理
       item._data = resolvePath(props.data, item.paths);
@@ -842,9 +1035,6 @@
         fields.add(key);
         initializeField(item);
       }
-
-      // 分组、数组默认占满一行
-      if ((isGroup(item) || item._array) && !item.media) item.media = 'mob-24';
       return item;
     });
     linkage.start(tasks);
@@ -873,14 +1063,15 @@
   watch(
     [() => state.form, () => props.data, () => props.clearContext],
     () => {
-      state.form.forEach((item: any = {}) => {
+      state.form.forEach((item: any = {}, idx: number) => {
         if (isGroup(item)) return; // 保留递归实例，由解析后的子节点各自清空和恢复。
         const cache = canRestore(item) ? shared.cache : undefined;
+        const key = item._fid || `#${idx}`;
         if (isCleared(item)) {
-          hiddenFields.add(item._fid);
+          hiddenFields.add(key);
           emptyField(resolvePath(props.data, item.paths), item.field, cache);
-        } else if (hiddenFields.has(item._fid) || firstRun) {
-          hiddenFields.delete(item._fid);
+        } else if (hiddenFields.has(key) || firstRun) {
+          hiddenFields.delete(key);
           if (cache) restoreField(resolvePath(props.data, item.paths), item.field, cache);
         }
       });
@@ -895,6 +1086,8 @@
       state.form
         .filter((col: any) => !isCleared(col) && col.field && !isGroup(col))
         .map((col: any) => ({ col, path: fieldPath(col), ctx: context() })),
+    // 当前层被隐藏（clear）的字段路径，供 getData({ visibleOnly }) 剔除
+    hidden: (): string[] => state.form.filter((col: any) => col.field && isCleared(col)).map((col: any) => fieldPath(col)),
   };
   onMounted(() => {
     shared.instances.add(instance);
@@ -917,7 +1110,10 @@
     const keys = Object.keys(a);
     return keys.length === Object.keys(b).length && keys.every(key => Object.prototype.hasOwnProperty.call(b, key) && sameInput(a[key], b[key]));
   };
-  const validateField = (col: any, ctx: FormContext, force = false): Promise<any> => {
+  // path 由收集字段的那一层计算（validate 在根表单调用时，嵌套字段的路径不能用根表单拼）
+  const validateField = (col: any, ctx: FormContext, path: string, force = false): Promise<any> => {
+    const server = shared.serverErrors.get(path);
+    if (server) return Promise.resolve({ msg: server.msg, type: server.type });
     const input = deepcopy([displayOf(col, ctx), rulesOf(col), col.model]);
     const previous = shared.validations.get(col);
     if (previous && previous.epoch === shared.validationEpoch && (!force || previous.pending) && sameInput(previous.input, input)) return previous.result;
@@ -930,7 +1126,7 @@
         error = message ? { msg: message, type: 'risk' } : await checkRules(input[0], input[1]);
       } catch { error = { msg: '校验失败，请重试', type: 'risk' }; }
       job.pending = false;
-      if (shared.validations.get(col) === job && shared.validationEpoch === job.epoch) { col._error = error; col._checked = true; }
+      if (shared.validations.get(col) === job && shared.validationEpoch === job.epoch && !shared.serverErrors.has(path)) { col._error = error; col._checked = true; }
       return error;
     })();
     return job.result;
@@ -938,11 +1134,22 @@
   watchEffect(() => {
     for (const col of state.form) {
       // 只读取校验输入，不监听内部错误结果；异步结果按执行顺序丢弃过期响应。
-      deepcopy(displayOf(col, context()));
+      const value = deepcopy(displayOf(col, context()));
       deepcopy(rulesOf(col));
       deepcopy(col.model);
+      // 回填的错误在字段值变化前一直显示，值一变就交回正常校验
+      const path = col.field ? fieldPath(col) : '';
+      const server = path ? shared.serverErrors.get(path) : undefined;
+      if (server && !isCleared(col)) {
+        if (sameInput(server.input, value)) {
+          col._error = { msg: server.msg, type: server.type };
+          col._checked = true;
+          continue;
+        }
+        shared.serverErrors.delete(path);
+      }
       if (col.field && !isGroup(col) && !isCleared(col) && (touched.value || col._touched)) {
-        void validateField(col, context());
+        void validateField(col, context(), path);
       } else {
         shared.validations.delete(col);
         col._error = null;
@@ -970,15 +1177,19 @@
     nextTick(() => el.scrollIntoView({ behavior: 'smooth', block: 'center' }));
   };
 
-  // 校验所有已显示的字段（包含分组和数组），warn 类型只作为提醒，不影响 valid
-  const validate = async ({ scroll = false }: { scroll?: boolean } = {}): Promise<FormValidateResult> => {
+  // 路径匹配：'contact' 包含 'contact.phone'，'members.0' 包含该行全部字段
+  const withinPaths = (path: string, paths?: string[]) => !paths || paths.some((p) => path === p || path.startsWith(`${p}.`));
+
+  // 校验已显示的字段（包含分组和数组），warn 类型只作为提醒，不影响 valid；paths 限定只校验这些路径
+  const validate = async ({ scroll = false, paths }: { scroll?: boolean; paths?: string[] } = {}): Promise<FormValidateResult> => {
     const epoch = shared.validationEpoch;
     const cancelledResult = (): FormValidateResult => ({ valid: false, errors: [{ field: '', path: '', label: '', msg: '表单已重置或切换，请重新校验', type: 'risk' }], warnings: [] });
     let cancel!: () => void;
     const cancelled = new Promise<FormValidateResult>(resolve => { cancel = () => resolve(cancelledResult()); });
     shared.cancelChecks.add(cancel);
     const run = async (): Promise<FormValidateResult> => {
-      shared.state.validated = true;
+      // 局部校验只让这些字段显示提示，其他字段保持原状
+      if (!paths) shared.state.validated = true;
       let results: any[];
       let revision: number;
       do {
@@ -990,8 +1201,9 @@
           if (shared.pending.size) await Promise.all([...shared.pending]);
         } while (revision !== shared.revision || shared.pending.size);
         revision = shared.revision;
-        results = await Promise.all(fieldsOf().map(async ({ col, path, ctx }) => {
-          const res = await validateField(col, ctx, true);
+        results = await Promise.all(fieldsOf().filter(({ path }) => withinPaths(path, paths)).map(async ({ col, path, ctx }) => {
+          if (paths) col._touched = true;
+          const res = await validateField(col, ctx, path, true);
           return res ? { field: col.field, path, label: labelText(col.label), msg: res.msg, type: res.type, fid: col._fid } : null;
         }));
         if (epoch !== shared.validationEpoch) return cancelledResult();
@@ -1021,10 +1233,66 @@
 
   const clearValidate = () => {
     cancelValidation();
+    shared.serverErrors.clear();
     shared.validations = new WeakMap();
     shared.state.validated = false;
     fieldsOf().forEach(({ col }) => { col._touched = false; col._error = null; col._checked = false; });
   };
 
-  defineExpose({ validate, reset, clearValidate, scrollToField });
+  // 回填外部错误（如服务端校验结果）：{ 'contact.phone': '号码已被占用' } 或 [{ path, msg, type }]。
+  // 字段值变化后错误自动消失；返回没有匹配到已显示字段的路径，便于改用全局提示。
+  const setErrors = (errors: Record<string, string | { msg: string; type?: string }> | Array<{ path: string; msg: string; type?: string }>, { scroll = false }: { scroll?: boolean } = {}): string[] => {
+    const list: Array<{ path: string; msg: string; type?: string }> = Array.isArray(errors)
+      ? errors
+      : Object.entries(errors || {}).map(([path, error]) => (isString(error) ? { path, msg: error } : { path, ...(error as any) }));
+    const fields = fieldsOf();
+    const missing: string[] = [];
+    list.forEach(({ path, msg, type = 'risk' }) => {
+      const found = fields.find((item) => item.path === path);
+      if (!found) return missing.push(path);
+      shared.serverErrors.set(path, { msg, type, input: deepcopy(displayOf(found.col, found.ctx)) });
+    });
+    const first = list.find((item) => !missing.includes(item.path));
+    if (scroll && first) scrollToField(first.path);
+    return missing;
+  };
+
+  // 与初始值（挂载时的数据及自动补全的默认值，或 setBaseline 之后的数据）比较，返回变化的字段路径
+  const getChanges = (): string[] => {
+    const changes: string[] = [];
+    const diff = (current: any, initial: any, path: string) => {
+      if (sameInput(current, initial)) return;
+      const bothArrays = isArray(current) && isArray(initial);
+      const bothObjects = isPlain(current) && isPlain(initial);
+      if ((bothArrays && current.length === initial.length) || bothObjects) {
+        const keys = new Set([...Object.keys(current), ...Object.keys(initial)]);
+        keys.forEach((key) => diff(current[key], initial[key], path ? `${path}.${key}` : key));
+      } else changes.push(path);
+    };
+    diff(toRaw(rootData.value), shared.snapshot, '');
+    return changes;
+  };
+  const isDirty = (path?: string) => getChanges().some((item) => !path || withinPaths(item, [path]) || withinPaths(path, [item]));
+
+  // 把当前数据设为新的初始值：同一对象上加载记录（Object.assign）或保存成功后调用，reset() 与 isDirty() 以它为准
+  const setBaseline = () => captureInitial();
+
+  // 取数据副本；visibleOnly 时去掉被 clear 隐藏的字段
+  const getData = ({ visibleOnly = false }: { visibleOnly?: boolean } = {}) => {
+    const data = deepcopy(toRaw(rootData.value));
+    if (visibleOnly) {
+      [...shared.instances].flatMap((item) => item.hidden()).forEach((path) => {
+        const keys = path.split('.');
+        const last = keys.pop() as string;
+        const parent = keys.reduce((target: any, key) => (target == null ? undefined : target[key]), data);
+        if (parent && typeof parent === 'object') delete parent[last];
+      });
+    }
+    return data;
+  };
+
+  // 插槽名由字段名、model 名动态生成，参数随插槽种类不同；字段与控件插槽的参数见 FormSlotScope
+  defineSlots<Record<string, (scope: any) => any>>();
+
+  defineExpose({ validate, reset, clearValidate, scrollToField, setErrors, getChanges, isDirty, setBaseline, getData });
 </script>