@neatui/vue 5.1.0 → 5.1.1

package/MIGRATION-5.0.md

@@ -60,6 +60,10 @@ Vue 最低版本声明统一为 3.5.11，与已有 Pinia 3 的要求一致；同
 
 ## 新增与行为修复
 
+- 渲染结构精简：节点即元素，attrs 原样落在节点元素上。无标题的 Text / Html / Button 节点只输出内容元素本身；分组、数组内部的层级不再包根元素，子节点直接落在节点元素（无标题分组）或内容容器（有标题分组）里；纯文本不再包 span，不输出空的 style / ui-col。模板不输出说明注释，空内容、没有提示、没有 submit 时不留占位注释（客户端渲染）。依赖旧包裹层（`.flex-block > [ui-row]`、内容节点外层 div、`span`）的样式或测试需要调整。
+- id 只给字段：`表单前缀-数据路径`（`.` 换成 `-`），如 `apply-contact-phone`、`apply-members-0-name`；前缀为 `idx`，未传时由 useId 生成 6 位短串。分组、容器、内容节点不再输出 id，需要时在 attrs 里写。旧的 `form-<idx>-g0-field-x` / `group-0` 形式不再生成，错误提示 id 为 `<字段 id>-error`。
+- `child` 可写成 `{ attrs, lists }`：attrs（可为函数）描述承载子节点的容器；容器用 ui-flex 布局时不加栅格和默认间距 `n-sl-sub`，写了 class 时替换默认间距；无标题分组的节点元素就是容器，节点写了 class 时同样不加默认间距（与根元素规则一致）。
+- `media: false`：这一层不用栅格，自身不带 ui-col，分组 / 数组的下一层也不带 ui-row；ui-col 只在所在层有栅格时输出；`rows=""` 时根元素不再输出空的 ui-row。
 - 标题与内容均可递归组合；数组支持默认值、数量限制、增删排序和行上下文。
 - 新增 `setErrors`（回填服务端错误）、`isDirty / getChanges`（未保存改动）、`setBaseline`（设置重置基线）、`getData({ visibleOnly })`（去掉隐藏字段），`validate({ paths })` 支持局部校验。在同一对象上用 `Object.assign` 加载记录后调用 `setBaseline()`。
 - `validate()` 等待异步联动并检查最新数据；`reset()` 恢复当前数据对象的初始状态；`clearValidate()` 取消未完成校验。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neatui/vue",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "basic component ui",
   "main": "./src/index.ts",
   "license": "MIT",
@@ -36,7 +36,7 @@
     "@fekit/scrollto": "^3.0.3",
     "@fekit/toast": "^2.7.2",
     "@fekit/utils": "^6.0.0",
-    "@neatui/css": "^5.1.0",
+    "@neatui/css": "^5.1.1",
     "@rollup/plugin-commonjs": "^26.0.1",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@vue/compiler-sfc": "^3.4.30",

package/src/components/basic/IRouterView.vue

