@neatui/vue 4.8.2 → 5.1.0

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

@@ -1,173 +1,155 @@
 <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>
+              <!-- 4.x 兼容：字段级 slot 优先于 model / field 同名插槽 -->
+              <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>
-          </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 +157,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, watchEffect, useId, isReactive, isReadonly } 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 { PropType, ShallowRef } from 'vue';
+  import type { FormItem, 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 +185,388 @@
       }
     }
     return emWidth;
+  };
+
+  // 路径缺失时补全对象，不把嵌套字段静默写到根层；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] = {}; onCreate?.(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 = ensurePath(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);
+      }
+    });
+  };
+
+  // 可写的数据视图：未写入的字段直接读原数据（响应式读取，便于精确追踪依赖），写入与删除只进入覆盖层。
+  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, shared, apply: applyResult }: 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();
+      });
+    };
+
+    // 联动函数拿到的是可写的数据视图：读取直接访问表单数据，Vue 只按实际读到的字段收集依赖；
+    // 写入只落在视图自己的覆盖层，不改动表单数据（与 4.x 传副本的语义一致）。
+    const call = (setup: any, item: any, onRead?: () => void) => {
+      const ctx = context();
+      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
+          : 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;
+          // 同步读取由 computed 精确追踪；异步函数在 await 之后才读取的数据无法追踪，
+          // 一旦出现就退回到跟随根数据版本重算。
+          let lateReads = false;
+          const version = shallowRef(0);
+          unwatchs.push(watch(shared.dataVersion, () => {
+            if (lateReads) version.value++;
+          }));
+          // 初次解析与监听共用计算结果，避免异步函数被重复调用。
+          const evaluated = computed(() => {
+            version.value;
+            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)) {
+            // 函数返回联动配置但没写 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, source: () => evaluated.value };
+          }
+        }
+        if (isLinkage(val)) {
+          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;
+        }
+      }
+    };
+
+    // 执行任务：不声明 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, 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++;
+            applyResult(target, key, result);
+          };
+          if (v instanceof Promise) {
+            // 等待期间保留上一次的结果，避免选项、标题等先变空再出现。
+            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;
+            // 函数属性只在计算结果变化时应用；联动配置的 watch: true 跟随根数据版本。
+            unwatchs.push(watch(task.source || shared.dataVersion, () => {
+              runsetup(task);
+            }, { immediate: true }));
+            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,12 +576,12 @@
     },
     // JSON规则
     form: {
-      type: Object,
-      default: () => ({}),
+      type: Array as PropType<FormItem[]>,
+      default: () => [],
     },
     // 表单数据
     data: {
-      type: Object as any,
+      type: Object as PropType<Record<string, any>>,
       default: () => ({}),
     },
     // 栅格系统
@@ -275,197 +604,615 @@
       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[]; hidden: () => string[] }>;
+    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> }>;
+    // 根数据任意变化时递增，供 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)) || {
+    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(),
+    dataVersion: shallowRef(0),
+    serverErrors: reactive(new Map()),
+  };
+  provide(FORM_SHARED, shared);
+
+  const rootData = computed(() => props.root || props.data);
+  // 根表单未传 idx 时用 useId 生成前缀，同页多个表单的同名字段 id 不再冲突；SSR 与客户端一致。
+  const autoIdx = useId().replace(/[^\w-]/g, '-');
+  const baseIdx = computed(() => (props.idx !== '' ? String(props.idx) : props.root ? '' : autoIdx));
+  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(rootData.value);
+    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++;
+    if (!props.root) shared.dataVersion.value++;
+  }, { 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 ? ':' : '';
-    })();
+    // 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 ? ':' : '';
     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) => [baseIdx.value, 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 (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');
+  };
+
+  // 字段缺失时的初始值：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 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' || key === 'array') initializeField(target);
+    },
+  });
+
+  // 初始结构和异步生成的子树都经过相同的数据初始化。
+  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-${baseIdx.value !== '' ? baseIdx.value + '-' : ''}${!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() })),
+    // 当前层被隐藏（clear）的字段路径，供 getData({ visibleOnly }) 剔除
+    hidden: (): string[] => state.form.filter((col: any) => col.field && isCleared(col)).map((col: any) => fieldPath(col)),
+  };
+  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]));
+  };
+  // 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;
+    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 && !shared.serverErrors.has(path)) { col._error = error; col._checked = true; }
+      return error;
+    })();
+    return job.result;
+  };
+  watchEffect(() => {
+    for (const col of state.form) {
+      // 只读取校验输入，不监听内部错误结果；异步结果按执行顺序丢弃过期响应。
+      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(), path);
+      } 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' }));
+  };
+
+  // 路径匹配：'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> => {
+      // 局部校验只让这些字段显示提示，其他字段保持原状
+      if (!paths) 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().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();
+      } 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.serverErrors.clear();
+    shared.validations = new WeakMap();
+    shared.state.validated = false;
+    fieldsOf().forEach(({ col }) => { col._touched = false; col._error = null; col._checked = false; });
+  };
+
+  // 回填外部错误（如服务端校验结果）：{ '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>