@neatui/vue 5.0.0 → 5.1.1

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

@@ -1,24 +1,20 @@
 <template>
-  <div class="flex-block pr" @focusout="col._touched = true" :aria-describedby="col._error && mode !== 'view' ? `${col._fid}-error` : undefined">
+  <button v-if="bare && col.model[0] === 'Button'" type="button" ui-btn="@a s" v-bind="contentAttrs" v-on="events"><template v-if="plain !== null">{{ plain }}</template><FieldExtra v-else :value="displayOf(col, ctx)" :trusted="trusted" /></button>
+  <div v-else-if="bare && col.model[0] === 'Html' && trusted" v-bind="contentAttrs" v-on="events" v-html="displayOf(col, ctx)"></div>
+  <div v-else-if="bare" v-bind="contentAttrs" v-on="events"><template v-if="plain !== null">{{ plain }}</template><FieldExtra v-else :value="displayOf(col, ctx)" :trusted="trusted" /></div>
+  <div v-else 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"><template v-if="plain !== null">{{ plain }}</template><FieldExtra v-else :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"><template v-if="plain !== null">{{ plain }}</template><FieldExtra v-else :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 +22,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 +87,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
@@ -112,12 +111,21 @@
     item?: Record<string, any> | (() => Record<string, any>);
   }
 
+  /** 子节点容器：attrs 描述这一层容器（可以是函数），lists / child 是子节点 */
+  export interface FormChild {
+    attrs?: Record<string, any> | ((data: any, item: any, ctx: FormContext) => Record<string, any>);
+    lists?: FormItem[];
+    child?: FormItem[];
+  }
+
   /** 基础节点：标题和子节点复用同一套配置，不为装饰或交互增加专用字段。 */
   export interface FormItem {
     label?: Dynamic<string | [string, Record<string, any>] | FormItem[]>;
     field?: string;
-    value?: any | FormValue;
-    child?: Dynamic<FormItem[]>;
+    // 固定内容、{ text, html, attrs } 内容对象、VNode、数组；绑定字段时用 { default, get, set }；也可以是函数或联动配置
+    value?: FormValue | FormContent | FormSetup | FormLinkage<FormContent>;
+    // 子节点；{ attrs, lists } 时 attrs 落在承载子节点的容器上（无标题分组即节点元素本身）
+    child?: Dynamic<FormItem[]> | FormChild;
     attrs?: Dynamic<Record<string, any>>;
     clear?: Dynamic<boolean | { value: boolean; restore?: boolean }>;
     enums?: Dynamic<any[]>;
@@ -126,9 +134,29 @@
     model?: Dynamic<string | [string, Record<string, any>?]>;
     rules?: Dynamic<FormRule[]>;
     // 兼容原有布局和数据路径；普通容器布局也可直接使用 attrs。
-    media?: Dynamic<string>;
+    /** 自身 ui-col（只在所在层有栅格时输出）；false 表示不用栅格：自身不带 ui-col，分组 / 数组的下一层也不带 ui-row */
+    media?: Dynamic<string | false>;
     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 +175,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 +201,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,43 +265,44 @@
     return handlers;
   };
 
-  // 内容渲染：字符串按文本渲染；VNode 原样渲染；{ text, html, attrs } 只有 html 为 true 时才按 HTML 渲染
-  const render = (value: any): any => {
+  // 内容渲染：字符串直接输出文本节点；VNode 原样渲染；{ text, html, attrs } 需要属性才包 span，只有 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));
+    return String(value);
   };
 
   export const FieldMessage = defineComponent({
     props: ['col', 'mode'],
+    // 没有内容时返回空数组：客户端渲染不留占位注释
     setup: (props) => () => props.mode !== 'view' ? [
       props.col.model?.[1]?.verify && props.col._checked
         ? h('i', { 'ui-form-verify': props.col._error ? 'no' : isEmpty(props.col._data?.[props.col.field]) ? '' : 'ok', 'aria-hidden': 'true' }) : null,
       props.col._error ? h('p', { id: `${props.col._fid}-error`, 'data-field-error': props.col.field,
           role: props.col._error.type === 'warn' ? 'status' : 'alert',
           class: `mt-xs ${props.col._error.type === 'warn' ? 'co-warn' : 'co-risk'}` }, props.col._error.msg) : null,
-    ] : null,
+    ].filter(Boolean) : [],
   });
 
   export const FieldExtra = defineComponent({
     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 +336,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 +345,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 +384,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 +398,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;
@@ -369,6 +409,8 @@
     mode?: string;
     ctx: FormContext;
     custom?: boolean;
+    // 无标题的内容节点：不包字段容器，直接输出内容元素，节点 attrs 透传到这个元素上（模板根部不能有注释）
+    bare?: boolean;
   }>();
   // 在选项树里按 value 找 label
   const findLabel = (options: any[] = [], value: any): any => {
@@ -404,6 +446,79 @@
     }
     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));