@@ -316,7 +316,7 @@
     .side-preview {
       min-width: 10rem;
       height: 100%;
-      box-shadow: -0.25em 0 0.5em rgba(0, 0, 0, 0.05);
+      box-shadow: -0.25em 0 0.5em var(--co-deep-o-mm);
       pointer-events: auto;
 
       &[ui-card~='@a'][ui-card~=':max'] {

package/src/components/form/Input.vue

@@ -1,6 +1,6 @@
 <template>
   <div
-    :ui-form="`${theme} sz:${sz} ${state.error.co} type:input ${block ? ' :block' : ''} ${disabled ? 'disabled' : ''} ${readonly ? 'readonly' : ''} ${preview ? 'preview' : ''}`"
+    :ui-form="[theme, sz && `sz:${sz}`, state.error.co, 'type:input', block && ':block', disabled && 'disabled', readonly && 'readonly', preview && 'preview'].filter(Boolean).join(' ')"
     @click="emits('click', $event)"
   >
     <div v-if="state.interacted" :ui-form-tips="state.error.ontips">{{ state.error.tips }}</div>

package/src/components/form/InputNumber.vue

@@ -1,6 +1,6 @@
 <template>
   <div
-    :ui-form="`${theme} sz:${sz} ${state.error.co} type:input ${block ? ' :block' : ''} ${disabled ? 'disabled' : ''} ${readonly ? 'readonly' : ''}`"
+    :ui-form="[theme, sz && `sz:${sz}`, state.error.co, 'type:input', block && ':block', disabled && 'disabled', readonly && 'readonly'].filter(Boolean).join(' ')"
     @click="emits('click', $event)"
   >
     <div :ui-form-tips="state.error.ontips">{{ state.error.tips }}</div>

package/src/components/form/InputRange.vue

@@ -1,5 +1,5 @@
 <template>
-  <div :ui-form="`${theme} sz:${sz} ${state.co} type:input ${block ? ' :block' : ''} ${disabled ? 'disabled' : ''} ${readonly ? 'readonly' : ''}`" @click="emits('click', $event)">
+  <div :ui-form="[theme, sz && `sz:${sz}`, state.co, 'type:input', block && ':block', disabled && 'disabled', readonly && 'readonly'].filter(Boolean).join(' ')" @click="emits('click', $event)">
     <div v-if="ready" :ui-form-tips="state.ontips">{{ state.tips }}</div>
     <div ui-form-prefix="">
       <template v-for="(item, idx) in prefix" :key="idx">

package/src/components/form/Textarea.vue

@@ -1,6 +1,6 @@
 <template>
   <div
-    :ui-form="`${theme} sz:${sz} ${state.error.co} type:textarea ${isAutoHeight ? 'auto-height' : ''} ${block ? ' :block' : ''} ${disabled ? 'disabled' : ''} ${readonly ? 'readonly' : ''}`"
+    :ui-form="[theme, sz && `sz:${sz}`, state.error.co, 'type:textarea', isAutoHeight && 'auto-height', block && ':block', disabled && 'disabled', readonly && 'readonly'].filter(Boolean).join(' ')"
     @click="emits('click', $event)"
   >
     <div :ui-form-tips="state.error.ontips">{{ state.error.tips }}</div>

package/src/components/form/TimePicker.vue

@@ -1,5 +1,5 @@
 <template>
-  <div :ui-form="`${theme} type:input ${disabled ? 'disabled' : ''}`">
+  <div :ui-form="[theme, 'type:input', disabled && 'disabled'].filter(Boolean).join(' ')">
     <input type="time" :value="modelValue || ''" :min="min" :max="max" :step="step" :disabled="disabled" :readonly="readonly"
       :aria-invalid="error ? true : undefined" :aria-label="label" :required="required" @input="update" @change="change" @blur="emit('blur', $event)" @focus="emit('focus', $event)" />
     <span v-if="verify && error" role="alert" class="co-risk">{{ error }}</span>

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

@@ -1,175 +1,143 @@
 <template>
-  <div :ui-row="rows" :class="rootClass">
+  <Level :bare="bare" v-bind="bare ? undefined : { 'ui-row': rows || undefined, class: rootClass }">
     <template v-for="(col, idx) in state.form" :key="idx">
-      <div
-        v-if="isGroup(col) || !isCleared(col)"
-        :id="col._fid"
-        :ui-col="col.media"
-        :ui-flex="`${isVertical(col) ? 'col xm' : 'row lt'}`"
-        :data-path="debug ? fieldPath(col) || undefined : undefined"
-        :title="debug ? debugInfo(col) : undefined"
-        v-bind="col.attrs || {}"
-        :style="isCleared(col) ? { display: 'none' } : undefined"
-        v-on="isGroup(col) || col._array ? eventsOf(col, context()) : {}"
-      >
-        <!-- ${field}-row：整行自定义，包括标签 -->
-        <div v-if="rowSlot(col)" class="flex-block" @focusout="col._touched = true">
-          <slot :name="rowSlot(col)" v-bind="fieldScope(col)"></slot>
-          <FieldMessage :col="col" :mode="mode" />
-        </div>
-        <template v-else>
-          <!-- 标签：${field}-label / array-label / child-label / label 插槽可以接管 -->
-          <FormLoader
-            v-if="labelNodes(col.label)"
-            :form="labelNodes(col.label)"
-            :clearContext="{ value: isCleared(col), restore: canRestore(col) }"
-            :arrayContext="col._array ? arrayContext(col) : arrayContextProp"
-            :data="col._data"
-            :root="rootData"
-            :path="[path, col.paths].filter(Boolean).join('.')"
-            :index="index"
-            :idx="`${childIdx(col, idx)}-label`"
-            :mode="mode"
-            :interacted="touched"
-            :debug="debug"
-            rows=""
-            class="w-full"
-            ui-flex="row lm"
-          />
-          <template v-else-if="labelText(col.label)">
-            <h6 v-if="isVertical(col)" :style="`${showStar(col) ? 'text-indent: -1em' : ''}`" :class="labelClass" v-bind="labelAttrs(col.label)">
-              <slot v-if="labelSlot(col)" :name="labelSlot(col)" :col="col" :node="col" :data="col._data" :text="formatLabel(col)"></slot>
-              <template v-else-if="labelText(col.label) !== '*'">
-                <b v-if="showStar(col)" class="co-risk pr" style="left: 0.1em">﹡</b>
-                <span>{{ formatLabel(col) }}</span>
-              </template>
-            </h6>
-            <p
-              v-else
-              :class="[labelClass, `${clh({ ...(col.model[1] || {}) })}`]"
-              :style="labelStyle(col)"
-              class="ar nr-sm flex-fixed o-ls"
-              v-bind="labelAttrs(col.label)"
-            >
-              <slot v-if="labelSlot(col)" :name="labelSlot(col)" :col="col" :node="col" :data="col._data" :text="formatLabel(col)"></slot>
-              <template v-else-if="labelText(col.label) !== '*'">
-                <b v-if="showStar(col)" class="co-risk">﹡</b>
-                <span>{{ formatLabel(col) }}</span>
-              </template>
-            </p>
-          </template>
+      <template v-if="isGroup(col) || !isCleared(col)">
+        <FormRender v-if="isBareContent(col)" bare :col="col" :mode="mode" :interacted="touched" :ctx="context()" v-bind="nodeAttrs(col)" />
+
+        <div v-else v-bind="nodeAttrs(col)" v-on="isGroup(col) || col._array ? eventsOf(col, context()) : {}">
+          <div v-if="rowSlot(col)" class="flex-block" @focusout="col._touched = true">
+            <slot :name="rowSlot(col)" v-bind="fieldScope(col)"></slot>
+            <FieldMessage :col="col" :mode="mode" />
+          </div>
+
+          <FormLoader v-else-if="isGroup(col) && !hasLabel(col)" v-bind="childProps(col)">
+            <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
+          </FormLoader>
 
-          <!-- 分组：递归渲染，带 field 时写入 data[field]，否则和当前层共用数据 -->
-          <div v-if="isGroup(col)" class="flex-block" :style="col.attrs?.['ui-flex'] ? { display: 'contents' } : undefined">
+          <template v-else>
             <FormLoader
-              :form="col.child || []"
+              v-if="labelNodes(col.label)"
+              :form="labelNodes(col.label)"
               :clearContext="{ value: isCleared(col), restore: canRestore(col) }"
-              :arrayContext="arrayContextProp"
-              :data="childData(col)"
+              :arrayContext="col._array ? arrayContext(col) : arrayContextProp"
+              :data="col._data"
               :root="rootData"
-              :path="fieldPath(col)"
+              :path="[path, col.paths].filter(Boolean).join('.')"
               :index="index"
-              :idx="childIdx(col, idx)"
-              :rows="col.attrs?.['ui-row'] ?? rows"
-              :style="col.attrs?.['ui-flex'] ? { display: 'contents' } : undefined"
+              :idx="baseIdx"
               :mode="mode"
-              :interacted="interacted"
-              :colon="colon"
-              :labelClass="labelClass"
-              :labelWidth="labelWidth"
-              :vertical="vertical"
+              :interacted="touched"
               :debug="debug"
-            >
-              <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
-            </FormLoader>
-          </div>
+              rows=""
+              class="w-full"
+              ui-flex="row lm"
+            />
+            <h6 v-else-if="labelText(col.label) && isVertical(col)" :style="showStar(col) ? 'text-indent: -1em' : undefined" :class="labelClass || undefined" v-bind="labelAttrs(col.label)">
+              <slot v-if="labelSlot(col)" :name="labelSlot(col)" :col="col" :node="col" :data="col._data" :text="formatLabel(col)"></slot>
+              <template v-else-if="labelText(col.label) !== '*' && showStar(col)"><b class="co-risk pr" style="left: 0.1em">﹡</b>{{ formatLabel(col) }}</template>
+              <template v-else-if="labelText(col.label) !== '*'">{{ formatLabel(col) }}</template>
+            </h6>
+            <p v-else-if="labelText(col.label)" :class="[labelClass, clh({ ...(col.model[1] || {}) })]" :style="labelStyle(col)" class="ar nr-sm flex-fixed o-ls" v-bind="labelAttrs(col.label)">
+              <slot v-if="labelSlot(col)" :name="labelSlot(col)" :col="col" :node="col" :data="col._data" :text="formatLabel(col)"></slot>
+              <template v-else-if="labelText(col.label) !== '*' && showStar(col)"><b class="co-risk">﹡</b>{{ formatLabel(col) }}</template>
+              <template v-else-if="labelText(col.label) !== '*'">{{ formatLabel(col) }}</template>
+            </p>
 
-          <!-- 数组：每一行是一个子表单，支持增删和排序 -->
-          <div v-else-if="col._array" class="flex-block">
-            <div ui-row="">
-              <div v-for="(row, i) in listOf(col)" :key="rowKey(row)" :ui-col="col._array.attrs?.['ui-col'] || 'mob-24'" ui-flex="row lt" class="mb-xs" v-bind="col._array.attrs || {}">
-                <div class="flex-block">
-                  <FormLoader
-                    :form="col._array.child"
-                    :arrayContext="arrayContext(col, row)"
-                    :data="row"
-                    :root="rootData"
-                    :path="`${fieldPath(col)}.${i}`"
-                    :index="i"
-                    :idx="`${childIdx(col, idx)}-${i}`"
-                    :rows="col._array.rows || col.attrs?.['ui-row'] || rows"
-                    :mode="mode"
-                    :interacted="interacted"
-                    :colon="colon"
-                    :labelClass="labelClass"
-                    :labelWidth="labelWidth"
-                    :vertical="vertical"
-                    :debug="debug"
-                  >
+            <div v-if="isGroup(col)" v-bind="boxAttrs(col)">
+              <FormLoader v-bind="childProps(col)">
+                <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
+              </FormLoader>
+            </div>
+
+            <div v-else-if="col._array" class="flex-block">
+              <div v-if="listOf(col).length" ui-row>
+                <div v-for="(row, i) in listOf(col)" :key="rowKey(row)" v-bind="rowAttrs(col)">
+                  <div v-if="hasActions(col)" v-bind="rowBox(col)">
+                    <FormLoader v-bind="rowProps(col, row, i)">
+                      <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
+                    </FormLoader>
+                  </div>
+                  <FormLoader v-else v-bind="rowProps(col, row, i)">
                     <template v-for="name in childSlots()" #[name]="scope"><slot :name="name" v-bind="scope || {}"></slot></template>
                   </FormLoader>
-                </div>
-                <div v-if="editable && (hasSlot(`${col.field}-actions`) || col._array.sortable || col._array.del !== false)" class="flex-fixed nl-sm" ui-flex="row lm">
-                  <slot v-if="hasSlot(`${col.field}-actions`)" :name="`${col.field}-actions`" v-bind="rowScope(col, i)"></slot>
-                  <template v-else>
-                    <template v-if="col._array.sortable">
-                      <button ui-btn="@a s" type="button" :disabled="i === 0" @click="moveRow(col, i, -1)">上移</button>
-                      <button ui-btn="@a s" type="button" class="ml-xs" :disabled="i === listOf(col).length - 1" @click="moveRow(col, i, 1)">下移</button>
+                  <div v-if="hasActions(col)" class="flex-fixed nl-sm" ui-flex="row lm">
+                    <slot v-if="hasSlot(`${col.field}-actions`)" :name="`${col.field}-actions`" v-bind="rowScope(col, i)"></slot>
+                    <template v-else>
+                      <template v-if="col._array.sortable">
+                        <button ui-btn="@a s" type="button" :disabled="i === 0" @click="moveRow(col, i, -1)">上移</button>
+                        <button ui-btn="@a s" type="button" class="ml-xs" :disabled="i === listOf(col).length - 1" @click="moveRow(col, i, 1)">下移</button>
+                      </template>
+                      <button
+                        v-if="col._array.del !== false"
+                        ui-btn="@a s risk"
+                        type="button"
+                        class="ml-xs"
+                        :disabled="listOf(col).length <= (col._array.min || 0)"
+                        @click="removeRow(col, i)"
+                      >
+                        {{ col._array.del || '删除' }}
+                      </button>
                     </template>
-                    <button
-                      v-if="col._array.del !== false"
-                      ui-btn="@a s risk"
-                      type="button"
-                      class="ml-xs"
-                      :disabled="listOf(col).length <= (col._array.min || 0)"
-                      @click="removeRow(col, i)"
-                    >
-                      {{ col._array.del || '删除' }}
-                    </button>
-                  </template>
+                  </div>
                 </div>
               </div>
+              <template v-if="editable && col._array.add !== false">
+                <slot v-if="hasSlot(`${col.field}-add`)" :name="`${col.field}-add`" :col="col" :list="listOf(col)" :add="() => addRow(col)"></slot>
+                <button v-else ui-btn="@a s" type="button" :disabled="!!col._array.max && listOf(col).length >= col._array.max" @click="addRow(col)">
+                  {{ col._array.add || '+ 添加一项' }}
+                </button>
+              </template>
+              <div v-if="!editable && !listOf(col).length" class="lh-ls">-</div>
+              <FieldMessage :col="col" :mode="mode" />
             </div>
-            <template v-if="editable && col._array.add !== false">
-              <slot v-if="hasSlot(`${col.field}-add`)" :name="`${col.field}-add`" :col="col" :list="listOf(col)" :add="() => addRow(col)"></slot>
-              <button v-else ui-btn="@a s" type="button" :disabled="!!col._array.max && listOf(col).length >= col._array.max" @click="addRow(col)">
-                {{ col._array.add || '+ 添加一项' }}
-              </button>
-            </template>
-            <div v-if="!editable && !listOf(col).length" class="lh-ls">-</div>
-            <FieldMessage :col="col" :mode="mode" />
-          </div>
 
-          <!-- 叶节点：输入、内容、按钮和自定义控件使用相同的 value / event -->
-          <FormRender v-else :col="col" :mode="mode" :entry="resolveEntry(col)" :interacted="touched" :ctx="context()" :custom="(!editable && hasSlot(`${col.field}-value`)) || !resolveEntry(col)">
-            <slot v-if="!editable && hasSlot(`${col.field}-value`)" :name="`${col.field}-value`" v-bind="fieldScope(col)"></slot>
-            <template v-else>
-              <!-- 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>
-        </template>
-      </div>
+            <FormRender v-else :col="col" :mode="mode" :entry="resolveEntry(col)" :interacted="touched" :ctx="context()" :custom="(!editable && hasSlot(`${col.field}-value`)) || !resolveEntry(col)">
+              <slot v-if="!editable && hasSlot(`${col.field}-value`)" :name="`${col.field}-value`" v-bind="fieldScope(col)"></slot>
+              <template v-else>
+                <slot v-if="col.slot" :name="col.slot" v-bind="fieldScope(col)"></slot>
+                <slot v-else-if="col.model[0]" :name="col.model[0]" v-bind="fieldScope(col)"></slot>
+                <slot v-else :name="col.field" v-bind="fieldScope(col)"></slot>
+              </template>
+            </FormRender>
+          </template>
+        </div>
+      </template>
     </template>
-    <div v-if="$slots.submit" :ui-flex="`${vertical ? 'col xm' : 'row xt'}`">
-      <div v-if="vertical">
-        <slot name="submit"></slot>
-      </div>
-      <div v-else :style="submitStyle">
+    <div v-if="!bare && $slots.submit" :ui-flex="vertical ? 'col xm' : 'row xt'">
+      <div :style="vertical ? undefined : submitStyle || undefined">
         <slot name="submit"></slot>
       </div>
     </div>
-  </div>
+  </Level>
 </template>
 <script lang="ts" setup>
-  import { watch, reactive, shallowRef, onMounted, onBeforeUnmount, useAttrs, useSlots, computed, provide, inject, toRaw, nextTick, watchEffect, useId, isReactive, isReadonly } from 'vue';
+  import { Comment, h, watch, reactive, shallowRef, onMounted, onBeforeUnmount, useAttrs, useSlots, computed, provide, inject, toRaw, nextTick, watchEffect, useId, isReactive, isReadonly } from 'vue';
   import { useRoute, useRouter } from 'vue-router';
   import { isString, isObject, deepcopy, isArray, isFunction } from '@fekit/utils';
   import FormRender, { getField, emptyValueOf, clh, isEmpty, labelText, labelAttrs, rulesOf, displayOf, valueBinding, labelNodes, eventsOf, writeValue, FieldMessage } from './FormRender.vue';
   import type { PropType, ShallowRef } from 'vue';
   import type { FormItem, FormArrayContext, FormContext, FormError, FormValidateResult, LinkageTask, FormRule } from './FormRender.vue';
+
+  // 层级根：最外层输出 div（接收透传属性），分组 / 数组内部的层级（bare）只输出子节点；
+  // 顶层的条件占位注释（没有 submit 等）一并过滤，客户端与 SSR 一致。模板根部不能有注释，否则透传属性失效。
+  const Level: any = (props: { bare?: boolean }, { slots, attrs }: any) => {
+    const children = (slots.default?.() || []).filter((node: any) => node.type !== Comment);
+    return props.bare ? children : h('div', attrs, children);
+  };
+  Level.props = ['bare'];
+  Level.inheritAttrs = false;
+
+  // 未传 idx 时的 id 前缀：由 useId 算出的 6 位短串，SSR 与客户端一致，同页多个表单不冲突
+  const shortHash = (text: string) => {
+    let h = 2166136261;
+    for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619);
+    return (h >>> 0).toString(36).padStart(6, '0').slice(-6);
+  };
+
+  // child 两种写法：节点数组，或 { attrs, lists }（兼容 child 作为 lists 的别名）；动态配置交给联动
+  const isChildBox = (child: any) => isObject(child) && !isArray(child) && !isFunction(child.setup) && child.watch === undefined
+    && (isArray(child.lists) || isArray(child.child) || child.attrs !== undefined);
+  const childList = (child: any): any[] | null => (isArray(child) ? child : isChildBox(child) ? child.lists || child.child || [] : null);
   // 计算Label宽度
   const clw = (label: any = '') => {
     let emWidth = 0;
@@ -256,6 +224,13 @@
     return _model;
   };
 
+  // child: { attrs, lists } 拆成子节点数组和容器属性
+  const splitChild = (item: any) => {
+    if (!isChildBox(item.child)) return;
+    item._childAttrs = item.child.attrs;
+    item.child = childList(item.child);
+  };
+
   // 规范化数组配置，兼容旧版 array: 'field' 和 lists
   const normalizeArray = (array: any) => {
     if (isString(array)) return { child: [{ field: array }] };
@@ -269,11 +244,12 @@
     list.forEach((item: any = {}) => {
       if (!isObject(item)) return;
       const target = ensurePath(row, item.paths);
-      if (isArray(item.child) && !item.array) {
+      const child = childList(item.child);
+      if (child && !item.array) {
         if (item.field) {
-          target[item.field] = createRow(item.child, getEmpty);
+          target[item.field] = createRow(child, getEmpty);
         } else {
-          Object.assign(target, createRow(item.child, getEmpty));
+          Object.assign(target, createRow(child, getEmpty));
         }
       } else if (item.field) {
         target[item.field] = getEmpty(item);
@@ -625,6 +601,11 @@
       default: false,
     },
     // 以下由分组和数组内部传递
+    // 内部层级：不输出根元素，子节点直接落在上一层的容器里
+    bare: {
+      type: Boolean,
+      default: false,
+    },
     // 根表单数据，联动函数和 watch 都基于它
     root: {
       type: Object as any,
@@ -680,7 +661,7 @@
 
   const rootData = computed(() => props.root || props.data);
   // 根表单未传 idx 时用 useId 生成前缀，同页多个表单的同名字段 id 不再冲突；SSR 与客户端一致。
-  const autoIdx = useId().replace(/[^\w-]/g, '-');
+  const autoIdx = `f${shortHash(useId())}`;
   const baseIdx = computed(() => (props.idx !== '' ? String(props.idx) : props.root ? '' : autoIdx));
   const cancelValidation = () => {
     shared.validationEpoch++;
@@ -766,6 +747,106 @@
   // 整行插槽
   const rowSlot = (col: any = {}) => (col.field && hasSlot(`${col.field}-row`) ? `${col.field}-row` : '');
 
+  // ---- 渲染结构：节点即元素，只补 id / ui-col / 布局 / 调试 / 隐藏，空值不输出 ----
+  // 模板分支：${field}-row 整行插槽 → 无标题分组（节点元素即容器）→ 标题（节点树 / h6 / p，插槽 ${field}-label、array-label、child-label、label）
+  // → 有标题分组（标题 + 内容容器）→ 数组（行；有操作按钮时分字段区与按钮区）→ 字段（控件 + 错误提示；字段级 slot 兼容 4.x）
+  const hasLabel = (col: any = {}) => !!labelNodes(col.label) || !!labelText(col.label);
+  // 无标题的 Text / Html / Button 内容节点直接输出内容元素
+  const isBareContent = (col: any = {}) => !col.field && !isGroup(col) && !col._array && !hasLabel(col) && !rowSlot(col)
+    && ['Text', 'Html', 'Button'].includes(col.model?.[0]);
+  // 所在层有栅格时才输出 ui-col；分组、数组默认占满一行；false 不用栅格
+  const mediaOf = (col: any = {}) => (!props.rows || col.media === false ? undefined : col.media || (isGroup(col) || col._array ? 'mob-24' : undefined));
+  const joinClass = (...list: any[]) => {
+    const out = list.filter((v) => v !== undefined && v !== null && v !== '' && !(isArray(v) && !v.length));
+    return out.length ? (out.length === 1 ? out[0] : out) : undefined;
+  };
+  // 子节点容器：child.attrs（可为函数）+ 这一层的栅格；ui-flex 布局时不加栅格和默认间距；写了 class 时由外部接管间距（与根元素一致）
+  const childAttrsOf = (col: any) => {
+    const attrs = col._childAttrs;
+    return (isFunction(attrs) ? attrs(col._data, col, context()) : attrs) || {};
+  };
+  const levelOf = (col: any, flex?: string, styled = false) => {
+    const { 'ui-row': row, ...own } = childAttrsOf(col);
+    const layout = own['ui-flex'] ?? flex;
+    const rows = col.media === false || layout ? '' : String(row ?? col.attrs?.['ui-row'] ?? props.rows ?? '');
+    return { rows, attrs: { ...own, 'ui-row': rows || undefined, class: 'class' in own ? own.class : layout || styled ? undefined : 'n-sl-sub' } };
+  };
+  // 节点元素；无标题分组的节点元素同时是下一层容器
+  const nodeAttrs = (col: any) => {
+    const { 'ui-row': _row, ...own } = col.attrs || {};
+    const out: Record<string, any> = { ...own };
+    const group = isGroup(col);
+    const box = group && !hasLabel(col) && !rowSlot(col);
+    if (col._fid) out.id = col._fid;
+    const media = mediaOf(col);
+    if (media) out['ui-col'] = media;
+    if (box) {
+      // 无标题分组的节点元素就是容器：节点写了 class 时不再加默认间距
+      const level = levelOf(col, own['ui-flex'], own.class !== undefined).attrs;
+      Object.assign(out, level, { class: joinClass(own.class, level.class) });
+    } else if (!isBareContent(col) && own['ui-flex'] === undefined) {
+      out['ui-flex'] = isVertical(col) ? 'col xm' : 'row lt';
+    }
+    if (props.debug) {
+      out['data-path'] = fieldPath(col) || undefined;
+      out.title = debugInfo(col);
+    }
+    if (isCleared(col)) out.style = joinClass(own.style, { display: 'none' });
+    return out;
+  };
+  // 有标题分组的子节点容器
+  const boxAttrs = (col: any) => {
+    const { attrs } = levelOf(col);
+    return { ...attrs, class: joinClass('flex-block', attrs.class) };
+  };
+  const levelProps = () => ({
+    bare: true,
+    root: rootData.value,
+    mode: props.mode,
+    interacted: props.interacted,
+    colon: props.colon,
+    labelClass: props.labelClass,
+    labelWidth: props.labelWidth,
+    vertical: props.vertical,
+    debug: props.debug,
+    idx: baseIdx.value,
+  });
+  const childProps = (col: any) => ({
+    ...levelProps(),
+    form: col.child || [],
+    clearContext: { value: isCleared(col), restore: canRestore(col) },
+    arrayContext: props.arrayContext,
+    data: childData(col),
+    path: fieldPath(col),
+    index: props.index,
+    rows: levelOf(col, hasLabel(col) ? undefined : col.attrs?.['ui-flex']).rows,
+  });
+  // 数组：行栅格、行元素、行内字段区
+  const hasActions = (col: any) => editable.value && (hasSlot(`${col.field}-actions`) || !!col._array.sortable || col._array.del !== false);
+  const rowRows = (col: any) => (col.media === false ? '' : col._array.rows || col.attrs?.['ui-row'] || props.rows || '');
+  const rowAttrs = (col: any) => {
+    const own = col._array.attrs || {};
+    const out: Record<string, any> = { ...own, 'ui-col': own['ui-col'] || 'mob-24', class: joinClass('mb-xs', own.class) };
+    if (hasActions(col)) {
+      if (own['ui-flex'] === undefined) out['ui-flex'] = 'row lt';
+    } else if (own['ui-flex'] === undefined) {
+      // 没有操作按钮时行元素本身承载这一行的字段
+      out['ui-row'] = rowRows(col) || undefined;
+      out.class = joinClass('mb-xs', own.class ?? 'n-sl-sub');
+    }
+    return out;
+  };
+  const rowBox = (col: any) => ({ class: 'flex-block n-sl-sub', 'ui-row': rowRows(col) || undefined });
+  const rowProps = (col: any, row: any, i: number) => ({
+    ...levelProps(),
+    form: col._array.child,
+    arrayContext: arrayContext(col, row),
+    data: row,
+    path: `${fieldPath(col)}.${i}`,
+    index: i,
+    rows: hasActions(col) || (col._array.attrs || {})['ui-flex'] === undefined ? rowRows(col) : '',
+  });
+
   // 表单默认标签宽度；单个标签用 label[1].style 覆盖。
   const widthOf = (value: any) => {
     if (value === 'auto') return '';
@@ -778,9 +859,8 @@
     return style ? style.replace(/^width:([^;]+);.*$/, 'padding-left:$1;') : '';
   });
 
-  // 分组、数组的路径和 id 前缀
+  // 字段数据路径（也是字段 id 的主体）
   const fieldPath = (col: any = {}) => [props.path, col.paths, col.field].filter(Boolean).join('.');
-  const childIdx = (col: any = {}, idx: number) => [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] : []);
 
@@ -800,7 +880,7 @@
   const initialOf = (item: any = {}) => {
     if (valueBinding(item.value) && item.value.default !== undefined) return deepcopy(item.value.default);
     if (item.array) return [];
-    if (isArray(item.child)) return {};
+    if (childList(item.child)) return {};
     return emptyValueOf(isString(item.model) || isArray(item.model) ? normalizeModel(item.model) : ['']);
   };
 
@@ -885,6 +965,7 @@
     apply: (target, key, result) => {
       target[key] = key === 'model' ? normalizeModel(result) : result;
       if (key === 'array') target._array = result ? normalizeArray(result) : null;
+      if (key === 'child') splitChild(target);
       if (key === 'child' || key === 'array') initializeField(target);
     },
   });
@@ -925,6 +1006,7 @@
       if (isObject(item)) {
         linkage.resolve(item, idx, tasks);
       }
+      splitChild(item);
 
       item._array = item.array ? normalizeArray(item.array) : item._kind === 'array' ? { child: [] } : null;
 
@@ -941,7 +1023,7 @@
       }
 
       // 添加ID
-      item._fid = `form-${baseIdx.value !== '' ? baseIdx.value + '-' : ''}${!item.field && isGroup(item) ? `group-${idx}` : `field-${item.field || `node-${idx}`}`}`;
+      item._fid = item.field ? [baseIdx.value, fieldPath(item).replace(/\./g, '-')].filter(Boolean).join('-') : '';
 
       // 数据路径处理
       item._data = resolvePath(props.data, item.paths);
@@ -953,9 +1035,6 @@
         fields.add(key);
         initializeField(item);
       }
-
-      // 分组、数组默认占满一行
-      if ((isGroup(item) || item._array) && !item.media) item.media = 'mob-24';
       return item;
     });
     linkage.start(tasks);
