@neatui/vue 4.8.1 → 5.0.0

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

@@ -1,173 +1,153 @@
 <template>
   <div :ui-row="rows" :class="rootClass">
     <template v-for="(col, idx) in state.form" :key="idx">
-      <div v-if="!col.clear" :id="col._fid" :ui-col="col.media" :ui-flex="`${vertical ? 'col xm' : 'row lt'}`">
-        <template v-if="col.label">
-          <h6 v-if="vertical" :style="`${col.rules?.some((validator: any) => validator.required) ? 'text-indent: -1em' : ''}`" :class="labelClass">
-            <template v-if="col.label == '*'"></template>
-            <template v-else>
-              <b v-if="col.rules?.some((validator: any) => validator.required)" class="co-risk pr" style="left: 0.1em">﹡</b>
-              <span>{{ formatLabel(col) }}</span>
+      <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>
+
+          <!-- 分组：递归渲染，带 field 时写入 data[field]，否则和当前层共用数据 -->
+          <div v-if="isGroup(col)" class="flex-block" :style="col.attrs?.['ui-flex'] ? { display: 'contents' } : undefined">
+            <FormLoader
+              :form="col.child || []"
+              :clearContext="{ value: isCleared(col), restore: canRestore(col) }"
+              :arrayContext="arrayContextProp"
+              :data="childData(col)"
+              :root="rootData"
+              :path="fieldPath(col)"
+              :index="index"
+              :idx="childIdx(col, idx)"
+              :rows="col.attrs?.['ui-row'] ?? rows"
+              :style="col.attrs?.['ui-flex'] ? { display: 'contents' } : undefined"
+              :mode="mode"
+              :interacted="interacted"
+              :colon="colon"
+              :labelClass="labelClass"
+              :labelWidth="labelWidth"
+              :vertical="vertical"
+              :debug="debug"
+            >
+              <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 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"
+                  >
+                    <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>
+                    </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>
-          </h6>
-          <p v-else :class="[labelClass, `${clh({ ...(col.model[1] || {}) })}`]" :style="`width:${state._lw + 'em'}; max-width:50%;`" class="ar nr-sm flex-fixed o-ls">
-            <template v-if="col.label == '*'"></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>
-              <b v-if="col.rules?.some((validator: any) => validator.required)" class="co-risk">﹡</b>
-              <span>{{ formatLabel(col) }}</span>
+              <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>
-          </p>
-        </template>
-        <Input v-if="col.model[0] === 'Input'" v-model="col._data[col.field]" :interacted="interacted" :rules="col.rules" class="w-full" v-bind="{ ...(col.model[1] || {}) }" />
-        <Select
-          v-else-if="col.model[0] === 'Select'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col?.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        ></Select>
-        <SelectList
-          v-else-if="col.model[0] === 'SelectList'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col?.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <SelectTags
-          v-else-if="col.model[0] === 'SelectTags'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col?.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <SelectPicker
-          v-else-if="col.model[0] === 'SelectPicker'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col?.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <SearchSelect
-          v-else-if="col.model[0] === 'SearchSelect'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <MoreSelect
-          v-else-if="col.model[0] === 'MoreSelect'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <MoreSelectList
-          v-else-if="col.model[0] === 'MoreSelectList'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <MoreSelectTags
-          v-else-if="col.model[0] === 'MoreSelectTags'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <MoreSelectPicker
-          v-else-if="col.model[0] === 'MoreSelectPicker'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <SearchMoreSelect
-          v-else-if="col.model[0] === 'SearchMoreSelect'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <PageSelect
-          v-else-if="col.model[0] === 'PageSelect'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <SelectTree
-          v-else-if="col.model[0] === 'SelectTree'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <DatePicker
-          v-else-if="col.model[0] === 'DatePicker'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <DateRangePicker
-          v-else-if="col.model[0] === 'DateRangePicker'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <ImgUpload v-else-if="col.model[0] === 'ImgUpload'" v-model="col._data[col.field]" :interacted="interacted" :rules="col.rules" v-bind="{ ...(col.model[1] || {}) }" />
-        <Upload v-else-if="col.model[0] === 'Upload'" v-model="col._data[col.field]" :interacted="interacted" :rules="col.rules" v-bind="{ ...(col.model[1] || {}) }" />
-        <Textarea
-          v-else-if="col.model[0] === 'Textarea'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :rules="col.rules"
-          v-bind="{ ...(col.model[1] || {}) }"
-        ></Textarea>
-        <Switch v-else-if="col.model[0] === 'Switch'" v-model="col._data[col.field]" :interacted="interacted" :rules="col.rules" v-bind="{ ...(col.model[1] || {}) }" />
-        <Checkbox v-else-if="col.model[0] === 'Checkbox'" v-model="col._data[col.field]" :interacted="interacted" :rules="col.rules" v-bind="{ ...(col.model[1] || {}) }" />
-        <Tree v-else-if="col.model[0] === 'Tree'" v-model="col._data[col.field]" :interacted="interacted" :rules="col.rules" class="mt-sm" v-bind="{ ...(col.model[1] || {}) }" />
-        <Cascader
-          v-else-if="col.model[0] === 'Cascader'"
-          v-model="col._data[col.field]"
-          :interacted="interacted"
-          :options="col.enums"
-          :rules="col.rules"
-          class="w-full"
-          v-bind="{ ...(col.model[1] || {}) }"
-        />
-        <template v-else>
-          <slot v-if="col.slot" :name="col.slot" :col="col"></slot>
-          <slot v-else-if="col.model[0]" :name="col.model[0]" :col="col"></slot>
-          <slot v-else :name="col.field" :col="col"></slot>
+          </FormRender>
         </template>
       </div>
     </template>
