Skip to content

Commit 8dd8aa4

Browse files
author
李杨枚
committed
docs: add docs and guide of ListTable header folding
1 parent 09e2a94 commit 8dd8aa4

9 files changed

Lines changed: 481 additions & 1 deletion

File tree

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

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
category: examples
3+
group: Basic Features
4+
title: List Table - Header Group Collapse
5+
cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/list-table-header-group.png
6+
link: table-type/list-table
7+
option: ListTable-columns-text#columns
8+
---
9+
10+
# List Table - Header Group Collapse
11+
12+
Configure columns as a nested multi-layer structure to achieve multi-layer header grouping effects. Enable tree-style expansion and collapse functionality through `columnHierarchyType: 'grid-tree'`, and set the default expansion level with `columnExpandLevel`.
13+
14+
## Key Configurations
15+
16+
- columns
17+
- `columnHierarchyType` Set hierarchy display to `grid-tree` to enable tree-style expand/collapse
18+
- `columnExpandLevel` Configure default expansion level (defaults to 1)
19+
20+
## Code demo
21+
22+
```javascript livedemo template=vtable
23+
let tableInstance;
24+
const records = [
25+
{
26+
id: 1,
27+
name: 'name.1',
28+
name_1: 'name_1.1',
29+
name_2: 'name_2.1',
30+
name_2_1: 'name_2_1.1',
31+
name_2_2: 'name_2_2.1'
32+
},
33+
{
34+
id: 2,
35+
name: 'name.2',
36+
name_1: 'name_1.2',
37+
name_2: 'name_2.2',
38+
name_2_1: 'name_2_1.2',
39+
name_2_2: 'name_2_2.2'
40+
},
41+
{
42+
id: 3,
43+
name: 'name.3',
44+
name_1: 'name_1.3',
45+
name_2: 'name_2.3',
46+
name_2_1: 'name_2_1.3',
47+
name_2_2: 'name_2_2.3'
48+
},
49+
{
50+
id: 4,
51+
name: 'name.4',
52+
name_1: 'name_1.4',
53+
name_2: 'name_2.4',
54+
name_2_1: 'name_2_1.4',
55+
name_2_2: 'name_2_2.4'
56+
},
57+
{
58+
id: 5,
59+
name: 'name.5',
60+
name_1: 'name_1.5',
61+
name_2: 'name_2.5',
62+
name_2_1: 'name_2_1.5',
63+
name_2_2: 'name_2_2.5'
64+
}
65+
];
66+
67+
const columns = [
68+
{
69+
field: 'id',
70+
title: 'ID',
71+
width: 100
72+
},
73+
{
74+
field: 'name',
75+
title: 'Name',
76+
columns: [
77+
{
78+
field: 'name_1',
79+
title: 'Name_1',
80+
width: 120
81+
},
82+
{
83+
field: 'name_2',
84+
title: 'Name_2',
85+
width: 150,
86+
columns: [
87+
{
88+
field: 'name_2_1',
89+
title: 'Name_2_1',
90+
width: 150
91+
},
92+
{
93+
field: 'name_2_2',
94+
title: 'Name_2_2',
95+
width: 150
96+
}
97+
]
98+
}
99+
]
100+
}
101+
];
102+
103+
const option = {
104+
records,
105+
columns,
106+
columnHierarchyType: 'grid-tree',
107+
columnExpandLevel: 3,
108+
widthMode: 'standard',
109+
autoWrapText: true,
110+
autoRowHeight: true,
111+
defaultColWidth: 150
112+
};
113+
tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
114+
window['tableInstance'] = tableInstance;
115+
```

