Feat/listtable columntree

common/changes/@visactor/vtable/feat-listtable-columntree_2025-04-03-10-14.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat: list table header support hierarchy \n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

docs/assets/demo/en/basic-functionality/list-table-header-group-collapse.md

@@ -0,0 +1,115 @@
+---
+category: examples
+group: Basic Features
+title: List Table - Header Group Collapse
+cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/list-table-header-group.png
+link: table-type/list-table
+option: ListTable-columns-text#columns
+---
+
+# List Table - Header Group Collapse
+
+Configure columns as a nested multi-layer structure to achieve multi-layer header grouping effects. Enable tree-style expansion and collapse functionality through `headerHierarchyType: 'grid-tree'`, and set the default expansion level with `headerExpandLevel`.
+
+## Key Configurations
+
+- columns
+- `headerHierarchyType` Set hierarchy display to `grid-tree` to enable tree-style expand/collapse
+- `headerExpandLevel` Configure default expansion level (defaults to 1)
+
+## Code demo
+
+```javascript livedemo template=vtable
+let tableInstance;
+const records = [
+  {
+    id: 1,
+    name: 'name.1',
+    name_1: 'name_1.1',
+    name_2: 'name_2.1',
+    name_2_1: 'name_2_1.1',
+    name_2_2: 'name_2_2.1'
+  },
+  {
+    id: 2,
+    name: 'name.2',
+    name_1: 'name_1.2',
+    name_2: 'name_2.2',
+    name_2_1: 'name_2_1.2',
+    name_2_2: 'name_2_2.2'
+  },
+  {
+    id: 3,
+    name: 'name.3',
+    name_1: 'name_1.3',
+    name_2: 'name_2.3',
+    name_2_1: 'name_2_1.3',
+    name_2_2: 'name_2_2.3'
+  },
+  {
+    id: 4,
+    name: 'name.4',
+    name_1: 'name_1.4',
+    name_2: 'name_2.4',
+    name_2_1: 'name_2_1.4',
+    name_2_2: 'name_2_2.4'
+  },
+  {
+    id: 5,
+    name: 'name.5',
+    name_1: 'name_1.5',
+    name_2: 'name_2.5',
+    name_2_1: 'name_2_1.5',
+    name_2_2: 'name_2_2.5'
+  }
+];
+
+const columns = [
+  {
+    field: 'id',
+    title: 'ID',
+    width: 100
+  },
+  {
+    field: 'name',
+    title: 'Name',
+    columns: [
+      {
+        field: 'name_1',
+        title: 'Name_1',
+        width: 120
+      },
+      {
+        field: 'name_2',
+        title: 'Name_2',
+        width: 150,
+        columns: [
+          {
+            field: 'name_2_1',
+            title: 'Name_2_1',
+            width: 150
+          },
+          {
+            field: 'name_2_2',
+            title: 'Name_2_2',
+            width: 150
+          }
+        ]
+      }
+    ]
+  }
+];
+
+const option = {
+  records,
+  columns,
+  headerHierarchyType: 'grid-tree',
+  headerExpandLevel: 3,
+  widthMode: 'standard',
+  autoWrapText: true,
+  autoRowHeight: true,
+  defaultColWidth: 150
+};
+tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+window['tableInstance'] = tableInstance;
+```

docs/assets/demo/menu.json

@@ -520,6 +520,13 @@
             "en": "List Table - Header Group"
           }
         },