@@ -175,60 +155,27 @@
       <div v-if="vertical">
         <slot name="submit"></slot>
       </div>
-      <div v-else :style="`padding-left:${state._lw + 'em'};`">
+      <div v-else :style="submitStyle">
         <slot name="submit"></slot>
       </div>
     </div>
   </div>
 </template>
 <script lang="ts" setup>
-  import { watch, reactive, onBeforeUnmount, nextTick, useAttrs, computed } from 'vue';
+  import { watch, reactive, shallowRef, onMounted, onBeforeUnmount, useAttrs, useSlots, computed, provide, inject, toRaw, nextTick, readonly, watchEffect } from 'vue';
   import { useRoute, useRouter } from 'vue-router';
-  import { isString, isObject, isFunction, deepcopy, isArray } from '@fekit/utils';
-  import {
-    Input,
-    Switch,
-    Checkbox,
-    Textarea,
-    Select,
-    SelectList,
-    SelectTags,
-    SelectPicker,
-    SearchSelect,
-    PageSelect,
-    SelectTree,
-    MoreSelect,
-    MoreSelectList,
-    MoreSelectTags,
-    MoreSelectPicker,
-    DatePicker,
-    DateRangePicker,
-    SearchMoreSelect,
-    ImgUpload,
-    Upload,
-    Cascader,
-  } from '../../form';
-  import { Tree } from '../../display';
-
-  const route = useRoute();
-  const router = useRouter();
-  const attrs = useAttrs();
-  // 外部写了 class 时去掉默认根 class，由外部接管
-  const rootClass = computed(() => (attrs.class ? undefined : 'n-sl-sub'));
-
-  // 计算Label行高
-  const clh = ({ sz = '' }: any = {}) => {
-    const lhs: any = { xs: 'lh-sm', s: 'lh-mm', m: 'lh-ls', l: 'lh-ll', xl: 'lh-xl' };
-    return lhs[sz] || 'lh-ls';
-  };
+  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';
 
   // 计算Label宽度
