@neatui/vue 5.0.0 → 5.1.0

package/MIGRATION-5.0.md

@@ -16,11 +16,9 @@ Vue 最低版本声明统一为 3.5.11，与已有 Pinia 3 的要求一致；同
 
 | 旧配置 | 5.0 写法 |
 | --- | --- |
-| 字段的 `slot: 'custom'` | `model: 'Custom'` 配合 `#Custom`，或使用同名字段插槽 |
-| 字段级 `colon` | 用 `label` 节点树精确输出文字；表单级 `colon` 继续支持 |
 | 只读取 `col` 的自定义插槽 | `col` 继续提供；通过 `bind / update` 接入双向绑定、转换和只读状态 |
 
-例如将 `{ field: 'name', slot: 'custom' }` 改为 `{ field: 'name', model: 'Custom' }`：
+字段级 `slot` 和 `colon` 继续支持。新写法可以用 `model` 配合同名插槽，并通过 `bind` 接入双向绑定：
 
 ```vue
 <FormLoader :form="form" :data="data">
@@ -32,6 +30,12 @@ Vue 最低版本声明统一为 3.5.11，与已有 Pinia 3 的要求一致；同
 
 旧联动签名 `(data, item, route, router)` 继续可用。第三参数的 `path` 始终是网址路径，`formPath` 是表单数据路径；它还提供 `root / data / index / array / route / router`。事件、值转换和插槽里的 `ctx.path` 仍是表单数据路径。
 
+`clear` 行为有变化：4.8.2 隐藏即丢弃原值，现在默认暂存、重新显示时恢复，避免控制字段与被控字段同时赋值（如加载记录）时联动尚未完成就清掉数据。需要旧行为时返回 `{ value, restore: false }`。
+
+字段 id：不传 `idx` 时，4.8.2 生成 `form-field-<字段>`，同页多个表单会冲突；现在自动生成唯一前缀。依赖固定 id 的样式或测试请显式传 `idx`。
+
+联动函数按实际读取的字段追踪，只有读到的字段变化才重新执行（4.8.2 为同层任意字段变化都执行）；函数拿到的 data 可以改写，不影响表单数据。
+
 `model[1].rules` 继续覆盖节点 `rules`，空数组表示关闭该节点校验。`verify: true` 显示统一校验图标；不会再同时触发控件和 FormLoader 两套校验。
 
 ## 从桌面旧组件或中间扩展配置迁移
@@ -48,7 +52,7 @@ Vue 最低版本声明统一为 3.5.11，与已有 Pinia 3 的要求一致；同
 | `transverse` | `label` 属性中的 `style.width: 'auto'` |
 | `before / prefix / suffix / extra / childAttrs` | 使用 `child` 内容节点与 `attrs` 容器 |
 | 节点 `rows` | `attrs: { 'ui-row': '…' }` |
-| `restore` | `clear: () => ({ value: 是否清空, restore: true })` |
+| `restore` | 默认即暂存并在重新显示时恢复；需要丢弃时写 `clear: () => ({ value: 是否清空, restore: false })` |
 | `array.media` | `array.attrs: { 'ui-col': '…' }` |
 | `every-label` 插槽 | `label` 插槽，接收 `col / node / data / text` |
 
@@ -57,10 +61,13 @@ Vue 最低版本声明统一为 3.5.11，与已有 Pinia 3 的要求一致；同
 ## 新增与行为修复
 
 - 标题与内容均可递归组合；数组支持默认值、数量限制、增删排序和行上下文。
+- 新增 `setErrors`（回填服务端错误）、`isDirty / getChanges`（未保存改动）、`setBaseline`（设置重置基线）、`getData({ visibleOnly })`（去掉隐藏字段），`validate({ paths })` 支持局部校验。在同一对象上用 `Object.assign` 加载记录后调用 `setBaseline()`。
 - `validate()` 等待异步联动并检查最新数据；`reset()` 恢复当前数据对象的初始状态；`clearValidate()` 取消未完成校验。
 - 换一条记录时替换 `data` 对象，建立新的重置基线；对同一对象 `Object.assign` 视为编辑。
 - `paths` 缺失时补全对象，已有非对象路径明确报错。
-- 增加 Radio、Gallery（别名 SelectImg）、RichTextInput；TimePicker 使用浏览器原生时间输入并校验范围与步长。
-- Gallery 提供通用图片选择与搜索事件，不包含旧业务素材库的接口、分页和后台管理。RichTextInput 默认支持文本格式、列表、链接和撤销重做，未配置图片上传或表格扩展。
+- 增加 Radio、Gallery（别名 SelectImg），FormLoader 已内置。NeatUI 不提供富文本控件，业务编辑器用同名字段插槽接入 `<MyEditor v-bind="bind" />`。TimePicker 使用浏览器原生时间输入并校验范围与步长。
+- Select 不再清空不在当前选项中的值：只有上级切换使原本有效的值失效（如省市级联）时才清空；加载记录、异步或分页选项尚未包含当前值时保留，并显示原始值。4.x 会直接清空为 null。
+- 类型：`form` 标注为 `FormItem[]`；`FormItem.value` 的 `get / set` 参数可正确推断；新增 `FormSlotScope` 描述字段与控件插槽参数。
+- Gallery 提供通用图片选择与搜索事件，不包含旧业务素材库的接口、分页和后台管理。
 
 示例与完整 API 见仓库的 `web/app/pages/components/formloader.vue`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neatui/vue",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "basic component ui",
   "main": "./src/index.ts",
   "license": "MIT",
@@ -36,13 +36,9 @@
     "@fekit/scrollto": "^3.0.3",
     "@fekit/toast": "^2.7.2",
     "@fekit/utils": "^6.0.0",
-    "@neatui/css": "^5.0.0",
+    "@neatui/css": "^5.1.0",
     "@rollup/plugin-commonjs": "^26.0.1",
     "@rollup/plugin-node-resolve": "^15.2.3",
-    "@tiptap/core": "^3.31.3",
-    "@tiptap/pm": "^3.31.3",
-    "@tiptap/starter-kit": "^3.31.3",
-    "@tiptap/vue-3": "^3.31.3",
     "@vue/compiler-sfc": "^3.4.30",
     "compressorjs": "^1.2.1",
     "echarts": "^5.5.0",

package/src/components/form/Select.vue

@@ -235,6 +235,11 @@
         };
       }
 
+      // 值不在当前选项中（选项未加载、分页或远程搜索）时显示原始值，避免看起来像未选择
+      if (props.modelValue !== null && props.modelValue !== undefined && props.modelValue !== '') {
+        return { label: String(props.modelValue), value: props.modelValue };
+      }
+
       return {};
     }),
     displayLabel: computed((): string => {
@@ -285,35 +290,24 @@
     { immediate: true },
   );
 
-  // 监听并验证modelValue的有效性
+  // 值是否在选项中（含 all 选项）
+  const inOptions = (value: any, options: any[] | undefined, allOption: any) =>
+    (allOption && value === allOption.value) || !!options?.some((option: any) => `${option.value}` === `${value}`);
+
+  // 只在选项变化使原本有效的值失效时清空（如级联切换上级后）。
+  // 值由外部写入（加载记录）、选项异步未到、分页或远程搜索尚未包含当前值时保留，避免丢失数据。
   watch(
     [() => props.modelValue, () => props.options, () => props.all, () => props.other],
-    ([value, options, allOption, otherConfig]) => {
+    ([value, options, allOption, otherConfig], [previousValue, previousOptions]) => {
       // 如果配置了 other，则允许任意值（可能是用户自定义输入）
-      if (otherConfig) {
-        return;
-      }
-
-      // 如果有值但不在有效选项中，清空该值
-      if (value != null && value !== '' && options?.length > 0) {
-        let isValid = false;
-
-        // 检查是否是 all 选项
-        if (allOption && value === allOption.value) {
-          isValid = true;
-        } else {
-          // 检查是否在普通选项中
-          isValid = options.some((option: any) => `${option.value}` === `${value}`);
-        }
-
-        if (!isValid) {
-          nextTick(() => {
-            change(null);
-          });
-        }
+      if (otherConfig || value == null || value === '' || !options?.length) return;
+      const invalidated = value === previousValue && options !== previousOptions && inOptions(value, previousOptions, allOption) && !inOptions(value, options, allOption);
+      if (invalidated) {
+        nextTick(() => {
+          change(null);
+        });
       }
     },
-    { immediate: true },
   );
 
   // 选择

package/src/components/form/index.ts

@@ -1,6 +1,5 @@
 import Radio from './Radio.vue';
 import Gallery from './Gallery.vue';
-import RichTextInput from './RichTextInput.vue';
 import Input from './Input.vue';
 import InputRange from './InputRange.vue';
 import Switch from './Switch.vue';
@@ -36,7 +35,6 @@ export {
   Radio,
   Gallery,
   Gallery as SelectImg,
-  RichTextInput,
   Input,
   InputRange,
   Switch,

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

@@ -144,7 +144,9 @@
           <FormRender v-else :col="col" :mode="mode" :entry="resolveEntry(col)" :interacted="touched" :ctx="context()" :custom="(!editable && hasSlot(`${col.field}-value`)) || !resolveEntry(col)">
             <slot v-if="!editable && hasSlot(`${col.field}-value`)" :name="`${col.field}-value`" v-bind="fieldScope(col)"></slot>
             <template v-else>
-              <slot v-if="col.model[0]" :name="col.model[0]" v-bind="fieldScope(col)"></slot>
+              <!-- 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>
           </FormRender>
@@ -162,12 +164,12 @@
   </div>
 </template>
 <script lang="ts" setup>
-  import { watch, reactive, shallowRef, onMounted, onBeforeUnmount, useAttrs, useSlots, computed, provide, inject, toRaw, nextTick, readonly, watchEffect } 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, deepcopy, isArray, isFunction } from '@fekit/utils';
   import FormRender, { getField, emptyValueOf, clh, isEmpty, labelText, labelAttrs, rulesOf, displayOf, valueBinding, labelNodes, eventsOf, writeValue, FieldMessage } from './FormRender.vue';
-  import type { FormArrayContext, FormContext, FormError, FormValidateResult, LinkageTask, FormRule } from './FormRender.vue';
-
+  import type { PropType, ShallowRef } from 'vue';
+  import type { FormItem, FormArrayContext, FormContext, FormError, FormValidateResult, LinkageTask, FormRule } from './FormRender.vue';
   // 计算Label宽度
   const clw = (label: any = '') => {
     let emWidth = 0;
@@ -185,12 +187,12 @@
     return emWidth;
   };
 
-  // 路径缺失时补全对象，不把嵌套字段静默写到根层。
-  const resolvePath = (data: any, paths: string = '') => {
+  // 路径缺失时补全对象，不把嵌套字段静默写到根层；onCreate 用于记录新建对象的初始值。
+  const ensurePath = (data: any, paths: string = '', onCreate?: (target: any, key: string) => void) => {
     let target = data;
     (paths?.split('.') || []).forEach((key: string) => {
       if (!key) return;
-      if (target[key] == null) { target[key] = {}; recordInitial(target, key); }
+      if (target[key] == null) { target[key] = {}; onCreate?.(target, key); }
       if (!isObject(target[key])) throw new TypeError(`[FormLoader] paths 的 ${key} 必须是对象`);
       target = target[key];
     });
@@ -266,7 +268,7 @@
     const row: any = {};
     list.forEach((item: any = {}) => {
       if (!isObject(item)) return;
-      const target = resolvePath(row, item.paths);
+      const target = ensurePath(row, item.paths);
       if (isArray(item.child) && !item.array) {
         if (item.field) {
           target[item.field] = createRow(item.child, getEmpty);
@@ -314,18 +316,83 @@
     });
   };
 
+  // 可写的数据视图：未写入的字段直接读原数据（响应式读取，便于精确追踪依赖），写入与删除只进入覆盖层。
+  const DELETED = Symbol('deleted');
+  const plainObject = (value: any) => !!value && typeof value === 'object' && !(value instanceof Date);
+  const dataView = (source: any, onRead?: () => void): any => {
+    if (!plainObject(source)) return source;
+    const src = isReactive(source) || isReadonly(source) ? source : reactive(source);
+    const array = isArray(toRaw(src));
+    const overlay = new Map<PropertyKey, any>();
+    const children = new Map<PropertyKey, { raw: any; view: any }>();
+    const read = (key: PropertyKey) => {
+      // Vue 内部标记（__v_raw、__v_isReactive 等）按普通对象处理，视图本身不是响应式对象。
+      if (typeof key === 'string' && key.startsWith('__v_')) return undefined;
+      if (overlay.has(key)) {
+        const value = overlay.get(key);
+        return value === DELETED ? undefined : value;
+      }
+      // 方法取原生函数（不走 Vue 的数组方法包装），调用时通过视图逐项读取，依赖仍然精确。
+      const native = Reflect.get(toRaw(src), key);
+      if (typeof native === 'function') return native;
+      onRead?.();
+      const value = Reflect.get(src, key);
+      if (!plainObject(value) || typeof key === 'symbol') return value;
+      const cached = children.get(key);
+      if (cached && cached.raw === toRaw(value)) return cached.view;
+      const view = dataView(value, onRead);
+      children.set(key, { raw: toRaw(value), view });
+      return view;
+    };
+    const exists = (key: PropertyKey) => (typeof key === 'string' && key.startsWith('__v_') ? false : overlay.has(key) ? overlay.get(key) !== DELETED : (onRead?.(), Reflect.has(src, key)));
+    return new Proxy(array ? [] : {}, {
+      get: (_, key) => read(key),
+      set: (_, key, value) => { overlay.set(key, value); children.delete(key); return true; },
+      deleteProperty: (_, key) => { overlay.set(key, DELETED); children.delete(key); return true; },
+      defineProperty: (_, key, descriptor) => { overlay.set(key, descriptor.value); children.delete(key); return true; },
+      has: (_, key) => exists(key),
+      ownKeys: () => {
+        onRead?.();
+        const keys = new Set<string | symbol>(Reflect.ownKeys(src));
+        overlay.forEach((value, key) => (value === DELETED ? keys.delete(key as string | symbol) : keys.add(key as string | symbol)));
+        if (array) {
+          const length = read('length');
+          keys.forEach((key) => { if (typeof key === 'string' && /^\d+$/.test(key) && Number(key) >= length) keys.delete(key); });
+        }
+        return [...keys];
+      },
+      getOwnPropertyDescriptor: (_, key) => {
+        if (!exists(key)) return undefined;
+        if (array && key === 'length') return { value: read(key), writable: true, enumerable: false, configurable: false };
+        return { value: read(key), writable: true, enumerable: true, configurable: true };
+      },
+      getPrototypeOf: () => Reflect.getPrototypeOf(toRaw(src)),
+    });
+  };
+
+  // 动态属性联动：函数或 { value, setup, watch }；按实际读取的字段追踪依赖，丢弃过期的异步结果
+  // 联动引擎需要的共享状态：数据版本（watch: true 与 await 后读取的回退）、结构版本、未完成的异步任务
+  interface LinkageShared {
+    dataVersion: ShallowRef<number>;
+    revision: number;
+    pending: Set<Promise<any>>;
+  }
+
   interface LinkageOptions {
     // 按下标取当前渲染的字段
     target: (idx: number) => any;
-    // 联动上下文：根数据、当前层数据、行下标、路由等
+    // 联动上下文：根数据、当前层数据、行下标、路由等；属性按需读取，未用到的不产生依赖
     context: () => FormContext;
+    shared: LinkageShared;
+    // 把联动结果写回字段（规范化 model / array、初始化子结构由表单负责）
+    apply: (target: any, key: string, result: any) => void;
   }
 
   // 带 setup 或 watch 的对象才是联动配置，attrs 等普通对象原样保留
   const isLinkage = (val: any) => isObject(val) && (isFunction(val.setup) || isArray(val.watch) || val.watch === true);
 
   // 动态属性：函数或 { value, setup, watch }，监听字段变化时重新计算，支持 Promise
-  const useLinkage = ({ target: getTarget, context }: LinkageOptions) => {
+  const useLinkage = ({ target: getTarget, context, shared, apply: applyResult }: LinkageOptions) => {
     // 结构变化时重建字段监听；普通字段变化只触发对应的联动任务
     const unwatchs: Array<() => void> = [];
     const pendingRuns = new Map<LinkageTask, () => void>();
@@ -339,14 +406,11 @@
       });
     };
 
-    // 传给联动函数的根数据是只读的，联动只改字段配置，不改数据
-    const call = (setup: any, item: any, used?: () => void) => {
+    // 联动函数拿到的是可写的数据视图：读取直接访问表单数据，Vue 只按实际读到的字段收集依赖；
+    // 写入只落在视图自己的覆盖层，不改动表单数据（与 4.x 传副本的语义一致）。
+    const call = (setup: any, item: any, onRead?: () => void) => {
       const ctx = context();
-      const track = (data: any) => new Proxy(readonly(data), {
-        get(target, key, receiver) { used?.(); return Reflect.get(target, key, receiver); },
-        ownKeys(target) { used?.(); return Reflect.ownKeys(target); },
-        has(target, key) { used?.(); return Reflect.has(target, key); },
-      });
+      const track = (data: any) => dataView(data, onRead);
       // 统一回调协议，不通过参数个数猜测用途。path 保持已发布版路由含义。
       const scope = new Proxy(ctx, {
         get: (target, key) => key === 'path' ? ctx.route?.path : key === 'formPath' ? ctx.path
@@ -370,15 +434,25 @@
         // 处理函数
         if (isFunction(val)) {
           const fn = val;
-          let usesData = false;
+          // 同步读取由 computed 精确追踪；异步函数在 await 之后才读取的数据无法追踪，
+          // 一旦出现就退回到跟随根数据版本重算。
+          let lateReads = false;
           const version = shallowRef(0);
-          unwatchs.push(watch(() => context().root, () => {
-            if (usesData) version.value++;
-          }, { deep: true, flush: 'sync' }));
+          unwatchs.push(watch(shared.dataVersion, () => {
+            if (lateReads) version.value++;
+          }));
           // 初次解析与监听共用计算结果，避免异步函数被重复调用。
           const evaluated = computed(() => {
             version.value;
-            return call(fn, reactive(item), () => { usesData = true; });
+            let evaluating = true;
+            let settled = false;
+            const result = call(fn, reactive(item), () => {
+              if (!evaluating && !settled) lateReads = true;
+            });
+            evaluating = false;
+            if (result instanceof Promise) result.then(() => (settled = true), () => (settled = true));
+            else settled = true;
+            return result;
           });
           val = evaluated.value;
           if (isLinkage(val)) {
@@ -396,12 +470,12 @@
           } else {
             hasInitialResult = true;
             initialResult = val;
-            val = { value: val instanceof Promise ? undefined : val, setup: () => evaluated.value, watch: true };
+            val = { value: val instanceof Promise ? undefined : val, setup: () => evaluated.value, watch: true, source: () => evaluated.value };
           }
         }
         if (isLinkage(val)) {
-          const { value = null, setup = () => {}, watch: _watch = [] } = val || {};
-          tasks.push({ idx, key, value, setup, watch: _watch, hasInitialResult, initialResult });
+          const { value = null, setup = () => {}, watch: _watch = [], source } = val || {};
+          tasks.push({ idx, key, value, setup, watch: _watch, hasInitialResult, initialResult, source });
           item[key] = value;
         } else {
           item[key] = val;
@@ -415,7 +489,7 @@
       const taskRuns = new Map<LinkageTask, number>();
       const runsetup = (task: LinkageTask) => {
         if (current !== generation) return;
-        const { idx, key, value, setup } = task;
+        const { idx, key, setup } = task;
         const target = getTarget(idx);
         if (target && isFunction(setup)) {
           pendingRuns.get(task)?.();
@@ -426,12 +500,10 @@
           const isCurrent = () => current === generation && getTarget(idx) === target && taskRuns.get(task) === runId;
           const apply = (result: any) => {
             shared.revision++;
-            target[key] = key === 'model' ? normalizeModel(result) : result;
-            if (key === 'array') target._array = result ? normalizeArray(result) : null;
-            if (key === 'child' || key === 'array') initializeField(target);
+            applyResult(target, key, result);
           };
           if (v instanceof Promise) {
-            nextTick(() => { if (isCurrent()) apply(value); });
+            // 等待期间保留上一次的结果，避免选项、标题等先变空再出现。
             let release!: () => void;
             const pending = new Promise<void>(resolve => { release = resolve; });
             const finish = () => {
@@ -466,10 +538,10 @@
           const { watch: keys } = task;
           if (keys === true) {
             task.hasInitialResult = false;
-            unwatchs.push(watchEffect(() => {
-              deepcopy(context().root);
+            // 函数属性只在计算结果变化时应用；联动配置的 watch: true 跟随根数据版本。
+            unwatchs.push(watch(task.source || shared.dataVersion, () => {
               runsetup(task);
-            }));
+            }, { immediate: true }));
             return;
           }
           unwatchs.push(
@@ -487,6 +559,7 @@
     return { stop, resolve, start };
   };
 
+
   const route = useRoute();
   const router = useRouter();
   const attrs = useAttrs();
@@ -503,12 +576,12 @@
     },
     // JSON规则
     form: {
-      type: Array,
+      type: Array as PropType<FormItem[]>,
       default: () => [],
     },
     // 表单数据
     data: {
-      type: Object as any,
+      type: Object as PropType<Record<string, any>>,
       default: () => ({}),
     },
     // 栅格系统
@@ -575,7 +648,7 @@
   interface Shared {
     state: { lw: number; validated: boolean };
     cache: ClearCache;
-    instances: Set<{ collect: () => any[] }>;
+    instances: Set<{ collect: () => any[]; hidden: () => string[] }>;
     snapshot: any;
     initialObjects: WeakMap<object, any>;
     pending: Set<Promise<any>>;
@@ -583,6 +656,10 @@
     validationEpoch: number;
     cancelChecks: Set<() => void>;
     validations: WeakMap<object, { input: any; epoch: number; pending: boolean; result: Promise<any> }>;
+    // 根数据任意变化时递增，供 watch: true 的联动共用
+    dataVersion: ShallowRef<number>;
+    // 外部回填的错误（如服务端校验），按字段路径保存；字段值变化后自动失效
+    serverErrors: Map<string, { msg: string; type: string; input: any }>;
   }
   const FORM_SHARED = Symbol.for('neatui:form-loader');
   const shared: Shared = (props.root && inject<Shared | null>(FORM_SHARED, null)) || {
@@ -596,10 +673,15 @@
     validationEpoch: 0,
     cancelChecks: new Set(),
     validations: new WeakMap(),
+    dataVersion: shallowRef(0),
+    serverErrors: reactive(new Map()),
   };
   provide(FORM_SHARED, shared);
 
   const rootData = computed(() => props.root || props.data);
+  // 根表单未传 idx 时用 useId 生成前缀，同页多个表单的同名字段 id 不再冲突；SSR 与客户端一致。
+  const autoIdx = useId().replace(/[^\w-]/g, '-');
+  const baseIdx = computed(() => (props.idx !== '' ? String(props.idx) : props.root ? '' : autoIdx));
   const cancelValidation = () => {
     shared.validationEpoch++;
     shared.cancelChecks.forEach(cancel => cancel());
@@ -616,7 +698,7 @@
   };
   const captureInitial = () => {
     shared.initialObjects = new WeakMap();
-    shared.snapshot = cloneInitial(props.data);
+    shared.snapshot = cloneInitial(rootData.value);
     shared.cache = new WeakMap();
     cancelValidation();
   };
@@ -627,6 +709,7 @@
   if (!props.root) captureInitial();
   watch(() => props.data, () => {
     shared.revision++;
+    if (!props.root) shared.dataVersion.value++;
   }, { deep: true, flush: 'sync' });
   const editable = computed(() => props.mode !== 'view');
   // 调用过 validate 后所有字段展示校验状态
@@ -666,6 +749,10 @@
     const label = labelText(col.label);
     if (!label) return '';
     if (/[:：]\s*$/.test(label)) return label;
+    // 4.x 兼容：字段级 colon 优先，false 不显示，string 自定义字符，true 为 ':'
+    if (col.colon === false) return label;
+    if (isString(col.colon)) return `${label}${col.colon}`;
+    if (col.colon === true) return `${label}:`;
     // 自定义节点树和标签属性可以直接决定呈现；默认文本标签跟随表单冒号。
     if ((isGroup(col) || col._array || col.array) && isVertical(col)) return label;
     const suffix = isString(props.colon) ? props.colon : props.colon ? ':' : '';
@@ -693,7 +780,7 @@
 
   // 分组、数组的路径和 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 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] : []);
 
@@ -703,6 +790,7 @@
   // 控件：已注册的 model；没写 model 且没有对应插槽时默认 Input
   const resolveEntry = (col: any = {}) => {
     const model = col.model?.[0];
+    if (col.slot && !getField(model)) return undefined;
     if (model) return getField(model);
     if (col.field && hasSlot(col.field)) return undefined;
     return getField(col.field ? 'Input' : 'Text');
@@ -776,7 +864,30 @@
     form: [],
   });
 
-  const linkage = useLinkage({ target: (idx) => state.form[idx], context });
+  // 路径缺失时补全对象，并把新建的对象记入重置基线
+  const resolvePath = (data: any, paths: string = '') => ensurePath(data, paths, recordInitial);
+
+  // 按需读取的联动上下文：函数没用到的属性（如数组行上下文）变化时不触发重算。
+  const lazyContext = (): FormContext => ({
+    get root() { return rootData.value; },
+    get data() { return props.data; },
+    get index() { return props.index; },
+    get array() { return props.arrayContext; },
+    get path() { return props.path; },
+    get mode() { return props.mode; },
+    route,
+    router,
+  });
+  const linkage = useLinkage({
+    target: (idx) => state.form[idx],
+    context: lazyContext,
+    shared,
+    apply: (target, key, result) => {
+      target[key] = key === 'model' ? normalizeModel(result) : result;
+      if (key === 'array') target._array = result ? normalizeArray(result) : null;
+      if (key === 'child' || key === 'array') initializeField(target);
+    },
+  });
 
   // 初始结构和异步生成的子树都经过相同的数据初始化。
   const initializeField = (item: any) => {
@@ -830,7 +941,7 @@
       }
 
       // 添加ID
-      item._fid = `form-${props.idx !== '' ? props.idx + '-' : ''}${!item.field && isGroup(item) ? `group-${idx}` : `field-${item.field || `node-${idx}`}`}`;
+      item._fid = `form-${baseIdx.value !== '' ? baseIdx.value + '-' : ''}${!item.field && isGroup(item) ? `group-${idx}` : `field-${item.field || `node-${idx}`}`}`;
 
       // 数据路径处理
       item._data = resolvePath(props.data, item.paths);
@@ -895,6 +1006,8 @@
       state.form
         .filter((col: any) => !isCleared(col) && col.field && !isGroup(col))
         .map((col: any) => ({ col, path: fieldPath(col), ctx: context() })),
+    // 当前层被隐藏（clear）的字段路径，供 getData({ visibleOnly }) 剔除
+    hidden: (): string[] => state.form.filter((col: any) => col.field && isCleared(col)).map((col: any) => fieldPath(col)),
   };
   onMounted(() => {
     shared.instances.add(instance);
@@ -917,7 +1030,10 @@
     const keys = Object.keys(a);
     return keys.length === Object.keys(b).length && keys.every(key => Object.prototype.hasOwnProperty.call(b, key) && sameInput(a[key], b[key]));
   };
-  const validateField = (col: any, ctx: FormContext, force = false): Promise<any> => {
+  // path 由收集字段的那一层计算（validate 在根表单调用时，嵌套字段的路径不能用根表单拼）
+  const validateField = (col: any, ctx: FormContext, path: string, force = false): Promise<any> => {
+    const server = shared.serverErrors.get(path);
+    if (server) return Promise.resolve({ msg: server.msg, type: server.type });
     const input = deepcopy([displayOf(col, ctx), rulesOf(col), col.model]);
     const previous = shared.validations.get(col);
     if (previous && previous.epoch === shared.validationEpoch && (!force || previous.pending) && sameInput(previous.input, input)) return previous.result;
@@ -930,7 +1046,7 @@
         error = message ? { msg: message, type: 'risk' } : await checkRules(input[0], input[1]);
       } catch { error = { msg: '校验失败，请重试', type: 'risk' }; }
       job.pending = false;
-      if (shared.validations.get(col) === job && shared.validationEpoch === job.epoch) { col._error = error; col._checked = true; }
+      if (shared.validations.get(col) === job && shared.validationEpoch === job.epoch && !shared.serverErrors.has(path)) { col._error = error; col._checked = true; }
       return error;
     })();
     return job.result;
@@ -938,11 +1054,22 @@
   watchEffect(() => {
     for (const col of state.form) {
       // 只读取校验输入，不监听内部错误结果；异步结果按执行顺序丢弃过期响应。
-      deepcopy(displayOf(col, context()));
+      const value = deepcopy(displayOf(col, context()));
       deepcopy(rulesOf(col));
       deepcopy(col.model);
+      // 回填的错误在字段值变化前一直显示，值一变就交回正常校验
+      const path = col.field ? fieldPath(col) : '';
+      const server = path ? shared.serverErrors.get(path) : undefined;
+      if (server && !isCleared(col)) {
+        if (sameInput(server.input, value)) {
+          col._error = { msg: server.msg, type: server.type };
+          col._checked = true;
+          continue;
+        }
+        shared.serverErrors.delete(path);
+      }
       if (col.field && !isGroup(col) && !isCleared(col) && (touched.value || col._touched)) {
-        void validateField(col, context());
+        void validateField(col, context(), path);
       } else {
         shared.validations.delete(col);
         col._error = null;
@@ -970,15 +1097,19 @@
     nextTick(() => el.scrollIntoView({ behavior: 'smooth', block: 'center' }));
   };
 
-  // 校验所有已显示的字段（包含分组和数组），warn 类型只作为提醒，不影响 valid
-  const validate = async ({ scroll = false }: { scroll?: boolean } = {}): Promise<FormValidateResult> => {
+  // 路径匹配：'contact' 包含 'contact.phone'，'members.0' 包含该行全部字段
+  const withinPaths = (path: string, paths?: string[]) => !paths || paths.some((p) => path === p || path.startsWith(`${p}.`));
+
+  // 校验已显示的字段（包含分组和数组），warn 类型只作为提醒，不影响 valid；paths 限定只校验这些路径
+  const validate = async ({ scroll = false, paths }: { scroll?: boolean; paths?: string[] } = {}): Promise<FormValidateResult> => {
     const epoch = shared.validationEpoch;
     const cancelledResult = (): FormValidateResult => ({ valid: false, errors: [{ field: '', path: '', label: '', msg: '表单已重置或切换，请重新校验', type: 'risk' }], warnings: [] });
     let cancel!: () => void;
     const cancelled = new Promise<FormValidateResult>(resolve => { cancel = () => resolve(cancelledResult()); });
     shared.cancelChecks.add(cancel);
     const run = async (): Promise<FormValidateResult> => {
-      shared.state.validated = true;
+      // 局部校验只让这些字段显示提示，其他字段保持原状
+      if (!paths) shared.state.validated = true;
       let results: any[];
       let revision: number;
       do {
@@ -990,8 +1121,9 @@
           if (shared.pending.size) await Promise.all([...shared.pending]);
         } while (revision !== shared.revision || shared.pending.size);
         revision = shared.revision;
-        results = await Promise.all(fieldsOf().map(async ({ col, path, ctx }) => {
-          const res = await validateField(col, ctx, true);
+        results = await Promise.all(fieldsOf().filter(({ path }) => withinPaths(path, paths)).map(async ({ col, path, ctx }) => {
+          if (paths) col._touched = true;
+          const res = await validateField(col, ctx, path, true);
           return res ? { field: col.field, path, label: labelText(col.label), msg: res.msg, type: res.type, fid: col._fid } : null;
         }));
         if (epoch !== shared.validationEpoch) return cancelledResult();
@@ -1021,10 +1153,66 @@
 
   const clearValidate = () => {
     cancelValidation();
+    shared.serverErrors.clear();
     shared.validations = new WeakMap();
     shared.state.validated = false;
     fieldsOf().forEach(({ col }) => { col._touched = false; col._error = null; col._checked = false; });
   };
 
-  defineExpose({ validate, reset, clearValidate, scrollToField });
+  // 回填外部错误（如服务端校验结果）：{ 'contact.phone': '号码已被占用' } 或 [{ path, msg, type }]。
+  // 字段值变化后错误自动消失；返回没有匹配到已显示字段的路径，便于改用全局提示。
+  const setErrors = (errors: Record<string, string | { msg: string; type?: string }> | Array<{ path: string; msg: string; type?: string }>, { scroll = false }: { scroll?: boolean } = {}): string[] => {
+    const list: Array<{ path: string; msg: string; type?: string }> = Array.isArray(errors)
+      ? errors
+      : Object.entries(errors || {}).map(([path, error]) => (isString(error) ? { path, msg: error } : { path, ...(error as any) }));
+    const fields = fieldsOf();
+    const missing: string[] = [];
+    list.forEach(({ path, msg, type = 'risk' }) => {
+      const found = fields.find((item) => item.path === path);
+      if (!found) return missing.push(path);
+      shared.serverErrors.set(path, { msg, type, input: deepcopy(displayOf(found.col, found.ctx)) });
+    });
+    const first = list.find((item) => !missing.includes(item.path));
+    if (scroll && first) scrollToField(first.path);
+    return missing;
+  };
+
+  // 与初始值（挂载时的数据及自动补全的默认值，或 setBaseline 之后的数据）比较，返回变化的字段路径
+  const getChanges = (): string[] => {
+    const changes: string[] = [];
+    const diff = (current: any, initial: any, path: string) => {
+      if (sameInput(current, initial)) return;
+      const bothArrays = isArray(current) && isArray(initial);
+      const bothObjects = isPlain(current) && isPlain(initial);
+      if ((bothArrays && current.length === initial.length) || bothObjects) {
+        const keys = new Set([...Object.keys(current), ...Object.keys(initial)]);
+        keys.forEach((key) => diff(current[key], initial[key], path ? `${path}.${key}` : key));
+      } else changes.push(path);
+    };
+    diff(toRaw(rootData.value), shared.snapshot, '');
+    return changes;
+  };
+  const isDirty = (path?: string) => getChanges().some((item) => !path || withinPaths(item, [path]) || withinPaths(path, [item]));
+
+  // 把当前数据设为新的初始值：同一对象上加载记录（Object.assign）或保存成功后调用，reset() 与 isDirty() 以它为准
+  const setBaseline = () => captureInitial();
+
+  // 取数据副本；visibleOnly 时去掉被 clear 隐藏的字段
+  const getData = ({ visibleOnly = false }: { visibleOnly?: boolean } = {}) => {
+    const data = deepcopy(toRaw(rootData.value));
+    if (visibleOnly) {
+      [...shared.instances].flatMap((item) => item.hidden()).forEach((path) => {
+        const keys = path.split('.');
+        const last = keys.pop() as string;
+        const parent = keys.reduce((target: any, key) => (target == null ? undefined : target[key]), data);
+        if (parent && typeof parent === 'object') delete parent[last];
+      });
+    }
+    return data;
+  };
+
+  // 插槽名由字段名、model 名动态生成，参数随插槽种类不同；字段与控件插槽的参数见 FormSlotScope
+  defineSlots<Record<string, (scope: any) => any>>();
+
+  defineExpose({ validate, reset, clearValidate, scrollToField, setErrors, getChanges, isDirty, setBaseline, getData });
 </script>

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

@@ -1,24 +1,17 @@
 <template>
-  <div class="flex-block pr" @focusout="col._touched = true" :aria-describedby="col._error && mode !== 'view' ? `${col._fid}-error` : undefined">
+  <div ref="root" class="flex-block pr" @focusout="col._touched = true">
     <slot v-if="custom" />
-    <button v-else-if="col.model[0] === 'Button'" type="button" ui-btn="@a s" v-bind="col.model[1]" v-on="events"><FieldExtra :value="displayOf(col, ctx)" /></button>
-    <div v-else-if="col.model[0] === 'Html'" v-bind="col.model[1]" v-on="events" v-html="displayOf(col, ctx)"></div>
-    <div v-else-if="col.model[0] === 'Text'" v-bind="col.model[1]" v-on="events"><FieldExtra :value="displayOf(col, ctx)" /></div>
+    <button v-else-if="col.model[0] === 'Button'" type="button" ui-btn="@a s" v-bind="contentAttrs" v-on="events"><FieldExtra :value="displayOf(col, ctx)" :trusted="trusted" /></button>
+    <div v-else-if="col.model[0] === 'Html' && trusted" v-bind="contentAttrs" v-on="events" v-html="displayOf(col, ctx)"></div>
+    <div v-else-if="col.model[0] === 'Html' || col.model[0] === 'Text'" v-bind="contentAttrs" v-on="events"><FieldExtra :value="displayOf(col, ctx)" :trusted="trusted" /></div>
     <div v-else-if="(mode === 'view' && !entry?.view) || entry?.component === FieldView" class="flex-block o-ls" :class="clh(col.model?.[1] || {})" v-on="events">{{ text }}</div>
     <component
       v-else-if="entry"
       :is="entry.component"
       :modelValue="displayOf(col, ctx)"
-      :interacted="interacted"
-      :options="entry.options ? col.enums : undefined"
       :class="entry.class"
-      v-bind="col.model[1] || {}"
-      :rules="[]"
-      :verify="false"
-      :co="col._error?.type || col.model[1]?.co"
-      :readonly="mode === 'view' ? true : col.model[1]?.readonly"
-      :disabled="mode === 'view' ? true : col.model[1]?.disabled"
-      v-on="events"
+      v-bind="controlProps"
+      v-on="controlEvents"
       @update:modelValue="update"
     />
     <FieldMessage :col="col" :mode="mode" />
@@ -26,7 +19,7 @@
 </template>
 <script lang="ts">
   import { defineComponent, h, isVNode, markRaw } from 'vue';
-  import type { Component } from 'vue';
+  import type { Component, VNode } from 'vue';
   import { isArray, isObject, isString, isFunction } from '@fekit/utils';
 
   /** 最近一层数组的操作上下文；行引用在排序后仍指向原行。 */
@@ -91,6 +84,9 @@
     set?: (value: any, ctx: FormContext) => any;
   }
 
+  /** 内容节点可以渲染的值 */
+  export type FormContent = string | number | boolean | null | VNode | { text?: string; html?: boolean; attrs?: Record<string, any> } | FormContent[];
+
   /** 数组配置 */
   export interface FormArray {
     // 每一行的字段，兼容旧版 lists
@@ -116,7 +112,8 @@
   export interface FormItem {
     label?: Dynamic<string | [string, Record<string, any>] | FormItem[]>;
     field?: string;
-    value?: any | FormValue;
+    // 固定内容、{ text, html, attrs } 内容对象、VNode、数组；绑定字段时用 { default, get, set }；也可以是函数或联动配置
+    value?: FormValue | FormContent | FormSetup | FormLinkage<FormContent>;
     child?: Dynamic<FormItem[]>;
     attrs?: Dynamic<Record<string, any>>;
     clear?: Dynamic<boolean | { value: boolean; restore?: boolean }>;
@@ -129,6 +126,25 @@
     media?: Dynamic<string>;
     vertical?: Dynamic<boolean>;
     paths?: string;
+    // 4.x 兼容：自定义插槽名；字段级冒号（false 不显示，string 自定义字符）
+    slot?: string;
+    colon?: boolean | string;
+  }
+
+  /** 字段与控件插槽（${field}、model 名、${field}-value、${field}-row）的参数 */
+  export interface FormSlotScope {
+    col: any;
+    node: any;
+    // 当前层数据
+    data: any;
+    mode: string;
+    // 原始值（未经 value.get）
+    value: any;
+    ctx: FormContext;
+    // 写回：经过 value.set，查看模式下不写入
+    update: (value: any) => void;
+    // Vue 控件直接 v-bind：modelValue 已经过 value.get
+    bind: { modelValue: any; 'onUpdate:modelValue': (value: any) => void; disabled: boolean };
   }
 
   /** 校验结果 */
@@ -147,10 +163,20 @@
 
   /** FormLoader 对外方法 */
   export interface FormLoaderExpose {
-    validate: (options?: { scroll?: boolean }) => Promise<FormValidateResult>;
+    /** 校验已显示字段；paths 只校验这些路径（含子路径） */
+    validate: (options?: { scroll?: boolean; paths?: string[] }) => Promise<FormValidateResult>;
     reset: () => void;
     clearValidate: () => void;
     scrollToField: (path: string) => void;
+    /** 回填外部错误，返回没有匹配到字段的路径 */
+    setErrors: (errors: Record<string, string | { msg: string; type?: string }> | Array<{ path: string; msg: string; type?: string }>, options?: { scroll?: boolean }) => string[];
+    /** 与初始值相比发生变化的字段路径 */
+    getChanges: () => string[];
+    isDirty: (path?: string) => boolean;
+    /** 把当前数据设为新的初始值 */
+    setBaseline: () => void;
+    /** 数据副本；visibleOnly 去掉被 clear 隐藏的字段 */
+    getData: (options?: { visibleOnly?: boolean }) => any;
   }
 
   /** 动态属性任务 */
@@ -163,12 +189,14 @@
     watch: string[] | true;
     hasInitialResult: boolean;
     initialResult: any;
+    // 函数属性的计算结果；变化时重新应用，替代整表深拷贝监听
+    source?: () => any;
   }
 
   /** 控件注册信息 */
   export interface FieldEntry {
     component: Component;
-    // 查看模式使用控件自身的 readonly 展示（如图片、富文本）。
+    // 查看模式使用控件自身的 readonly 展示（如图片库）。
     view?: boolean;
     validate?: (value: any, props: any) => string | null | Promise<string | null>;
     // 是否把 enums 作为 options 传入
@@ -225,14 +253,14 @@
     return handlers;
   };
 
-  // 内容渲染：字符串按文本渲染；VNode 原样渲染；{ text, html, attrs } 只有 html 为 true 时才按 HTML 渲染
-  const render = (value: any): any => {
+  // 内容渲染：字符串按文本渲染；VNode 原样渲染；{ text, html, attrs } 只有 html 为 true 且内容来自配置时才按 HTML 渲染
+  const render = (value: any, trusted: boolean): any => {
     if (value === null || value === undefined || value === '') return null;
     if (isVNode(value)) return value;
-    if (isArray(value)) return value.map(render);
+    if (isArray(value)) return value.map((item: any) => render(item, trusted));
     if (isObject(value)) {
       const { text = '', html = false, attrs = {} } = value;
-      return html ? h('span', { ...attrs, innerHTML: text }) : h('span', attrs, text);
+      return html && trusted ? h('span', { ...attrs, innerHTML: text }) : h('span', trusted ? attrs : {}, String(text));
     }
     return h('span', String(value));
   };
@@ -252,16 +280,16 @@
     name: 'FieldExtra',
     props: {
       value: { type: null, default: null },
+      trusted: { type: Boolean, default: false },
     },
     setup(props) {
-      return () => render(props.value);
+      return () => render(props.value, props.trusted);
     },
   });
 
   import {
     Radio,
     Gallery,
-    RichTextInput,
     Input,
     InputRange,
     Switch,
@@ -295,7 +323,7 @@
   const multiple = { emptyValue: () => [] };
 
   // View 由当前渲染器直接展示；注册表保留标记以兼容自定义注册。
-  const FieldView = defineComponent({ name: 'FormView', render: () => null });
+  export const FieldView = defineComponent({ name: 'FormView', render: () => null });
 
   // 占位：只占栅格，不渲染内容
   const Blank = defineComponent({ name: 'FormBlank', render: () => null });
@@ -304,7 +332,6 @@
   const registry: Record<string, FieldEntry> = {
     Radio: option(Radio),
     Gallery: option(Gallery, { view: true, emptyValue: (props: any) => props?.multiple ? [] : '' }),
-    RichTextInput: { component: markRaw(RichTextInput), view: true, class: 'w-full' },
     Input: { component: markRaw(Input), class: 'w-full' },
     InputRange: { component: markRaw(InputRange), class: 'w-full', emptyValue: () => [] },
     Select: option(Select),
@@ -344,9 +371,9 @@
 
   // 仅补名称别名；显式注册同名控件时仍优先使用注册项。
   const fieldAliases: Record<string, string> = { TextArea: 'Textarea', view: 'View', SelectImg: 'Gallery' };
-  export const getField = (model: string = ''): FieldEntry | undefined => registry[model] || registry[fieldAliases[model]];
+  export const getField = (model: string = ''): FieldEntry | undefined => registry[model] || registry[fieldAliases[model] ?? ''];
 
-  // 注册自定义控件，比如业务里的图片库、富文本；注册后 model 直接写名字即可
+  // 注册自定义控件，比如业务里的图片库；注册后 model 直接写名字即可。富文本等重控件建议用插槽接入，不进注册表
   export const registerField = (name: string, entry: FieldEntry) => {
     registry[name] = { ...entry, component: markRaw(entry.component as any) };
   };
@@ -358,10 +385,10 @@
     if (typeof value === 'function') return value(model[1]);
     return value === undefined ? '' : value;
   };
-
 </script>
 <script lang="ts" setup>
-  import { computed } from 'vue';
+  // 单个字段的渲染：内置内容节点、注册控件或插槽，以及统一的错误提示
+  import { computed, ref, watch, nextTick, onMounted, onUpdated } from 'vue';
   const props = defineProps<{
     col: any;
     entry?: FieldEntry;
@@ -404,6 +431,73 @@
     }
     return String(one(value));
   });
-  const update = (value: any) => { props.col._touched = true; writeValue(props.col, value, props.ctx); };
+  // 配置里写死、由配置函数生成或经 value.get 转换的内容视为可信；直接显示 field 数据时按文本渲染，避免 XSS。
+  const trusted = computed(() => {
+    const { value } = props.col;
+    return value !== undefined && (!valueBinding(value) || isFunction(value.get));
+  });
   const events = computed(() => eventsOf(props.col, props.ctx));
+  // 先写回数据再通知配置里的 update:modelValue，与插槽的 update 顺序一致。
+  const controlEvents = computed(() => {
+    const { 'update:modelValue': _, ...rest } = events.value;
+    return rest;
+  });
+  const update = (value: any) => {
+    props.col._touched = true;
+    writeValue(props.col, value, props.ctx);
+    events.value['update:modelValue']?.(value);
+  };
+
+  // FormLoader 自己的参数只传给声明了它们的控件，避免落到 Radio、Gallery 等控件的 DOM 上。
+  const formOnly = ['interacted', 'rules', 'verify', 'co', 'format', 'empty'];
+  const controlProps = computed(() => {
+    const { col, entry, mode } = props;
+    const options = col.model?.[1] || {};
+    const merged: Record<string, any> = {
+      interacted: props.interacted,
+      options: entry?.options ? col.enums : undefined,
+      ...options,
+      rules: [],
+      verify: false,
+      co: col._error?.type || options.co,
+      readonly: mode === 'view' ? true : options.readonly,
+      disabled: mode === 'view' ? true : options.disabled,
+    };
+    const declared: any = (entry?.component as any)?.props;
+    // 没有声明 props 的自定义注册控件可能通过 $attrs 读取这些参数，保持透传。
+    const declares = (key: string) => !declared || (isArray(declared) ? declared.includes(key) : Object.prototype.hasOwnProperty.call(declared, key));
+    formOnly.forEach((key) => { if (!declares(key)) delete merged[key]; });
+    if (merged.options === undefined) delete merged.options;
+    return merged;
+  });
+  // 按钮和内容节点只接收普通属性
+  const contentAttrs = computed(() => {
+    const attrs = { ...(props.col.model?.[1] || {}) };
+    formOnly.forEach((key) => delete attrs[key]);
+    return attrs;
+  });
+
+  // 错误提示关联到实际输入元素，读屏软件才能读出；只移除自己加上的属性。
+  const root = ref<HTMLElement>();
+  const inputs = 'input:not([type=hidden]):not([type=search]), textarea, select, [contenteditable="true"], [role="radiogroup"]';
+  const describe = () => {
+    const el = root.value;
+    // 非 DOM 渲染环境（SSR、自定义渲染器）没有查询接口
+    if (!el || typeof el.querySelectorAll !== 'function') return;
+    const errorId = props.col._error && props.mode !== 'view' ? `${props.col._fid}-error` : '';
+    el.querySelectorAll<HTMLElement>(inputs).forEach((node) => {
+      if (errorId) {
+        node.setAttribute('aria-invalid', 'true');
+        node.setAttribute('aria-describedby', errorId);
+        node.dataset.formAria = '';
+      } else if (node.dataset.formAria !== undefined) {
+        node.removeAttribute('aria-invalid');
+        node.removeAttribute('aria-describedby');
+        delete node.dataset.formAria;
+      }
+    });
+  };
+  onMounted(describe);
+  onUpdated(describe);
+  watch(() => [props.col._error, props.mode], () => nextTick(describe));
 </script>

package/src/components/loader/index.ts

@@ -1,6 +1,6 @@
 import FormLoader from './FormLoader/FormLoader.vue';
 export { registerField } from './FormLoader/FormRender.vue';
-export type { FormValue, FormItem, FormArray, FormRule, FormContext, FormArrayContext, FormLinkage, FormError, FormValidateResult, FormLoaderExpose, FieldEntry } from './FormLoader/FormRender.vue';
+export type { FormValue, FormItem, FormArray, FormRule, FormContext, FormArrayContext, FormLinkage, FormError, FormValidateResult, FormLoaderExpose, FormSlotScope, FieldEntry } from './FormLoader/FormRender.vue';
 import LimitLoader from './LimitLoader';
 export * from './TableLoader/index';
 import TableLoader from './TableLoader/TableLoader.vue';

package/src/components/form/RichTextInput.vue

@@ -1,99 +0,0 @@
-<template>
-  <div class="neat-rich-text b-solid b-xs b-line r-sm" :aria-busy="!editor">
-    <template v-if="editor">
-      <div v-if="!readonly" role="toolbar" aria-label="文本格式" class="n-sm" ui-flex="row lm">
-        <button v-for="tool in tools" :key="tool.label" type="button" ui-btn="@a s" :disabled="disabled"
-          :aria-pressed="tool.active ? editor.isActive(tool.active) : undefined" @mousedown.prevent @click="tool.run()">{{ tool.label }}</button>
-        <button type="button" ui-btn="@a s" :disabled="disabled" @mousedown.prevent @click="openLink">链接</button>
-        <button type="button" ui-btn="@a s" :disabled="disabled || !editor.can().undo()" @mousedown.prevent @click="editor.chain().focus().undo().run()">撤销</button>
-        <button type="button" ui-btn="@a s" :disabled="disabled || !editor.can().redo()" @mousedown.prevent @click="editor.chain().focus().redo().run()">重做</button>
-      </div>
-      <div v-if="linkOpen && !disabled && !readonly" class="n-sm" ui-flex="row lm">
-        <input v-model="link" aria-label="链接地址" placeholder="https://" @keydown.enter.prevent="applyLink" />
-        <button type="button" @click="applyLink">应用链接</button>
-        <button type="button" @click="linkOpen = false">取消</button>
-        <span v-if="linkError" role="alert">请输入 http、https 或 mailto 地址</span>
-      </div>
-      <EditorContent :editor="editor" />
-    </template>
-  </div>
-</template>
-<script setup lang="ts">
-  import { onMounted, onBeforeUnmount, shallowRef, watch, ref } from 'vue';
-  import { Editor, EditorContent } from '@tiptap/vue-3';
-  import StarterKit from '@tiptap/starter-kit';
-  const props = withDefaults(defineProps<{
-    modelValue?: string; disabled?: boolean; readonly?: boolean; label?: string;
-  }>(), { modelValue: '', disabled: false, readonly: false, label: '富文本内容' });
-  const emit = defineEmits(['update:modelValue', 'change', 'focus', 'blur']);
-  const editor = shallowRef<Editor>();
-  const linkOpen = ref(false);
-  const link = ref('');
-  const linkError = ref(false);
-  let linkSelection = { from: 1, to: 1 };
-  onMounted(() => {
-    editor.value = new Editor({
-      extensions: [StarterKit.configure({ link: { openOnClick: false } })],
-      content: props.modelValue,
-      editable: !props.disabled && !props.readonly,
-      editorProps: { attributes: { role: 'textbox', 'aria-multiline': 'true', 'aria-label': props.label } },
-      onUpdate: ({ editor }) => {
-        const value = editor.isEmpty ? '' : editor.getHTML();
-        emit('update:modelValue', value);
-        emit('change', value);
-      },
-      onFocus: ({ event }) => emit('focus', event),
-      onBlur: ({ event }) => emit('blur', event),
-    });
-  });
-  onBeforeUnmount(() => editor.value?.destroy());
-  watch(() => props.modelValue, value => {
-    const instance = editor.value;
-    if (instance && value !== (instance.isEmpty ? '' : instance.getHTML())) instance.commands.setContent(value || '', { emitUpdate: false });
-  });
-  watch(() => [props.disabled, props.readonly], () => {
-    editor.value?.setEditable(!props.disabled && !props.readonly, false);
-    linkOpen.value = false;
-  });
-  const tools = [
-    { label: '加粗', active: 'bold', run: () => editor.value?.chain().focus().toggleBold().run() },
-    { label: '斜体', active: 'italic', run: () => editor.value?.chain().focus().toggleItalic().run() },
-    { label: '下划线', active: 'underline', run: () => editor.value?.chain().focus().toggleUnderline().run() },
-    { label: '标题', active: 'heading', run: () => editor.value?.chain().focus().toggleHeading({ level: 2 }).run() },
-    { label: '无序列表', active: 'bulletList', run: () => editor.value?.chain().focus().toggleBulletList().run() },
-    { label: '有序列表', active: 'orderedList', run: () => editor.value?.chain().focus().toggleOrderedList().run() },
-    { label: '引用', active: 'blockquote', run: () => editor.value?.chain().focus().toggleBlockquote().run() },
-    { label: '清除格式', run: () => editor.value?.chain().focus().unsetAllMarks().clearNodes().run() },
-  ];
-  const openLink = () => {
-    if (!editor.value) return;
-    const instance = editor.value;
-    const selection = instance.view.dom.ownerDocument.getSelection();
-    const { from, to } = instance.state.selection;
-    linkSelection = { from, to };
-    // DOM 选区更新可能先于编辑器的 selectionchange 事务。
-    if (selection?.anchorNode && selection.focusNode && instance.view.dom.contains(selection.anchorNode) && instance.view.dom.contains(selection.focusNode)) {
-      const anchor = instance.view.posAtDOM(selection.anchorNode, selection.anchorOffset);
-      const focus = instance.view.posAtDOM(selection.focusNode, selection.focusOffset);
-      linkSelection = { from: Math.min(anchor, focus), to: Math.max(anchor, focus) };
-    }
-    link.value = editor.value?.getAttributes('link').href || '';
-    linkError.value = false;
-    linkOpen.value = true;
-  };
-  const applyLink = () => {
-    if (props.disabled || props.readonly) return;
-    const href = link.value.trim();
-    if (href && !/^(https?:\/\/|mailto:)/i.test(href)) { linkError.value = true; return; }
-    const chain = editor.value?.chain().focus().setTextSelection(linkSelection).extendMarkRange('link');
-    if (href) chain?.setLink({ href }).run(); else chain?.unsetLink().run();
-    linkOpen.value = false;
-  };
-</script>
-<style scoped>
-  .neat-rich-text :deep(.tiptap) { min-height: 10rem; padding: .75rem; outline-offset: -2px; overflow-wrap: anywhere; }
-  .neat-rich-text :deep(ul) { list-style: disc; padding-left: 1.5rem; }
-  .neat-rich-text :deep(ol) { list-style: decimal; padding-left: 1.5rem; }
-  .neat-rich-text :deep(blockquote) { border-left: 3px solid currentColor; padding-left: .75rem; }
-  .neat-rich-text :deep(a) { text-decoration: underline; }
-</style>