+        {
+          "path": "list-table-header-group-collapse",
+          "title": {
+            "zh": "基本表格表头分组与折叠",
+            "en": "List Table - Header Group Collapse"
+          }
+        },
         {
           "path": "auto-wrap-text",
           "title": {

docs/assets/demo/zh/basic-functionality/list-table-header-group-collapse.md

@@ -0,0 +1,115 @@
+---
+category: examples
+group: Basic Features
+title: 基本表格表头分组与折叠
+cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/list-table-header-group.png
+link: table-type/list-table
+option: ListTable-columns-text#columns
+---
+
+# 基本表格表头分组与折叠
+
+将 columns 配置为嵌套多层结构来实现多层表头分组效果，可通过配置 `headerHierarchyType: 'grid-tree'` 开启树形的展开和折叠，并通过 `headerExpandLevel` 来设置默认展开层级。
+
+## 关键配置
+
+- columns
+- `headerHierarchyType` 将层级展示设置为 `grid-tree`，开启树形的展开和折叠功能
+- `headerExpandLevel` 设置默认展开层级，默认为`1`
+
+## 代码演示
+
+```javascript livedemo template=vtable
+let tableInstance;
+const records = [
+  {
+    id: 1,
+    name: 'name.1',
+    name_1: 'name_1.1',
+    name_2: 'name_2.1',
+    name_2_1: 'name_2_1.1',
+    name_2_2: 'name_2_2.1'
+  },
+  {
+    id: 2,
+    name: 'name.2',
+    name_1: 'name_1.2',
+    name_2: 'name_2.2',
+    name_2_1: 'name_2_1.2',
+    name_2_2: 'name_2_2.2'
+  },
+  {
+    id: 3,
+    name: 'name.3',
+    name_1: 'name_1.3',
+    name_2: 'name_2.3',
+    name_2_1: 'name_2_1.3',
+    name_2_2: 'name_2_2.3'
+  },
+  {
+    id: 4,
+    name: 'name.4',
+    name_1: 'name_1.4',
+    name_2: 'name_2.4',
+    name_2_1: 'name_2_1.4',
+    name_2_2: 'name_2_2.4'
+  },
+  {
+    id: 5,
+    name: 'name.5',
+    name_1: 'name_1.5',
+    name_2: 'name_2.5',
+    name_2_1: 'name_2_1.5',
+    name_2_2: 'name_2_2.5'
+  }
+];
+
+const columns = [
+  {
+    field: 'id',
+    title: 'ID',
+    width: 100
+  },
+  {
+    field: 'name',
+    title: 'Name',
+    columns: [
+      {
+        field: 'name_1',
+        title: 'Name_1',
+        width: 120
+      },
+      {
+        field: 'name_2',
+        title: 'Name_2',
+        width: 150,
+        columns: [
+          {
+            field: 'name_2_1',
+            title: 'Name_2_1',
+            width: 150
+          },
+          {
+            field: 'name_2_2',
+            title: 'Name_2_2',
+            width: 150
+          }
+        ]
+      }
+    ]
+  }
+];
+
+const option = {
+  records,
+  columns,
+  headerHierarchyType: 'grid-tree',
+  headerExpandLevel: 3,
+  widthMode: 'standard',
+  autoWrapText: true,
+  autoRowHeight: true,
+  defaultColWidth: 150
+};
+tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+window['tableInstance'] = tableInstance;
+```

docs/assets/guide/en/table_type/List_table/columns_tree.md

@@ -0,0 +1,114 @@
+## Basic Table Header Grouping and Collapsing
+
+In this tutorial, we will learn how to implement multi-level header grouping and collapsing in VTable using a tree structure to visualize complex header hierarchies.
+
+---
+
+## Use Cases
+
+Header grouping and collapsing are suitable for the following scenarios:
+
+- **Multidimensional Data Analysis**: Combine related fields into logical groups (e.g., "Sales Data" includes sub-columns like "Revenue" and "Profit").
+- **Complex Data Structures**: Tables with explicit hierarchical relationships (e.g., "Region-Province-City" three-level structure).
+- **Space Optimization**: Improve readability by collapsing non-critical columns.
+- **Dynamic Interaction**: Allow users to expand/collapse specific groups on demand for flexible data exploration.
+
+---
+
+## Implementation Steps
+
+### 1. Configure Multi-Level Header Structure
+
+Define header hierarchies using nested structures in the `columns` configuration. Each group adds sub-columns via the `columns` field to form a tree relationship.
+
+### 2. Enable Tree-Style Collapsing
+
+Set `headerHierarchyType: 'grid-tree'` to enable interactive tree-style collapsing for headers.
+
+### 3. Set Default Expansion Level
+
+Specify the initial expansion level using `headerExpandLevel` (default: `1`, showing only the first-level groups).
+
+---
+
+## Example
+
+```javascript livedemo template=vtable
+const records = [
+  { region: 'North', province: 'Province A', city: 'City 1', revenue: 1000, cost: 600 },
+  { region: 'North', province: 'Province A', city: 'City 2', revenue: 1500, cost: 800 },
+  { region: 'South', province: 'Province B', city: 'City 3', revenue: 2000, cost: 1100 }
+];
+
+const columns = [
+  {
+    title: 'Region',
+    field: 'region',
+    width: 150,
+    columns: [
+      {
+        title: 'Province',
+        field: 'province',
+        width: 150,
+        columns: [
+          {
+            title: 'City',
+            field: 'city',
+            width: 150
+          }
+        ]
+      }
+    ]
+  },
+  {
+    title: 'Financial Metrics',
+    field: 'metrics',
+    width: 180,
+    columns: [
+      { title: 'Revenue', field: 'revenue', width: 150 },
+      { title: 'Cost', field: 'cost', width: 150 }
+    ]
+  }
+];
+
+const option = {
+  records,
+  columns,
+  headerHierarchyType: 'grid-tree', // Enable tree-style collapsing
+  headerExpandLevel: 2, // Expand to the second level by default
+  widthMode: 'standard',
+  defaultRowHeight: 40
+};
+
+const tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+window.tableInstance = tableInstance;
+```
+
+---
+
+## Advanced Configuration
+
+### Listen to Collapse Events
+
+Capture user interactions and execute custom logic:
+
+```javascript
+tableInstance.on(VTable.ListTable.EVENT_TYPE.TREE_HIERARCHY_STATE_CHANGE, args => {
+  if (args.cellLocation === 'columnHeader') {
+    console.log('Header state changed:', args);
+  }
+});
+```
+
+### Dynamically Update Header States
+
+Programmatically control header expansion/collapse:
+
+```javascript
+// Toggle the expansion state of a specific column
+tableInstance.toggleHierarchyState(col, row);
+```
+
+---
+
+With these configurations, you can quickly implement structured multi-level headers with dynamic interactions, ideal for complex data analysis scenarios.

docs/assets/guide/menu.json

@@ -87,6 +87,13 @@
                 "en": "tree list"
               }
             },
+            {
+              "path": "columns_tree",
+              "title": {
+                "zh": "表头分组及折叠",
+                "en": "Columns tree"
+              }
+            },
             {
               "path": "group_list",
               "title": {