-  function clw(label: any = '') {
+  const clw = (label: any = '') => {
     let emWidth = 0;
     if (isString(label)) {
       for (let i = 0; i < label.length; i++) {
         const char = label[i];
-        if (/^[\u4e00-\u9fa5]+$/.test(char)) {
+        // 汉字、中文标点和全角字符按 1em 计算
+        if (/^[\u3000-\u303f\u4e00-\u9fa5\uff00-\uffef]$/.test(char)) {
           emWidth += 1;
         } else {
           emWidth += 0.5;
@@ -236,8 +183,317 @@
       }
     }
     return emWidth;
+  };
+
+  // 路径缺失时补全对象，不把嵌套字段静默写到根层。
+  const resolvePath = (data: any, paths: string = '') => {
+    let target = data;
+    (paths?.split('.') || []).forEach((key: string) => {
+      if (!key) return;
+      if (target[key] == null) { target[key] = {}; recordInitial(target, key); }
+      if (!isObject(target[key])) throw new TypeError(`[FormLoader] paths 的 ${key} 必须是对象`);
+      target = target[key];
+    });
+    return target;
+  };
+
+  // 按 'a.b.c' 读取数据
+  const readPath = (data: any, path: string = '') =>
+    String(path)
+      .split('.')
+      .reduce((target: any, key: string) => (target === null || target === undefined ? undefined : target[key]), data);
+
+  // 同类型的空值
+  const emptyOf = (value: any) => {
+    if (isArray(value)) return [];
+    if (typeof value === 'boolean') return false;
+    return '';
+  };
+
+  // 隐藏字段的值暂存在这里，重新显示时还原
+  type ClearCache = WeakMap<object, Map<string, any>>;
+
+  // 清空单个字段；restore 为 true 时先暂存原值。已为空时不再赋值，避免新数组反复触发 deep watcher
+  const emptyField = (data: any, field: string = '', cache?: ClearCache) => {
+    if (!data || !field) return;
+    const value = data[field];
+    if (isEmpty(value) || value === false) return;
+    if (cache) {
+      const saved = cache.get(data) || new Map();
+      saved.set(field, value);
+      cache.set(data, saved);
+    }
+    data[field] = emptyOf(value);
+  };
+
+  // 还原单个字段；只在当前仍为空时还原，避免覆盖用户新填的值
+  const restoreField = (data: any, field: string = '', cache?: ClearCache) => {
+    const saved = data && cache?.get(data);
+    if (!saved || !saved.has(field)) return;
+    if (isEmpty(data[field]) || data[field] === false) {
+      data[field] = saved.get(field);
+    }
+    saved.delete(field);
+  };
+
+  // 规范化 model 为 [type, props]，props 默认 verify: false
+  const normalizeModel = (model: any) => {
+    let _model = model;
+    if (_model) {
+      if (isString(_model)) {
+        _model = [_model, { verify: false }];
+      }
+    } else {
+      _model = ['', { verify: false }];
+    }
+    if (!_model[1]) {
+      _model[1] = { verify: false };
+    } else if (!Object.prototype.hasOwnProperty.call(_model[1], 'verify')) {
+      _model[1].verify = false;
+    }
+    return _model;
+  };
+
+  // 规范化数组配置，兼容旧版 array: 'field' 和 lists
+  const normalizeArray = (array: any) => {
+    if (isString(array)) return { child: [{ field: array }] };
+    if (!isObject(array)) return null;
+    return { ...array, child: array.child || array.lists || [] };
+  };
+
+  // 按字段配置生成一条新数据，用于数组新增行
+  const createRow = (list: any[] = [], getEmpty: (item: any) => any, preset: any = {}) => {
+    const row: any = {};
+    list.forEach((item: any = {}) => {
+      if (!isObject(item)) return;
+      const target = resolvePath(row, item.paths);
+      if (isArray(item.child) && !item.array) {
+        if (item.field) {
+          target[item.field] = createRow(item.child, getEmpty);
+        } else {
+          Object.assign(target, createRow(item.child, getEmpty));
+        }
+      } else if (item.field) {
+        target[item.field] = getEmpty(item);
+      }
+    });
+    return { ...row, ...deepcopy(isFunction(preset) ? preset() : preset) };
+  };
+
+  // 与组件内一致的校验：有值时跑 validator，无值时只看 required
+  const checkRules = async (value: any, rules: FormRule[] = []) => {
+    if (!isArray(rules)) return null;
+    if (!isEmpty(value)) {
+      for (const rule of rules) {
+        if (rule && isFunction(rule.validator) && !(await rule.validator!(value))) {
+          return { msg: rule.msg || '', type: rule.type || 'risk' };
+        }
+      }
+      return null;
+    }
+    const rule = rules.find((item) => item?.required);
+    return rule ? { msg: rule.msg || '', type: rule.type || 'risk' } : null;
+  };
+
+  const isPlain = (value: any) => isObject(value) && !isArray(value);
+
+  // 原地重置：保留嵌套对象的引用（分组绑定的是对象本身），快照里没有的字段置为同类型空值
+  const assignDeep = (target: any, source: any) => {
+    if (!isPlain(target)) return;
+    const keys = new Set([...Object.keys(target), ...Object.keys(source || {})]);
+    keys.forEach((key) => {
+      const from = source ? source[key] : undefined;
+      const to = target[key];
+      if (isPlain(to) && (isPlain(from) || from === undefined)) {
+        assignDeep(to, from || {});
+      } else if (source && Object.prototype.hasOwnProperty.call(source, key)) {
+        target[key] = deepcopy(from);
+      } else {
+        target[key] = emptyOf(to);
+      }
+    });
+  };
+
+  interface LinkageOptions {
+    // 按下标取当前渲染的字段
+    target: (idx: number) => any;
+    // 联动上下文：根数据、当前层数据、行下标、路由等
+    context: () => FormContext;
   }
 
+  // 带 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 unwatchs: Array<() => void> = [];
+    const pendingRuns = new Map<LinkageTask, () => void>();
+    let generation = 0;
+    const stop = () => {
+      generation += 1;
+      pendingRuns.forEach(finish => finish());
+      pendingRuns.clear();
+      unwatchs.splice(0).forEach((unwatch) => {
+        unwatch();
+      });
+    };
+
+    // 传给联动函数的根数据是只读的，联动只改字段配置，不改数据
+    const call = (setup: any, item: any, used?: () => 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); },
+      });
+      // 统一回调协议，不通过参数个数猜测用途。path 保持已发布版路由含义。
+      const scope = new Proxy(ctx, {
+        get: (target, key) => key === 'path' ? ctx.route?.path : key === 'formPath' ? ctx.path
+          : key === 'root' || key === 'data' ? track(ctx[key])
+          : key in target ? Reflect.get(target, key) : Reflect.get(ctx.route || {}, key),
+        has: (target, key) => key === 'formPath' || key in target || key in (ctx.route || {}),
+        ownKeys: target => [...new Set([...Reflect.ownKeys(ctx.route || {}), ...Reflect.ownKeys(target), 'formPath'])],
+        getOwnPropertyDescriptor: (target, key) => key === 'formPath' || key in target || key in (ctx.route || {})
+          ? { enumerable: true, configurable: true } : undefined,
+      });
+      return setup(track(ctx.root), item, scope, ctx.router);
+    };
+
+    // 解析字段上的动态属性，写入初始值并收集任务
+    const resolve = (item: any, idx: number, tasks: LinkageTask[]) => {
+      for (const key in item) {
+        // 假值（false、0、''）原样保留，不能当作联动配置
+        let val = item[key];
+        let hasInitialResult = false;
+        let initialResult: any;
+        // 处理函数
+        if (isFunction(val)) {
+          const fn = val;
+          let usesData = false;
+          const version = shallowRef(0);
+          unwatchs.push(watch(() => context().root, () => {
+            if (usesData) version.value++;
+          }, { deep: true, flush: 'sync' }));
+          // 初次解析与监听共用计算结果，避免异步函数被重复调用。
+          const evaluated = computed(() => {
+            version.value;
+            return call(fn, reactive(item), () => { usesData = true; });
+          });
+          val = evaluated.value;
+          if (isLinkage(val)) {
+            // 函数返回联动配置但没写 setup 时，之后每次重新执行函数并取它的 value
+            if (!isFunction(val.setup)) {
+              val.setup = (_data: any, current: any) => {
+                const res = call(fn, current);
+                return isLinkage(res) ? res.value : res;
+              };
+            }
+            // 未声明 watch 时监听全部数据
+            if (!isArray(val.watch)) {
+              val.watch = true;
+            }
+          } else {
+            hasInitialResult = true;
+            initialResult = val;
+            val = { value: val instanceof Promise ? undefined : val, setup: () => evaluated.value, watch: true };
+          }
+        }
+        if (isLinkage(val)) {
+          const { value = null, setup = () => {}, watch: _watch = [] } = val || {};
+          tasks.push({ idx, key, value, setup, watch: _watch, hasInitialResult, initialResult });
+          item[key] = value;
+        } else {
+          item[key] = val;
+        }
+      }
+    };
+
+    // 执行任务：不声明 watch 的只执行一次，其余按监听字段重新计算
+    const start = (tasks: LinkageTask[]) => {
+      const current = generation;
+      const taskRuns = new Map<LinkageTask, number>();
+      const runsetup = (task: LinkageTask) => {
+        if (current !== generation) return;
+        const { idx, key, value, setup } = task;
+        const target = getTarget(idx);
+        if (target && isFunction(setup)) {
+          pendingRuns.get(task)?.();
+          const runId = (taskRuns.get(task) || 0) + 1;
+          taskRuns.set(task, runId);
+          const v = task.hasInitialResult ? task.initialResult : call(setup, target);
+          task.hasInitialResult = false;
+          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);
+          };
+          if (v instanceof Promise) {
+            nextTick(() => { if (isCurrent()) apply(value); });
+            let release!: () => void;
+            const pending = new Promise<void>(resolve => { release = resolve; });
+            const finish = () => {
+              shared.pending.delete(pending);
+              if (pendingRuns.get(task) === finish) pendingRuns.delete(task);
+              release();
+            };
+            pendingRuns.set(task, finish);
+            shared.pending.add(pending);
+            v.then(async (res: any) => {
+              await nextTick();
+              if (isCurrent()) apply(res);
+            }).catch((error: unknown) => {
+              if (isCurrent()) console.warn(`[FormLoader] ${key} 联动失败`, error);
+            }).finally(finish);
+          } else nextTick(() => { if (isCurrent()) apply(v); });
+        }
+      };
+      // 点路径从根数据读取，'.' 开头从当前层读取
+      const read = (key: string) => {
+        const ctx = context();
+        return key.startsWith('.') ? readPath(ctx.data, key.slice(1)) : readPath(ctx.root, key);
+      };
+      const once = (task: LinkageTask) => Array.isArray(task.watch) && !task.watch.length;
+      tasks.filter(once).forEach((task) => {
+        runsetup(task);
+      });
+      // 每个动态属性只建立一个 watcher，多个依赖在同一轮变化时只执行一次
+      tasks
+        .filter((task) => !once(task))
+        .forEach((task) => {
+          const { watch: keys } = task;
+          if (keys === true) {
+            task.hasInitialResult = false;
+            unwatchs.push(watchEffect(() => {
+              deepcopy(context().root);
+              runsetup(task);
+            }));
+            return;
+          }
+          unwatchs.push(
+            watch(
+              () => keys.map((key: string) => read(key)),
+              () => {
+                runsetup(task);
+              },
+              { deep: true, immediate: true },
+            ),
+          );
+        });
+    };
+
+    return { stop, resolve, start };
+  };
+
+  const route = useRoute();
+  const router = useRouter();
+  const attrs = useAttrs();
+  const slots = useSlots();
+  // 外部写了 class 时去掉默认根 class，由外部接管
+  const rootClass = computed(() => (attrs.class ? undefined : 'n-sl-sub'));
+
   // 入参
   const props: any = defineProps({
     // 用户是否交互
@@ -247,8 +503,8 @@
     },
     // JSON规则
     form: {
-      type: Object,
-      default: () => ({}),
+      type: Array,
+      default: () => [],
     },
     // 表单数据
     data: {
@@ -275,197 +531,500 @@
       type: [String, Array, Object],
       default: '',
     },
+    // 统一的label宽度：数字为 em，'auto' 为自适应，不传时按最长的 label 计算
+    labelWidth: {
+      type: [Number, String],
+      default: undefined,
+    },
     // 是否垂直排列
     vertical: {
       type: Boolean,
       default: false,
     },
+    // edit 编辑 | view 查看
+    mode: {
+      type: String,
+      default: 'edit',
+    },
+    // 调试：字段容器带上 data-path 和 title，重建时在控制台输出解析后的配置
+    debug: {
+      type: Boolean,
+      default: false,
+    },
+    // 以下由分组和数组内部传递
+    // 根表单数据，联动函数和 watch 都基于它
+    root: {
+      type: Object as any,
+      default: null,
+    },
+    // 当前层在根数据中的路径
+    path: {
+      type: String,
+      default: '',
+    },
+    arrayContext: { type: Object as () => FormArrayContext, default: undefined },
+    clearContext: { type: Object as () => { value: boolean; restore: boolean }, default: undefined },
+    // 数组行下标
+    index: {
+      type: Number,
+      default: undefined,
+    },
   });
 