+  });
+  // 字符串、数字、布尔直接输出文本（空值不留占位注释）；VNode、{ text, html }、数组交给 FieldExtra
+  const plain = computed(() => {
+    const value = displayOf(props.col, props.ctx);
+    if (value === null || value === undefined) return '';
+    return typeof value === 'object' ? null : String(value);
+  });
   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/TableLoader/TableLoader.vue

@@ -101,14 +101,15 @@
             <td :colspan="columnCount" :style="virtualPadStyle(virtualSlice.padTop)"></td>
           </tr>
           <tr
-            v-for="{ item, idx } in virtualSlice.rows"
-            :key="rowKeyOf(item, idx)"
-            :ref="virtualEnabled ? (el: any) => bindVirtualRow(el, item) : undefined"
+            v-for="row in bodyRows"
+            :key="row.key"
+            :ref="virtualEnabled ? (el: any) => bindVirtualRow(el, row.item) : undefined"
             v-bind="rows.attrs"
-            v-on="event(rows.event, item, 'td')"
+            v-on="event(rows.event, row.item, 'td')"
+            :data-level="treeEnabled ? row.level : undefined"
           >
             <td v-if="selected" col-fixed="1" min-width :col-fixed-side="fixedSide('__select')" :style="fixedStyle('__select')">
-              <label class="mb-ss" ui-form="@a type:checkbox"><input type="checkbox" v-model="item.__selected" /><span></span></label>
+              <label v-if="row.level === 1" class="mb-ss" ui-form="@a type:checkbox"><input type="checkbox" v-model="row.item.__selected" /><span></span></label>
             </td>
             <template v-for="(col, cid) in state.table" :key="cid">
               <td
@@ -119,12 +120,41 @@
                 :col-fixed-side="fixedSide(col.field)"
                 :style="fixedStyle(col.field)"
                 :data-field="col.field"
+                :data-tree="row.level > 1 && col.field === treeField ? 1 : undefined"
               >
-                <slot :name="col.field" :col="col" :item="item" :idx="idx"><TableRender :node="col" :data="item" /></slot>
+                <div v-if="treeEnabled && col.field === treeField && row.level === 1" class="table-tree-node" ui-flex="row lm">
+                  <i
+                    v-if="childrenOf(row.item).length"
+                    class="table-tree-toggle ux-none"
+                    :data-fold="row.item.__folding ? 1 : 0"
+                    @click.stop="row.item.__folding = !row.item.__folding"
+                  ></i>
+                  <i v-else class="table-tree-toggle-pad"></i>
+                  <slot :name="col.field" :col="col" :item="row.item" :idx="row.idx" :parent="row.parent" :level="1"><TableRender :node="col" :data="row.item" /></slot>
+                </div>
+                <div v-else-if="treeEnabled && col.field === treeField && row.level === 2" class="table-tree-child" :data-last="row.last ? 1 : 0">
+                  <div v-if="depth > 2" class="table-tree-node" ui-flex="row lm">
+                    <i
+                      v-if="childrenOf(row.item).length"
+                      class="table-tree-toggle ux-none"
+                      :data-fold="row.item.__folding ? 1 : 0"
+                      @click.stop="row.item.__folding = !row.item.__folding"
+                    ></i>
+                    <i v-else class="table-tree-toggle-pad"></i>
+                    <slot :name="col.field" :col="col" :item="row.item" :idx="row.idx" :parent="row.parent" :level="2"><TableRender v-if="childHas(col, row.item)" :node="col" :data="row.item" /></slot>
+                  </div>
+                  <slot v-else :name="col.field" :col="col" :item="row.item" :idx="row.idx" :parent="row.parent" :level="2"><TableRender v-if="childHas(col, row.item)" :node="col" :data="row.item" /></slot>
+                </div>
+                <div v-else-if="treeEnabled && col.field === treeField" class="table-tree-child" data-pass="1" :data-last="row.parentLast ? 1 : 0">
+                  <div class="table-tree-child" :data-last="row.last ? 1 : 0">
+                    <slot :name="col.field" :col="col" :item="row.item" :idx="row.idx" :parent="row.parent" :level="row.level"><TableRender v-if="childHas(col, row.item)" :node="col" :data="row.item" /></slot>
+                  </div>
+                </div>
+                <slot v-else :name="col.field" :col="col" :item="row.item" :idx="row.idx" :parent="row.parent" :level="row.level"><TableRender v-if="row.level === 1 || childHas(col, row.item)" :node="col" :data="row.item" /></slot>
               </td>
             </template>
             <td v-if="slots.operate" col-fixed="r" class="ar" :col-fixed-side="fixedSide('__operate')" :style="fixedStyle('__operate')">
