Merge pull request #5012 from Violet2314/feat/masterDetail-children-othername

feat(master-detail): add support for custom childrenKey in master-det…

Author: fangsmile

docs/assets/guide/en/plugin/master-detail.md

@@ -14,6 +14,8 @@ MasterDetailPlugin follows TypeScript interface specifications to ensure type sa
 interface MasterDetailPluginOptions {
   /** Whether to enable checkbox cascade functionality - controls checkbox linkage between master and detail tables, default is true */
   enableCheckboxCascade?: boolean;
+  /** Field name of sub-table data - This is used to specify the attribute name where the sub-table data is located in the record. The default value is 'children'. */
+  childrenKey?: string;
   /** Detail table configuration - can be static configuration object or dynamic configuration function */
   detailTableOptions?: DetailTableOptions | ((params: { data: unknown; bodyRowIndex: number }) => DetailTableOptions);
 }

docs/assets/guide/zh/plugin/master-detail.md

@@ -14,6 +14,8 @@ MasterDetailPlugin 采用 TypeScript 接口规范，确保类型安全和开发
 interface MasterDetailPluginOptions {
   /** 是否启用checkbox级联功能 - 控制主从表之间的复选框联动，默认为 true */
   enableCheckboxCascade?: boolean;
+  /** 子表数据的字段名 - 用于指定记录中子表数据所在的属性名，默认为 'children' */
+  childrenKey?: string;
   /** 子表配置选项 - 支持静态配置对象或动态配置函数 */
   detailTableOptions?: DetailTableOptions | ((params: { data: unknown; bodyRowIndex: number }) => DetailTableOptions);
 }

packages/vtable-plugins/demo/master-detail-plugin/master-detail-plugin9.ts