+  // 各层级共享：Label 宽度、校验状态、隐藏字段暂存、已挂载的表单实例
+  interface Shared {
+    state: { lw: number; validated: boolean };
+    cache: ClearCache;
+    instances: Set<{ collect: () => any[] }>;
+    snapshot: any;
+    initialObjects: WeakMap<object, any>;
+    pending: Set<Promise<any>>;
+    revision: number;
+    validationEpoch: number;
+    cancelChecks: Set<() => void>;
+    validations: WeakMap<object, { input: any; epoch: number; pending: boolean; result: Promise<any> }>;
+  }
+  const FORM_SHARED = Symbol.for('neatui:form-loader');
+  const shared: Shared = (props.root && inject<Shared | null>(FORM_SHARED, null)) || {
+    state: reactive({ lw: 6, validated: false }),
+    cache: new WeakMap(),
+    instances: new Set(),
+    snapshot: null,
+    initialObjects: new WeakMap(),
+    pending: new Set(),
+    revision: 0,
+    validationEpoch: 0,
+    cancelChecks: new Set(),
+    validations: new WeakMap(),
+  };
+  provide(FORM_SHARED, shared);
+
+  const rootData = computed(() => props.root || props.data);
+  const cancelValidation = () => {
+    shared.validationEpoch++;
+    shared.cancelChecks.forEach(cancel => cancel());
+    shared.cancelChecks.clear();
+  };
+  // 将初始对象与快照对象对应；异步补出的默认值写入快照，用户后来新增的行不写入。
+  const cloneInitial = (value: any): any => {
+    if (!value || typeof value !== 'object' || value instanceof Date) return deepcopy(value);
+    const raw = toRaw(value);
+    const copy: any = isArray(value) ? [] : {};
+    shared.initialObjects.set(raw, copy);
+    Object.keys(value).forEach(key => { copy[key] = cloneInitial(value[key]); });
+    return copy;
+  };
+  const captureInitial = () => {
+    shared.initialObjects = new WeakMap();
+    shared.snapshot = cloneInitial(props.data);
+    shared.cache = new WeakMap();
+    cancelValidation();
+  };
+  const recordInitial = (data: any, key: string) => {
+    const initial = shared.initialObjects.get(toRaw(data));
+    if (initial) initial[key] = cloneInitial(data[key]);
+  };
+  if (!props.root) captureInitial();
+  watch(() => props.data, () => {
+    shared.revision++;
+  }, { deep: true, flush: 'sync' });
+  const editable = computed(() => props.mode !== 'view');
+  // 调用过 validate 后所有字段展示校验状态
+  const touched = computed(() => props.interacted || shared.state.validated);
+
+  const arrayContextProp = computed(() => props.arrayContext);
+
+  // 联动上下文
+  const context = (): FormContext => ({ root: rootData.value, data: props.data, index: props.index, array: props.arrayContext, path: props.path, mode: props.mode, route, router });
+
+  // value 保留原始值兼容已有插槽；bind.modelValue 使用显示转换后的值。
+  const fieldScope = (col: any) => {
+    const ctx = context();
+    const update = (value: any) => {
+      if (!editable.value || !col.field) return;
+      col._touched = true;
+      writeValue(col, value, context());
+      eventsOf(col, context())['update:modelValue']?.(value);
+    };
+    return {
+      col, node: col, data: col._data, mode: props.mode, value: col._data?.[col.field], ctx,
+      update,
+      bind: { modelValue: displayOf(col, ctx), 'onUpdate:modelValue': update, disabled: !editable.value },
+    };
+  };
+
+  // 字段未设置 vertical 时跟随表单
+  const isVertical = (col: any = {}) => (col.vertical === undefined || col.vertical === null ? props.vertical : !!col.vertical);
+  const isGroup = (col: any = {}) => (col._kind === 'child' || isArray(col.child)) && !col._array;
+  const isCleared = (col: any) => !!props.clearContext?.value || (isObject(col.clear) ? !!col.clear.value : !!col.clear);
+  const canRestore = (col: any) => props.clearContext?.restore !== false && !(isObject(col.clear) && col.clear.restore === false);
+  const hasSlot = (name: string) => !!slots[name];
+  const showStar = (col: any = {}) => editable.value && rulesOf(col).some((rule: any) => rule?.required);
+
   // label展示文案，支持全局/单个字段开关冒号
   const formatLabel = (col: any = {}) => {
-    const { label = '', colon: localColon = undefined } = col || {};
+    const label = labelText(col.label);
     if (!label) return '';
     if (/[:：]\s*$/.test(label)) return label;
-    const suffix = (() => {
-      if (localColon === false) return '';
-      if (isString(localColon)) return localColon;
-      if (localColon === true) return ':';
-      if (isString(props.colon)) return props.colon;
-      return props.colon ? ':' : '';
-    })();
+    // 自定义节点树和标签属性可以直接决定呈现；默认文本标签跟随表单冒号。
+    if ((isGroup(col) || col._array || col.array) && isVertical(col)) return label;
+    const suffix = isString(props.colon) ? props.colon : props.colon ? ':' : '';
     return suffix ? `${label}${suffix}` : label;
   };