-              <slot name="operate" :item="item" :idx="idx"></slot>
+              <slot name="operate" :item="row.item" :idx="row.idx" :parent="row.parent" :level="row.level"></slot>
             </td>
           </tr>
           <tr v-if="virtualSlice.padBottom" class="table-virtual-pad" aria-hidden="true">
@@ -158,21 +188,71 @@
             </IFollowView>
           </div>
         </li>
-        <li v-for="(item, idx) in lists" :key="rowKeyOf(item, idx)" class="bg-fore r-sm my-sl n-ms">
-          <table>
-            <tbody>
-              <template v-for="(col, idx) in state.table" :key="idx">
-                <tr v-if="!col.__close">
-                  <td class="nowrap vt n-ss">{{ col.label }}:</td>
-                  <td class="n-ss">
-                    <TableRender :node="col" :data="item" />
-                  </td>
-                </tr>
+        <template v-for="(item, idx) in lists" :key="rowKeyOf(item, idx)">
+          <li class="bg-fore r-sm my-sl n-ms">
+            <table>
+              <tbody>
+                <template v-for="(col, cid) in state.table" :key="cid">
+                  <tr v-if="!col.__close">
+                    <td class="nowrap vt n-ss">{{ col.label }}:</td>
+                    <td class="n-ss">
+                      <TableRender :node="col" :data="item" />
+                    </td>
+                  </tr>
+                </template>
+              </tbody>
+            </table>
+            <div v-if="slots.operate"><slot name="operate" :item="item" :idx="idx" :parent="noParent" :level="1"></slot></div>
+            <p v-if="treeEnabled && childrenOf(item).length" class="mt-ss">
+              <span class="ux-none co-main fs-sm" @click="item.__folding = !item.__folding">
+                {{ item.__folding ? words['common.expand'] || '展开' : words['common.collapse'] || '收起' }}
+              </span>
+            </p>
+          </li>
+          <template v-if="treeEnabled && !item.__folding">
+            <template v-for="(child, cidx) in childrenOf(item)" :key="`${rowKeyOf(item, idx)}-${cidx}`">
+              <li v-if="childVisible(child)" class="table-tree-item bg-fore r-sm my-sl n-ms">
+                <table>
+                  <tbody>
+                    <template v-for="(col, cid) in state.table" :key="cid">
+                      <tr v-if="!col.__close && childHas(col, child)">
+                        <td class="nowrap vt n-ss">{{ col.label }}:</td>
+                        <td class="n-ss">
+                          <TableRender :node="col" :data="child" />
+                        </td>
+                      </tr>
+                    </template>
+                  </tbody>
+                </table>
+                <div v-if="slots.operate"><slot name="operate" :item="child" :idx="cidx" :parent="item" :level="2"></slot></div>
+                <p v-if="depth > 2 && childrenOf(child).length" class="mt-ss">
+                  <span class="ux-none co-main fs-sm" @click="child.__folding = !child.__folding">
+                    {{ child.__folding ? words['common.expand'] || '展开' : words['common.collapse'] || '收起' }}
+                  </span>
+                </p>
+              </li>
+              <template v-if="depth > 2 && !child.__folding">
+                <template v-for="(grand, gidx) in childrenOf(child)" :key="`${rowKeyOf(item, idx)}-${cidx}-${gidx}`">
+                  <li v-if="childVisible(grand)" class="table-tree-item table-tree-item-3 bg-fore r-sm my-sl n-ms">
+                    <table>
+                      <tbody>
+                        <template v-for="(col, cid) in state.table" :key="cid">
+                          <tr v-if="!col.__close && childHas(col, grand)">
+                            <td class="nowrap vt n-ss">{{ col.label }}:</td>
+                            <td class="n-ss">
+                              <TableRender :node="col" :data="grand" />
+                            </td>
+                          </tr>
+                        </template>
+                      </tbody>
+                    </table>
+                    <div v-if="slots.operate"><slot name="operate" :item="grand" :idx="gidx" :parent="child" :level="3"></slot></div>
+                  </li>
+                </template>
               </template>