‎docs/assets/demo/menu.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,6 +520,13 @@
520520
"en": "List Table - Header Group"
521521
}
522522
},
523+
{
524+
"path": "list-table-header-group-collapse",
525+
"title": {
526+
"zh": "基本表格表头分组与折叠",
527+
"en": "List Table - Header Group Collapse"
528+
}
529+
},
523530
{
524531
"path": "auto-wrap-text",
525532
"title": {

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

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
category: examples
3+
group: Basic Features
4+
title: 基本表格表头分组与折叠
5+
cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/list-table-header-group.png
6+
link: table-type/list-table
7+
option: ListTable-columns-text#columns
8+
---
9+
10+
# 基本表格表头分组与折叠
11+
12+
将 columns 配置为嵌套多层结构来实现多层表头分组效果，可通过配置 `columnHierarchyType: 'grid-tree'` 开启树形的展开和折叠，并通过 `columnExpandLevel` 来设置默认展开层级。
13+
14+
## 关键配置
15+
16+
- columns
17+
- `columnHierarchyType` 将层级展示设置为 `grid-tree`，开启树形的展开和折叠功能
18+
- `columnExpandLevel` 设置默认展开层级，默认为`1`
19+
20+
## 代码演示
21+
22+
```javascript livedemo template=vtable
23+
let tableInstance;
24+
const records = [
25+
{
26+
id: 1,
27+
name: 'name.1',
28+
name_1: 'name_1.1',
29+
name_2: 'name_2.1',
30+
name_2_1: 'name_2_1.1',
31+
name_2_2: 'name_2_2.1'
32+
},
33+
{
34+
id: 2,
35+
name: 'name.2',
36+
name_1: 'name_1.2',
37+
name_2: 'name_2.2',
38+
name_2_1: 'name_2_1.2',
39+
name_2_2: 'name_2_2.2'
40+
},
41+
{
42+
id: 3,
43+
name: 'name.3',
44+
name_1: 'name_1.3',
45+
name_2: 'name_2.3',
46+
name_2_1: 'name_2_1.3',
47+
name_2_2: 'name_2_2.3'
48+
},
49+
{
50+
id: 4,
51+
name: 'name.4',
52+
name_1: 'name_1.4',
53+
name_2: 'name_2.4',
54+
name_2_1: 'name_2_1.4',
55+
name_2_2: 'name_2_2.4'
56+
},
57+
{
58+
id: 5,
59+
name: 'name.5',
60+
name_1: 'name_1.5',
61+
name_2: 'name_2.5',
62+
name_2_1: 'name_2_1.5',
63+
name_2_2: 'name_2_2.5'
64+
}
65+
];
66+
67+
const columns = [
68+
{
69+
field: 'id',
70+
title: 'ID',
71+
width: 100
72+
},
73+
{
74+
field: 'name',
75+
title: 'Name',
76+
columns: [
77+
{
78+
field: 'name_1',
79+
title: 'Name_1',
80+
width: 120
81+
},
82+
{
83+
field: 'name_2',
84+
title: 'Name_2',
85+
width: 150,
86+
columns: [
87+
{
88+
field: 'name_2_1',
89+
title: 'Name_2_1',
90+
width: 150
91+
},
92+
{
93+
field: 'name_2_2',
94+
title: 'Name_2_2',
95+
width: 150
96+
}
97+
]
98+
}
99+
]
100+
}
101+
];
102+
103+
const option = {
104+
records,
105+
columns,
106+
columnHierarchyType: 'grid-tree',
107+
columnExpandLevel: 3,
108+
widthMode: 'standard',
109+
autoWrapText: true,
110+
autoRowHeight: true,
111+
defaultColWidth: 150
112+
};
113+
tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
114+
window['tableInstance'] = tableInstance;
115+
```

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

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
## Basic Table Header Grouping and Collapsing
2+
3+
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.
4+
5+
---
6+
7+
## Use Cases
8+
9+
Header grouping and collapsing are suitable for the following scenarios:
10+
11+
- **Multidimensional Data Analysis**: Combine related fields into logical groups (e.g., "Sales Data" includes sub-columns like "Revenue" and "Profit").
12+
- **Complex Data Structures**: Tables with explicit hierarchical relationships (e.g., "Region-Province-City" three-level structure).
13+
- **Space Optimization**: Improve readability by collapsing non-critical columns.
14+
- **Dynamic Interaction**: Allow users to expand/collapse specific groups on demand for flexible data exploration.
15+
16+
---
17+
18+
## Implementation Steps
19+
20+
### 1. Configure Multi-Level Header Structure
21+
22+
Define header hierarchies using nested structures in the `columns` configuration. Each group adds sub-columns via the `columns` field to form a tree relationship.
23+
24+
### 2. Enable Tree-Style Collapsing
25+
26+
Set `columnHierarchyType: 'grid-tree'` to enable interactive tree-style collapsing for headers.
27+
28+
### 3. Set Default Expansion Level
29+
30+
Specify the initial expansion level using `columnExpandLevel` (default: `1`, showing only the first-level groups).
31+
32+
---
33+
34+
## Example
35+
36+
```javascript livedemo template=vtable
37+
const records = [
38+
{ region: 'North', province: 'Province A', city: 'City 1', revenue: 1000, cost: 600 },
39+
{ region: 'North', province: 'Province A', city: 'City 2', revenue: 1500, cost: 800 },
40+
{ region: 'South', province: 'Province B', city: 'City 3', revenue: 2000, cost: 1100 }
41+
];
42+
43+
const columns = [
44+
{
45+
title: 'Region',
46+
field: 'region',
47+
width: 150,
48+
columns: [
49+
{
50+
title: 'Province',
51+
field: 'province',
52+
width: 150,
53+
columns: [
54+
{
55+
title: 'City',
56+
field: 'city',
57+
width: 150
58+
}
59+
]
60+
}
61+
]
62+
},
63+
{
64+
title: 'Financial Metrics',
65+
field: 'metrics',
66+
width: 180,
67+
columns: [
68+
{ title: 'Revenue', field: 'revenue', width: 150 },
69+
{ title: 'Cost', field: 'cost', width: 150 }
70+
]
71+
}
72+
];
73+
74+
const option = {
75+
records,
76+
columns,
77+
columnHierarchyType: 'grid-tree', // Enable tree-style collapsing
78+
columnExpandLevel: 2, // Expand to the second level by default
79+
widthMode: 'standard',
80+
defaultRowHeight: 40
81+
};
82+
83+
const tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
84+
window.tableInstance = tableInstance;
85+
```
86+
87+
---
88+
89+
## Advanced Configuration
90+
91+
### Listen to Collapse Events
92+
93+
Capture user interactions and execute custom logic:
94+
95+
```javascript
96+
tableInstance.on(VTable.ListTable.EVENT_TYPE.TREE_HIERARCHY_STATE_CHANGE, args => {
97+
if (args.cellLocation === 'columnHeader') {
98+
console.log('Header state changed:', args);
99+
}
100+
});
101+
```
102+
103+
### Dynamically Update Header States
104+
105+
Programmatically control header expansion/collapse:
106+
107+
```javascript
108+
// Toggle the expansion state of a specific column
109+
tableInstance.toggleHierarchyState(col, row);
110+
```
111+
112+
---
113+
114+
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‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,13 @@
8787
"en": "tree list"
8888
}
8989
},
90+
{
91+
"path": "columns_tree",
92+
"title": {
93+
"zh": "表头分组及折叠",
94+
"en": "Columns tree"
95+
}
96+
},
9097
{
9198
"path": "group_list",
9299
"title": {

0 commit comments

Comments
 (0)