+  // 标签插槽：${field}-label > array-label / child-label > label
+  const labelSlot = (col: any = {}) => {
+    const names = [col.field && `${col.field}-label`, col._array && 'array-label', isGroup(col) && 'child-label', 'label'];
+    return (names.find((name) => name && hasSlot(name)) as string) || '';
+  };
+  // 整行插槽
+  const rowSlot = (col: any = {}) => (col.field && hasSlot(`${col.field}-row`) ? `${col.field}-row` : '');
+
+  // 表单默认标签宽度；单个标签用 label[1].style 覆盖。
+  const widthOf = (value: any) => {
+    if (value === 'auto') return '';
+    const n = Number(value);
+    return `width:${value !== undefined && value !== '' && !isNaN(n) ? n : shared.state.lw}em; max-width:50%;`;
+  };
+  const labelStyle = (col: any = {}) => widthOf(props.labelWidth);
+  const submitStyle = computed(() => {
+    const style = widthOf(props.labelWidth);
+    return style ? style.replace(/^width:([^;]+);.*$/, 'padding-left:$1;') : '';
+  });
+
+  // 分组、数组的路径和 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] : []);
+
+  // submit 只在最外层渲染，其余插槽透传给分组和数组
+  const childSlots = () => Object.keys(slots).filter((name) => name !== 'submit');
+
+  // 控件：已注册的 model；没写 model 且没有对应插槽时默认 Input
+  const resolveEntry = (col: any = {}) => {
+    const model = col.model?.[0];
+    if (model) return getField(model);
+    if (col.field && hasSlot(col.field)) return undefined;
+    return getField(col.field ? 'Input' : 'Text');
+  };
+
+  // 字段缺失时的初始值：default > 数组 [] > 分组 {} > 控件空值
+  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 {};
+    return emptyValueOf(isString(item.model) || isArray(item.model) ? normalizeModel(item.model) : ['']);
+  };
+
+  // 数组
+  const rowKeys = new WeakMap<object, number>();
+  let rowSeq = 0;
+  // 行的稳定 key，不往数据里写额外字段
+  const rowKey = (row: any) => {
+    if (!isObject(row)) return row;
+    if (!rowKeys.has(row)) rowKeys.set(row, (rowSeq += 1));
+    return rowKeys.get(row);
+  };
+  const newRow = (col: any) => createRow(col._array.child, initialOf, col._array.item);
+  const validIndex = (list: any[], i: number) => Number.isInteger(i) && i >= 0 && i < list.length;
+  const canAdd = (col: any) => editable.value && (!col._array.max || listOf(col).length < col._array.max);
+  const insertRow = (col: any, i: number) => {
+    const list = listOf(col);
+    if (!canAdd(col) || !Number.isInteger(i) || i < 0 || i > list.length) return;
+    col._touched = true;
+    list.splice(i, 0, newRow(col));
+  };
+  const addRow = (col: any) => insertRow(col, listOf(col).length);
+  const removeRow = (col: any, i: number) => {
+    const list = listOf(col);
+    if (!editable.value || !validIndex(list, i) || list.length <= (col._array.min || 0)) return;
+    col._touched = true;
+    list.splice(i, 1);
+  };
+  const moveRow = (col: any, i: number, step: number) => {
+    const list = listOf(col);
+    const j = i + step;
+    if (!editable.value || !validIndex(list, i) || !validIndex(list, j)) return;
+    const [row] = list.splice(i, 1);
+    list.splice(j, 0, row);
+  };
+  // 每次调用按行身份取下标，避免插入、排序或异步事件后误操作其他行。
+  const arrayContext = (col: any, row?: any): FormArrayContext => {
+    const ctx: FormArrayContext = {
+      get list() { return listOf(col); },
+      get row() { return row; },
+      get index() { return row === undefined ? -1 : listOf(col).indexOf(row); },
+      get canAdd() { return canAdd(col); },
+      get canRemove() { return editable.value && this.index >= 0 && this.list.length > (col._array.min || 0); },
+      get canMoveUp() { return editable.value && this.index > 0; },
+      get canMoveDown() { return editable.value && this.index >= 0 && this.index < this.list.length - 1; },
+      add: () => addRow(col),
+      insertAfter(i?: number) {
+        const index = i ?? ctx.index;
+        if (validIndex(ctx.list, index)) insertRow(col, index + 1);
+      },
+      remove() { removeRow(col, ctx.index); },
+      moveUp() { moveRow(col, ctx.index, -1); },
+      moveDown() { moveRow(col, ctx.index, 1); },
+    };
+    return ctx;
+  };
+  const rowScope = (col: any, i: number) => Object.assign(arrayContext(col, listOf(col)[i]), { col });
 
   // 数据
   const state: any = reactive({
     form: [],
-    _lw: 6,
   });
 