-            </tbody>
-          </table>
-          <div v-if="slots.operate"><slot name="operate" :item="item" :idx="idx"></slot></div>
-        </li>
+            </template>
+          </template>
+        </template>
       </ul>
     </div>
     <div v-if="!lists.length" class="ny-ls o-mm" ui-flex="col cm">
@@ -245,6 +325,12 @@
     rowKey?: string | ((item: any, idx: number) => string | number);
     /** 虚拟滚动（仅表格形态）：只渲染可视区附近的行，需要容器限定高度 */
     virtual?: boolean | { estimate?: number; overscan?: number };
+    /** 子行：字段名或函数，返回子行数组；子行沿用同一套列和插槽，折叠状态记在行的 __folding 上 */
+    children?: string | ((item: any) => any[]);
+    /** 折叠按钮和树线所在列的 field，默认第一个可见的非固定列 */
+    tree?: string;
+    /** 树的层数：默认 2（父行 + 子行）；3 时子行再按 children 取第三层 */
+    depth?: number;
   }
   // 外部入参
   const props: any = withDefaults(defineProps<Props>(), {
@@ -258,6 +344,7 @@
     allSelected: false,
     layout: 'auto',
     virtual: false,
+    depth: 2,
   });
 
   /**
@@ -347,7 +434,7 @@
   watch(
     () => props.table,
     () => {
-      const _cache = env.client ? JSON.parse(window.localStorage.getItem(`${name}_table`) || '{}') : {};
+      const _cache = env.client ? JSON.parse(window.localStorage.getItem(`${name.value}_table`) || '{}') : {};
       state.__last = 0;
       state.table = deepcopy(props.table || [])
         ?.map((col: TableColumn, idx: number) => {
@@ -426,7 +513,7 @@
           state.__last = idx;
         }
       });
-      if (env.client) window.localStorage.setItem(`${name}_table`, JSON.stringify(_table));
+      if (env.client) window.localStorage.setItem(`${name.value}_table`, JSON.stringify(_table));
     },
     { deep: true },
   );
@@ -540,6 +627,25 @@
     fixedCells.clear();
   });
 
+  // 子行
+  const treeEnabled = computed(() => !!props.children);
+  const childrenOf = (item: any): any[] => {
+    const key = props.children;
+    const list = isFunction(key) ? key(item) : key && item ? item[key] : undefined;
+    return Array.isArray(list) ? list : [];
+  };
+  // 父行的 parent 为空；声明成 any，插槽里两层行的 parent 类型才一致
+  const noParent: any = undefined;
+  // 子行常常只有部分字段，没有的列留空，不显示占位符
+  const childHas = (col: TableColumn, child: any) =>
+    (!!child && typeof child === 'object' && hasOwnProp(child, col.field)) || (col.value !== undefined && col.value !== null) || !!(col as any).child || !!(col as any).popup;
+  const childVisible = (child: any) => state.table.some((col) => !col.__close && childHas(col, child));
+  const treeField = computed(() => {
+    if (props.tree) return props.tree;
+    const visible = state.table.filter((col) => !col.__close);
+    return (visible.find((col) => !col.fixed) || visible[0])?.field;
+  });
+
   // 行标识
   const rowKeyOf = (item: any, idx: number) => {
     const key = props.rowKey;
@@ -553,7 +659,8 @@
    * 行高各不相同（单元格可能换行、放表单控件），按行对象缓存实测高度，
    * 没测过的按已测平均值估算；行对象不变则删行、排序后缓存仍有效。
    */