@@ -57,7 +57,7 @@ export function createTable() {
       status: '已完成',
       date: '2024-01-15',
       // 静态子表数据
-      children: [
+      items: [
         { productName: '笔记本电脑', quantity: 2, price: 5000, total: 10000 },
         { productName: '鼠标', quantity: 5, price: 100, total: 500 }
       ]
@@ -69,7 +69,7 @@ export function createTable() {
       amount: 25000,
       status: '处理中',
       date: '2024-01-16',
-      children: true // 懒加载标识 - 需要异步加载数据
+      items: true // 懒加载标识 - 需要异步加载数据
     },
     {
       id: 3,
@@ -78,7 +78,7 @@ export function createTable() {
       amount: 35000,
       status: '已完成',
       date: '2024-01-17',
-      children: true // 懒加载标识 - 需要异步加载数据
+      items: true // 懒加载标识 - 需要异步加载数据
     },
     {
       id: 4,
@@ -87,12 +87,12 @@ export function createTable() {
       amount: 18000,
       status: '待发货',
       date: '2024-01-18'
-      // 没有children属性，表示没有子数据，不显示展开图标
     }
   ];
 
   // 创建主从表插件
   const plugin = new MasterDetailPlugin({
+    childrenKey: 'items',
     enableCheckboxCascade: true,
     detailTableOptions: params => {
       const { data } = params;
@@ -116,7 +116,7 @@ export function createTable() {
   // 主表配置
   const tableOptions: VTable.ListTableConstructorOptions = {
     columns: [
-      { field: 'orderNo', title: '订单号', width: 120 },
+      { field: 'orderNo', title: '订单号', width: 120, sort: true },
       { field: 'customer', title: '客户名称', width: 150 },
       { field: 'amount', title: '订单金额', width: 120 },
       { field: 'status', title: '状态', width: 100 },

packages/vtable-plugins/src/master-detail-plugin/config.ts

@@ -6,8 +6,18 @@ import type { DetailTableOptions, MasterDetailPluginOptions } from './types';
  */
 export class ConfigManager {
   private expandRowCallback?: (rowIndex: number) => void;
+  private childrenKey: string;
 
-  constructor(private pluginOptions: MasterDetailPluginOptions, private table: VTable.ListTable) {}
+  constructor(private pluginOptions: MasterDetailPluginOptions, private table: VTable.ListTable) {
+    this.childrenKey = pluginOptions.childrenKey || 'children';
+  }
+
+  /**
+   * 获取子数据字段名
+   */
+  getChildrenKey(): string {
+    return this.childrenKey;
+  }
 
   /**
    * 设置展开行的回调函数
@@ -16,12 +26,41 @@ export class ConfigManager {
     this.expandRowCallback = callback;
   }
 
+  /**
+   * 创建 children 属性的 getter/setter，让 VTable 内部硬编码的 record.children
+   * 用来确保本来VTable中对于children的硬编码起作用
+   */
+  ensureChildrenAlias(record: unknown): void {
+    if (this.childrenKey === 'children') {
+      return; // 不需要别名
+    }
+    if (record && typeof record === 'object') {
+      const recordObj = record as Record<string, unknown>;
+      const key = this.childrenKey;
+      const descriptor = Object.getOwnPropertyDescriptor(recordObj, 'children');
+      if (descriptor && descriptor.get) {
+        return; // 已经设置过 getter，跳过
+      }
+      Object.defineProperty(recordObj, 'children', {
+        get() {
+          return this[key];
+        },
+        set(value: unknown) {
+          this[key] = value;
+        },
+        enumerable: false,
+        configurable: true
+      });
+    }
+  }
+
   /**
    * 检查记录是否有子数据
    */
-  private hasChildren(record: unknown): boolean {
-    if (record && typeof record === 'object' && 'children' in record) {
-      const children = record.children;
+  hasChildren(record: unknown): boolean {
+    const key = this.childrenKey;
+    if (record && typeof record === 'object' && key in record) {
+      const children = (record as Record<string, unknown>)[key];
       return Array.isArray(children) && children.length > 0;
     }
     return false;
@@ -130,8 +169,10 @@ export class ConfigManager {
       recordList.forEach(record => {
         if (record && typeof record === 'object') {
           const recordObj = record as Record<string, unknown>;
+          // 让 VTable 内部的 getHierarchyState / toggleHierarchyState 能正确检测
+          this.ensureChildrenAlias(record);
           // 处理有子数据的记录
-          if (this.hasChildren(record) || recordObj.children === true) {
+          if (this.hasChildren(record) || recordObj[this.childrenKey] === true) {
             // 优先级：records 中的 hierarchyState > hierarchyExpandLevel
             if (recordObj.hierarchyState === 'expand') {
               // 明确设置为展开
@@ -199,7 +240,7 @@ export class ConfigManager {
         const recordObj = record as Record<string, unknown>;
         // 检查是否需要展开
         if (
-          (this.hasChildren(record) || recordObj.children === true) &&
+          (this.hasChildren(record) || recordObj[this.childrenKey] === true) &&
           recordObj.hierarchyState === HierarchyState.expand
         ) {
           // 将记录索引添加到 expandedRecordIndices 中

packages/vtable-plugins/src/master-detail-plugin/core.ts

@@ -69,7 +69,7 @@ export class MasterDetailPlugin implements pluginsDefinition.IVTablePlugin {
    */
   private initializeManagers(): void {
     this.configManager = new ConfigManager(this.pluginOptions, this.table);
-    this.eventManager = new EventManager(this.table);
+    this.eventManager = new EventManager(this.table, this.configManager.getChildrenKey());
     const enableCheckboxCascade = this.pluginOptions.enableCheckboxCascade ?? true;
     this.subTableManager = new SubTableManager(this.table, enableCheckboxCascade);
 
@@ -255,7 +255,10 @@ export class MasterDetailPlugin implements pluginsDefinition.IVTablePlugin {
     const detailConfig = this.configManager.getDetailConfigForRecord(record, bodyRowIndex);
     const height = detailConfig?.style?.height || 300;
 
-    const childrenData = Array.isArray(record.children) ? record.children : [];
+    const childrenKey = this.configManager.getChildrenKey();
+    const childrenData = Array.isArray((record as Record<string, unknown>)[childrenKey])
+      ? ((record as Record<string, unknown>)[childrenKey] as unknown[])
+      : [];
 
     // 处理初始高度：如果是auto，先用默认值300展开
     const isAutoHeight = height === 'auto';
@@ -571,8 +574,9 @@ export class MasterDetailPlugin implements pluginsDefinition.IVTablePlugin {
       return;
     }
 
-    // 直接修改原始记录的 children 属性
-    (record as Record<string, unknown>).children = children;
+    // 直接修改原始记录的子数据属性
+    const childrenKey = this.configManager.getChildrenKey();
+    (record as Record<string, unknown>)[childrenKey] = children;
     this.expandRow(row, col);
     this.table.scenegraph.updateCellContent(col, row);
   }

packages/vtable-plugins/src/master-detail-plugin/events.ts

@@ -9,8 +9,11 @@ export class EventManager {
   private eventHandlers: Array<{ type: string; handler: (...args: unknown[]) => unknown }> = [];
   private allExpandedRowsBeforeMove: Set<number> = new Set();
   private isCleanedUp = false;
+  private childrenKey: string;
 
-  constructor(private table: VTable.ListTable) {}
+  constructor(private table: VTable.ListTable, childrenKey: string = 'children') {
+    this.childrenKey = childrenKey;
+  }
 
   /**
    * 绑定事件处理器
@@ -301,7 +304,12 @@ export class EventManager {
         row: number;
       };
       const record = this.getRecordByRowIndex(row - this.table.columnHeaderLevelCount);
-      if (record && typeof record === 'object' && 'children' in record && record.children === true) {
+      if (
+        record &&
+        typeof record === 'object' &&
+        this.childrenKey in record &&
+        (record as Record<string, unknown>)[this.childrenKey] === true
+      ) {
         return;
       }
       this.onToggleRowExpand?.(row, col);

packages/vtable-plugins/src/master-detail-plugin/types.ts

@@ -15,6 +15,8 @@ export interface DetailTableOptions extends VTable.ListTableConstructorOptions {
 export interface MasterDetailPluginOptions {
   /** 是否启用checkbox级联功能 - 控制主从表之间的复选框联动，默认为 true */
   enableCheckboxCascade?: boolean;
+  /** 子表数据的字段名 - 用于指定记录中子表数据所在的属性名，默认为 'children' */
+  childrenKey?: string;
   /** 子表配置 - 可以是静态配置对象或动态配置函数 */
   detailTableOptions?: DetailTableOptions | ((params: { data: unknown; bodyRowIndex: number }) => DetailTableOptions);
 }