-  // 结构变化时重建字段监听；普通字段变化只触发对应的联动任务
-  const unwatchs: Array<() => void> = [];
-  let fieldWatcherGeneration = 0;
-  const clearFieldWatchers = () => {
-    fieldWatcherGeneration += 1;
-    unwatchs.splice(0).forEach((unwatch) => {
-      unwatch();
-    });
-    return fieldWatcherGeneration;
-  };
-  const rebuildFieldWatchers = (form: any = []) => {
-    const generation = clearFieldWatchers();
-    const watched: any[] = [];
-    const onces: any[] = [];
-    const taskRuns = new Map<any, number>();
-    state.form = deepcopy(form)?.map((item: any = {}, idx: number) => {
-      // 计算Label宽度
-      const _w = clw(item.label) + 2;
-      if (_w > state._lw) {
-        state._lw = _w;
+  const linkage = useLinkage({ target: (idx) => state.form[idx], context });
+
+  // 初始结构和异步生成的子树都经过相同的数据初始化。
+  const initializeField = (item: any) => {
+    if (!item.field || !item._data) return;
+    const target = item._data;
+    let changed = false;
+    if (item._array) {
+      if (!isArray(target[item.field])) {
+        const initial = initialOf(item);
+        target[item.field] = isArray(initial) ? initial : [];
+        changed = true;
+      }
+      while (target[item.field].length < (item._array.min || 0)) { target[item.field].push(newRow(item)); changed = true; }
+    } else if (isGroup(item)) {
+      if (!isObject(target[item.field]) || isArray(target[item.field])) {
+        const initial = initialOf(item);
+        target[item.field] = isObject(initial) && !isArray(initial) ? initial : {};
+        changed = true;
       }
+    } else if (target[item.field] === undefined) {
+      target[item.field] = initialOf(item);
+      changed = true;
+    }
+    if (changed) recordInitial(target, item.field);
+  };
 
+  // 结构变化时重建字段和联动
+  const rebuild = (form: any = []) => {
+    shared.revision++;
+    linkage.stop();
+    const tasks: LinkageTask[] = [];
+    const fields = new Set<string>();
+    state.form = (deepcopy(form) || []).map((item: any = {}, idx: number) => {
+      item._kind = item.array ? 'array' : Object.prototype.hasOwnProperty.call(item, 'child') ? 'child' : 'field';
       if (isObject(item)) {
-        for (const key in item) {
-          let val = item[key] || {};
-          let hasInitialResult = false;
-          let initialResult: any;
-          // 处理函数
-          if (isFunction(val)) {
-            const setup = val;
-            val = setup(deepcopy(props.data), props.form, route, router);
-            if (isObject(val)) {
-              if (!isFunction(val.setup)) {
-                val.setup = setup;
-              }
-              if (!isArray(val.watch)) {
-                val.watch = deepcopy(form).map(({ field = '' }: any = {}) => field);
-              }
-            } else {
-              hasInitialResult = true;
-              initialResult = val;
-              val = { value: val, setup, watch: deepcopy(form).map(({ field = '' }: any = {}) => field) };
-            }
-          }
-          // 对象处理
-          if (isObject(val)) {
-            const { value = null, setup = () => {}, watch: _watch = [] } = val || {};
-            const task = { idx, key, value, setup, watch: _watch, hasInitialResult, initialResult };
-            // 监听字段为空
-            if (_watch.length) {
-              watched.push(task);
-            } else {
-              onces.push(task);
-            }
-            item[key] = value;
-          } else {
-            item[key] = val;
-          }
-        }
+        linkage.resolve(item, idx, tasks);
       }
 
+      item._array = item.array ? normalizeArray(item.array) : item._kind === 'array' ? { child: [] } : null;
+
       // 模型处理
-      if (item.model) {
-        if (isString(item.model)) {
-          item.model = [item.model, { verify: false }];
+      item.model = normalizeModel(item.model || (!item.field && !item.child && !item.array ? 'Text' : undefined));
+
+      // 计算Label宽度：必填星号 + 文案（含冒号）+ 右边距
+      if (!isVertical(item)) {
+        const required = rulesOf(item).some((rule: any) => rule?.required);
+        const _w = (required ? 1 : 0) + clw(formatLabel(item)) + 1;
+        if (_w > shared.state.lw) {
+          shared.state.lw = _w;
         }
-      } else {
-        item.model = ['', { verify: false }];
-      }
-      if (item.model[1] && !Object.prototype.hasOwnProperty.call(item.model[1], 'verify')) {
-        item.model[1].verify = false;
       }
 
       // 添加ID
-      item._fid = `form-${props.idx !== '' ? props.idx + '-' : ''}field-${item.field}`;
+      item._fid = `form-${props.idx !== '' ? props.idx + '-' : ''}${!item.field && isGroup(item) ? `group-${idx}` : `field-${item.field || `node-${idx}`}`}`;
 
       // 数据路径处理
-      item._data = props.data;
-      (item.paths?.split('.') || [])?.forEach((i: any) => {
-        if (item._data[i]) {
-          item._data = item._data[i];
-        }
-      });
-      return item;
-    });
-    const runsetup = (item: any = {}) => {
-      if (generation !== fieldWatcherGeneration) return;
-      const { idx = null, key = null, value = null, setup = null }: any = item || {};
-      const target = state.form[idx];
-      if (target && isFunction(setup)) {
-        const runId = (taskRuns.get(item) || 0) + 1;
-        taskRuns.set(item, runId);
-        const v = item.hasInitialResult ? item.initialResult : setup(deepcopy(props.data), target, route, router);
-        item.hasInitialResult = false;
-        const isCurrent = () => generation === fieldWatcherGeneration && state.form[idx] === target && taskRuns.get(item) === runId;
-        nextTick(() => {
-          if (!isCurrent()) return;
-          if (v instanceof Promise) {
-            target[key] = value;
-            v.then((res: any) => {
-              if (isCurrent()) {
-                target[key] = res;
-              }
-            });
-          } else {
-            target[key] = v;
-          }
-        });
+      item._data = resolvePath(props.data, item.paths);
+
+      // 补全缺失的数据字段，重复字段给出提示
+      if (item.field) {
+        const key = `${item.paths || ''}.${item.field}`;
+        if (fields.has(key)) console.warn(`[FormLoader] 字段重复：${fieldPath(item)}`);
+        fields.add(key);
+        initializeField(item);
       }
-    };
-    // 不声明 watch 的任务只执行一次
-    onces.forEach((item: any = {}) => {
-      runsetup(item);
-    });
-    // 每个动态属性只建立一个 watcher，多个依赖在同一轮变化时只执行一次
-    watched.forEach((item: any = {}) => {
-      unwatchs.push(
-        watch(
-          () => item.watch.map((key: any) => props.data[key]),
-          () => {
-            runsetup(item);
-          },
-          { deep: true, immediate: true },
-        ),
-      );
+
+      // 分组、数组默认占满一行
+      if ((isGroup(item) || item._array) && !item.media) item.media = 'mob-24';
+      return item;
     });
+    linkage.start(tasks);
+    if (props.debug) console.debug(`[FormLoader] ${props.path || 'root'}`, deepcopy(toRaw(state.form)));
   };
+
+  // 调试信息
+  const debugInfo = (col: any = {}) => [fieldPath(col) || '(group)', col.model?.[0] || (isGroup(col) ? 'child' : col._array ? 'array' : 'Input')].join(' · ');
   watch(
     () => props.form,
     (form = []) => {
-      rebuildFieldWatchers(form);
+      rebuild(form);
     },
     { deep: true, immediate: true },
   );
-  watch(
-    [() => props.data, () => props.idx],
-    () => {
-      rebuildFieldWatchers(props.form);
-    },
-  );
+  watch([() => props.data, () => props.idx], ([data], [previous]) => {
+    if (!props.root && data !== previous) captureInitial();
+    rebuild(props.form);
+  });
 
-  // 处理
+  // 隐藏的字段清空数据并暂存，重新显示时还原（restore: false 时只清空）
+  // 只在「隐藏 → 显示」的那一次和首次运行时还原，避免和分组内的子表单来回争抢同一个值
+  // 分组重新显示时由重新挂载的子表单自己还原
+  const hiddenFields = new Set<string>();
+  let firstRun = true;
   watch(
-    [() => state.form, () => props.data],
+    [() => state.form, () => props.data, () => props.clearContext],
     () => {
       state.form.forEach((item: any = {}) => {
-        const { clear = false, field = '', paths = '' }: any = item;
-        if (clear) {
-          // 数据路径处理
-          let _data = props.data;
-          (paths?.split('.') || [])?.forEach((i: any) => {
-            if (_data[i]) {
-              _data = item._data[i];
-            }
-          });
-          _data[field] = isArray(_data[field]) ? [] : '';
+        if (isGroup(item)) return; // 保留递归实例，由解析后的子节点各自清空和恢复。
+        const cache = canRestore(item) ? shared.cache : undefined;
+        if (isCleared(item)) {
+          hiddenFields.add(item._fid);
+          emptyField(resolvePath(props.data, item.paths), item.field, cache);
+        } else if (hiddenFields.has(item._fid) || firstRun) {
+          hiddenFields.delete(item._fid);
+          if (cache) restoreField(resolvePath(props.data, item.paths), item.field, cache);
         }
       });
+      firstRun = false;
     },
-    { deep: true },
+    { deep: true, immediate: true },
   );
 
+  // 当前层可校验的字段（已显示、非分组）
+  const instance = {
+    collect: () =>
+      state.form
+        .filter((col: any) => !isCleared(col) && col.field && !isGroup(col))
+        .map((col: any) => ({ col, path: fieldPath(col), ctx: context() })),
+  };
+  onMounted(() => {
+    shared.instances.add(instance);
+    shared.revision++;
+  });
+
   onBeforeUnmount(() => {
-    clearFieldWatchers();
+    if (!props.root) cancelValidation();
+    shared.instances.delete(instance);
+    shared.revision++;
+    linkage.stop();
+  });
+
+  const fieldsOf = () => [...shared.instances].flatMap((item) => item.collect());
+
+  const sameInput = (a: any, b: any): boolean => {
+    if (Object.is(a, b)) return true;
+    if (a instanceof Date && b instanceof Date) return +a === +b;
+    if (!a || !b || typeof a !== 'object' || typeof b !== 'object') return false;
+    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> => {
+    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;
+    const job = { input, epoch: shared.validationEpoch, pending: true, result: null as any };
+    shared.validations.set(col, job);
+    job.result = (async () => {
+      let error;
+      try {
+        const message = await resolveEntry(col)?.validate?.(input[0], input[2]?.[1] || {});
+        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; }
+      return error;
+    })();
+    return job.result;
+  };
+  watchEffect(() => {
+    for (const col of state.form) {
+      // 只读取校验输入，不监听内部错误结果；异步结果按执行顺序丢弃过期响应。
+      deepcopy(displayOf(col, context()));
+      deepcopy(rulesOf(col));
+      deepcopy(col.model);
+      if (col.field && !isGroup(col) && !isCleared(col) && (touched.value || col._touched)) {
+        void validateField(col, context());
+      } else {
+        shared.validations.delete(col);
+        col._error = null;
+        col._checked = false;
+      }
+    }
   });
+
+  // 按页面位置排序
+  const byPosition = (a: any, b: any) => {
+    if (typeof document === 'undefined') return 0;
+    const ea = document.getElementById(a.fid);
+    const eb = document.getElementById(b.fid);
+    if (!ea || !eb) return 0;
+    return ea.compareDocumentPosition(eb) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+  };
+
+  // 滚动到指定路径的字段，比如 'contact.phone'、'members.0.name'
+  const scrollToField = (path: string) => {
+    const found = fieldsOf().find((item) => item.path === path);
+    const el = found && typeof document !== 'undefined' ? document.getElementById(found.col._fid) : null;
+    if (!el) return;
+    // 通用定位事件：由配置中的 event.reveal 展开折叠区、切换标签页等。
+    el.dispatchEvent(new CustomEvent('reveal', { bubbles: true, detail: { path } }));
+    nextTick(() => el.scrollIntoView({ behavior: 'smooth', block: 'center' }));
+  };
+
+  // 校验所有已显示的字段（包含分组和数组），warn 类型只作为提醒，不影响 valid
+  const validate = async ({ scroll = false }: { scroll?: boolean } = {}): 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;
+      let results: any[];
+      let revision: number;
+      do {
+        // Vue 渲染、联动和异步子树稳定后，再收集可校验字段。
+        do {
+          revision = shared.revision;
+          await nextTick();
+          if (epoch !== shared.validationEpoch) return cancelledResult();
+          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);
+          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();
+      } while (revision !== shared.revision);
+      const found = (results.filter(Boolean) as any[]).sort(byPosition);
+      const strip = ({ fid, ...rest }: any): FormError => rest;
+      const errors = found.filter((item) => item.type !== 'warn');
+      if (scroll && errors[0]) scrollToField(errors[0].path);
+      return { valid: !errors.length, errors: errors.map(strip), warnings: found.filter((item) => item.type === 'warn').map(strip) };
+    };
+    try { return await Promise.race([run(), cancelled]); }
+    finally { shared.cancelChecks.delete(cancel); }
+  };
+
+  // 还原到初始数据并清除校验状态
+  const reset = () => {
+    shared.cache = new WeakMap();
+    if (shared.snapshot) assignDeep(rootData.value, shared.snapshot);
+    const bindInitial = (data: any, initial: any) => {
+      if (!data || !initial || typeof data !== 'object' || typeof initial !== 'object') return;
+      shared.initialObjects.set(toRaw(data), initial);
+      Object.keys(initial).forEach(key => bindInitial(data[key], initial[key]));
+    };
+    bindInitial(rootData.value, shared.snapshot);
+    clearValidate();
+  };
+
+  const clearValidate = () => {
+    cancelValidation();
+    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 });
 </script>