-  const virtualEnabled = computed(() => !!props.virtual);
+  // 行高按父行测量，展开的子行会让偏移失真，开了子行就不走虚拟滚动
+  const virtualEnabled = computed(() => !!props.virtual && !props.children);
   const virtualEstimate = computed(() => (isObject(props.virtual) && props.virtual.estimate) || 48);
   const virtualOverscan = computed(() => (isObject(props.virtual) && props.virtual.overscan) || 600);
   const scrollTop = ref(0);
@@ -586,6 +693,30 @@
     return { rows, padTop: offsets[start] || 0, padBottom: Math.max(0, offsets[offsets.length - 1] - (offsets[end] || 0)) };
   });
 
+  /** 桌面表格逐行渲染：开了子行时把树按展开状态摊平，记下层级、上级和是否同级最后一行（画树线用） */
+  const bodyRows = computed(() => {
+    if (!treeEnabled.value) {
+      return virtualSlice.value.rows.map(({ item, idx }: any) => ({ item, idx, level: 1, parent: noParent, key: rowKeyOf(item, idx), last: false, parentLast: false }));
+    }
+    const out: any[] = [];
+    props.lists.forEach((item: any, idx: number) => {
+      const key = rowKeyOf(item, idx);
+      out.push({ item, idx, level: 1, parent: noParent, key, last: false, parentLast: false });
+      if (item?.__folding) return;
+      const kids = childrenOf(item);
+      kids.forEach((child, cidx) => {
+        const last = cidx === kids.length - 1;
+        out.push({ item: child, idx: cidx, level: 2, parent: item, key: `${key}-${cidx}`, last, parentLast: false });
+        if (props.depth < 3 || child?.__folding) return;
+        const grand = childrenOf(child);
+        grand.forEach((g, gidx) => {
+          out.push({ item: g, idx: gidx, level: 3, parent: child, key: `${key}-${cidx}-${gidx}`, last: gidx === grand.length - 1, parentLast: last });
+        });
+      });
+    });
+    return out;
+  });
+
   let scrollFrame = 0;
   const onVirtualScroll = () => {
     if (!virtualEnabled.value || scrollFrame) return;
@@ -706,3 +837,81 @@
     return { ..._event };
   };
 </script>
+<style lang="scss" scoped>
+  .table-tree-node {
+    flex-wrap: nowrap;
+  }
+  .table-tree-toggle,
+  .table-tree-toggle-pad {
+    flex: none;
+    position: relative;
+    width: 1em;
+    height: 1em;
+    margin-right: 0.25em;
+  }
+  .table-tree-toggle {
+    cursor: pointer;
+    &::after {
+      position: absolute;
+      content: '';
+      top: 50%;
+      left: 50%;
+      border-width: 0.35em 0 0.35em 0.35em;
+      border-style: solid;
+      border-color: transparent transparent transparent currentColor;
+      border-radius: 30%;
+      transform: translate(-30%, -50%) rotate(90deg);
+      transition: transform 0.25s;
+    }
+    &[data-fold='1']::after {
+      transform: translate(-30%, -50%) rotate(0deg);
+    }
+  }
+
+  // 树线画在内层，纵向裁到单元格高度，横向不裁，固定列的阴影照常显示
+  td[data-tree] {
+    clip-path: inset(0 -100vw);
+    &:not([col-fixed]) {
+      position: relative;
+    }
+  }
+  .table-tree-child {
+    position: relative;
+    padding-left: 1.75em;
+    &::before,
+    &::after {
+      position: absolute;
+      content: '';
+      left: 0.5em;
+      background: var(--co-line);
+    }
+    &::before {
+      width: 1px;
+      top: -100vh;
+      bottom: -100vh;
+    }
+    &[data-last='1']::before {
+      bottom: 50%;
+    }
+    &::after {
+      width: 0.85em;
+      height: 1px;
+      top: 50%;
+    }
+  }
+  // 第三层：外层只画上一层的竖线（上一层是最后一行就不画），内层画自己的
+  .table-tree-child[data-pass='1'] {
+    &::after {
+      display: none;
+    }
+    &[data-last='1']::before {
+      display: none;
+    }
+  }
+  .table-tree-item {
+    margin-left: 1.5em;
+  }
+  .table-tree-item-3 {
+    margin-left: 3em;
+  }
+</style>