Feat/group

common/changes/@visactor/vtable/feat-group_2024-07-17-04-01.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@visactor/vtable",
+      "comment": "feat: add group function",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@visactor/vtable"
+}

docs/assets/demo/en/table-type/list-table-group.md

@@ -0,0 +1,110 @@
+---
+category: examples
+group: table-type
+title: Basic table grouping display
+cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/list-group.jpeg
+order: 1-2
+link: '../guide/table_type/List_table/group_list'
+option: ListTable#groupBy
+---
+
+# Basic table grouping display
+
+Basic table grouping display, used to display the hierarchical structure of grouping fields in data
+
+## Key configuration
+
+- groupBy: Specify the grouping field name
+
+## Code demonstration
+
+```javascript livedemo template=vtable
+  const titleColorPool = ['#3370ff', '#34c724', '#ff9f1a', '#ff4050', '#1f2329'];
+  let tableInstance;
+  fetch('https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/North_American_Superstore_data.json')
+    .then(res => res.json())
+    .then(data => {
+      const columns = [
+        {
+          field: 'Order ID',
+          title: 'Order ID',
+          width: 'auto'
+        },
+        {
+          field: 'Customer ID',
+          title: 'Customer ID',
+          width: 'auto'
+        },
+        {
+          field: 'Product Name',
+          title: 'Product Name',
+          width: 'auto'
+        },
+        {
+          field: 'Category',
+          title: 'Category',
+          width: 'auto'
+        },
+        {
+          field: 'Sub-Category',
+          title: 'Sub-Category',
+          width: 'auto'
+        },
+        {
+          field: 'Region',
+          title: 'Region',
+          width: 'auto'
+        },
+        {
+          field: 'City',
+          title: 'City',
+          width: 'auto'
+        },
+        {
+          field: 'Order Date',
+          title: 'Order Date',
+          width: 'auto'
+        },
+        {
+          field: 'Quantity',
+          title: 'Quantity',
+          width: 'auto'
+        },
+        {
+          field: 'Sales',
+          title: 'Sales',
+          width: 'auto'
+        },
+        {
+          field: 'Profit',
+          title: 'Profit',
+          width: 'auto'
+        }
+      ];
+
+      const option = {
+        records: data.slice(0, 100),
+        columns,
+        widthMode: 'standard',
+        groupBy: ['Category', 'Sub-Category'],
+        theme: VTable.themes.DEFAULT.extends({
+          groupTitleStyle: {
+            fontWeight: 'bold',
+            // bgColor: '#3370ff'
+            bgColor: args => {
+              const { col, row, table } = args;
+              const index = table.getGroupTitleLevel(col, row);
+              if (index !== undefined) {
+                return titleColorPool[index % titleColorPool.length];
+              }
+            }
+          }
+        })
+      };
+      tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+      window.tableInstance = tableInstance;
+    })
+    .catch(e => {
+      console.error(e);
+    });
+```

docs/assets/demo/menu.json

@@ -79,6 +79,13 @@
             "en": "List Table Tree(lazy load)"
           }
         },