@@ -984,14 +1063,15 @@
   watch(
     [() => state.form, () => props.data, () => props.clearContext],
     () => {
-      state.form.forEach((item: any = {}) => {
+      state.form.forEach((item: any = {}, idx: number) => {
         if (isGroup(item)) return; // 保留递归实例，由解析后的子节点各自清空和恢复。
         const cache = canRestore(item) ? shared.cache : undefined;
+        const key = item._fid || `#${idx}`;
         if (isCleared(item)) {
-          hiddenFields.add(item._fid);
+          hiddenFields.add(key);
           emptyField(resolvePath(props.data, item.paths), item.field, cache);
-        } else if (hiddenFields.has(item._fid) || firstRun) {
-          hiddenFields.delete(item._fid);
+        } else if (hiddenFields.has(key) || firstRun) {
+          hiddenFields.delete(key);
           if (cache) restoreField(resolvePath(props.data, item.paths), item.field, cache);
         }
       });

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

@@ -1,9 +1,12 @@
 <template>
-  <div ref="root" class="flex-block pr" @focusout="col._touched = true">
+  <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="contentAttrs" v-on="events"><FieldExtra :value="displayOf(col, ctx)" :trusted="trusted" /></button>
+    <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"><FieldExtra :value="displayOf(col, ctx)" :trusted="trusted" /></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"
@@ -108,13 +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;
     // 固定内容、{ text, html, attrs } 内容对象、VNode、数组；绑定字段时用 { default, get, set }；也可以是函数或联动配置
     value?: FormValue | FormContent | FormSetup | FormLinkage<FormContent>;
-    child?: Dynamic<FormItem[]>;
+    // 子节点；{ attrs, lists } 时 attrs 落在承载子节点的容器上（无标题分组即节点元素本身）
+    child?: Dynamic<FormItem[]> | FormChild;
     attrs?: Dynamic<Record<string, any>>;
     clear?: Dynamic<boolean | { value: boolean; restore?: boolean }>;
     enums?: Dynamic<any[]>;
@@ -123,7 +134,8 @@
     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 自定义字符）
@@ -253,7 +265,7 @@
     return handlers;
   };
 
-  // 内容渲染：字符串按文本渲染；VNode 原样渲染；{ text, html, attrs } 只有 html 为 true 且内容来自配置时才按 HTML 渲染
+  // 内容渲染：字符串直接输出文本节点；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;
@@ -262,18 +274,19 @@
       const { text = '', html = false, attrs = {} } = value;
       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({
@@ -396,6 +409,8 @@
     mode?: string;
     ctx: FormContext;
     custom?: boolean;
+    // 无标题的内容节点：不包字段容器，直接输出内容元素，节点 attrs 透传到这个元素上（模板根部不能有注释）
+    bare?: boolean;
   }>();
   // 在选项树里按 value 找 label
   const findLabel = (options: any[] = [], value: any): any => {
@@ -436,6 +451,12 @@
     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(() => {

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>