+        {
+          "path": "list-table-group",
+          "title": {
+            "zh": "基本表格分组展示",
+            "en": "List Table Group"
+          }
+        },
         {
           "path": "transpose-table",
           "title": {
@@ -1285,15 +1292,15 @@
         {
           "path": "table-export-ignore-icon",
           "title": {
-            "zh": "表格导出",
-            "en": "table export"
+            "zh": "表格导出（忽略图标）",
+            "en": "table export(ignore-icon)"
           }
         },
         {
           "path": "table-export-format",
           "title": {
-            "zh": "表格导出",
-            "en": "table export"
+            "zh": "表格导出（格式化）",
+            "en": "table export(format)"
           }
         }
       ]

docs/assets/demo/zh/table-type/list-table-group.md

@@ -0,0 +1,110 @@
+---
+category: examples
+group: table-type
+title: 基本表格分组展示
+cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/list-group.jpeg
+order: 1-2
+link: '../guide/table_type/List_table/group_list'
+option: ListTable#groupBy
+---
+
+# 基本表格分组展示
+
+基本表格分组展示，用于展示数据中分组字段的层级结构
+
+## 关键配置
+
+- groupBy: 指定分组字段名称
+
+## 代码演示
+
+```javascript livedemo template=vtable
+  const titleColorPool = ['#3370ff', '#34c724', '#ff9f1a', '#ff4050', '#1f2329'];
+  let tableInstance;
+  fetch('https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/North_American_Superstore_data.json')
+    .then(res => res.json())
+    .then(data => {
+      const columns = [
+        {
+          field: 'Order ID',
+          title: 'Order ID',
+          width: 'auto'
+        },
+        {
+          field: 'Customer ID',
+          title: 'Customer ID',
+          width: 'auto'
+        },
+        {
+          field: 'Product Name',
+          title: 'Product Name',
+          width: 'auto'
+        },
+        {
+          field: 'Category',
+          title: 'Category',
+          width: 'auto'
+        },
+        {
+          field: 'Sub-Category',
+          title: 'Sub-Category',
+          width: 'auto'
+        },
+        {
+          field: 'Region',
+          title: 'Region',
+          width: 'auto'
+        },
+        {
+          field: 'City',
+          title: 'City',
+          width: 'auto'
+        },
+        {
+          field: 'Order Date',
+          title: 'Order Date',
+          width: 'auto'
+        },
+        {
+          field: 'Quantity',
+          title: 'Quantity',
+          width: 'auto'
+        },
+        {
+          field: 'Sales',
+          title: 'Sales',
+          width: 'auto'
+        },
+        {
+          field: 'Profit',
+          title: 'Profit',
+          width: 'auto'
+        }
+      ];
+
+      const option = {
+        records: data.slice(0, 100),
+        columns,
+        widthMode: 'standard',
+        groupBy: ['Category', 'Sub-Category'],
+        theme: VTable.themes.DEFAULT.extends({
+          groupTitleStyle: {
+            fontWeight: 'bold',
+            // bgColor: '#3370ff'
+            bgColor: args => {
+              const { col, row, table } = args;
+              const index = table.getGroupTitleLevel(col, row);
+              if (index !== undefined) {
+                return titleColorPool[index % titleColorPool.length];
+              }
+            }
+          }
+        })
+      };
+      tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+      window.tableInstance = tableInstance;
+    })
+    .catch(e => {
+      console.error(e);
+    });
+```

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

@@ -0,0 +1,120 @@
+## Basic table grouping display
+
+In this tutorial, we will learn how to use the basic table grouping display function in VTable.
+
+## Usage scenario
+
+The basic table grouping display function is applicable to a variety of scenarios, such as:
+
+- Financial statements: You can group and display according to different account types (such as income, expenditure, assets, liabilities) to help you understand the financial situation more clearly.
+
+- Sales data analysis: You can group by product category, region, salesperson, etc., to facilitate comparison and analysis of sales performance in different categories or regions.
+
+- Project management: You can group by project stage, responsible team, priority, etc. to help better track and manage project progress.
+
+- Human resource management: You can group by department, position, years of work, etc. to facilitate employee management and performance evaluation.
+
+## Usage method
+
+In the option of ListTable, configure the `groupBy` field, the value is the grouping field name, you can configure a single field, or you can configure an array of multiple fields.
+```
+{
+  // ...
+  groupBy: 'key',
+}
+```
+或
+```
+{
+  // ...
+  groupBy: ['key1', 'key2'],
+}
+```
+## Example
+```javascript livedemo template=vtable
+const records = [
+   {
+      name: 'John Smith',
+      position: 'Recruiting Manager',
+      salary: '$8000',
+      group: 'Recruiting Group'
+    },
+    {
+      name: 'Emily Johnson',
+      position: 'Recruiting Supervisor',
+      salary: '$6000',
+      group: 'Recruiting Group'
+    },
+    {
+      name: 'Michael Davis',
+      position: 'Recruiting Specialist',
+      salary: '$4000',
+      group: 'Recruiting Group'
+    },
+    {
+      name: 'Jessica Brown',
+      position: 'Training Manager',
+      salary: '$8000',
+      group: 'Training Group',
+    },
+    {
+      name: 'Andrew Wilson',
+      position: 'Training Supervisor',
+      salary: '$6000',
+      group: 'Training Group',
+    }
+];
+const columns = [
+  {
+    field: 'name',
+    title: 'Name',
+    width: 'auto',
+  },
+  {
+    field: 'position',
+    title: 'Position',
+    width: 'auto',
+  },
+  {
+    field: 'salary',
+    title: 'Salary',
+    width: 'auto',
+  },
+];
+
+const option = {
+  records,
+  columns,
+  widthMode: 'standard',
+  groupBy: 'group'
+};
+const tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+window['tableInstance'] = tableInstance;
+```
+
+## Specify the display style of the group title
+
+In the theme, you can configure the groupTitleStyle property to specify the display style of the group title. If you need to specify the style of group titles at different levels, you can use the function to get the level of the current node through the `table.getGroupTitleLevel(col, row)` method to specify the styles of different levels.
+
+```ts
+const option: VTable.ListTableConstructorOptions = {
+  // ...
+  groupBy: ['Category', 'Sub-Category'],
+  theme: VTable.themes.DEFAULT.extends({
+    groupTitleStyle: {
+      fontWeight: 'bold',
+      bgColor: args => {
+        const { col, row, table } = args;
+        const index = table.getGroupTitleLevel(col, row); // Get the level of the current node
+        if (index !== undefined) {
+          return titleColorPool[index % titleColorPool.length];
+        }
+      }
+    }
+  })
+};
+```
+
+<div style="width: 80%; text-align: center;">
+  <img src="https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/list-group.jpeg" />
+</div>