Fix/group by just one col not show title

common/changes/@visactor/vtable/fix-groupBy-justOneCol-notShowTitle_2026-03-06-11-34.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix: when just has only one column groupTitle not show\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

packages/vtable/examples/list/groupBy-oneCol.ts

@@ -0,0 +1,103 @@
+import * as VTable from '../../src';
+
+const ListTable = VTable.ListTable;
+const CONTAINER_ID = 'vTable';
+
+export function createTable() {
+  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',
+        groupConfig: {
+          groupBy: ['Category', 'Sub-Category'],
+          titleFieldFormat: (record, col, row, table) => {
+            return record.vtableMergeName + '(' + record.children.length + ')';
+          },
+          enableTreeStickCell: true
+        },
+        enableCheckboxCascade: true, // default is true
+        enableHeaderCheckboxCascade: true, // default is true
+        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);
+    });
+}

packages/vtable/examples/menu.ts

@@ -35,6 +35,10 @@ export const menus = [
   {
     menu: '基本表格',
     children: [
+      {
+        path: 'list',
+        name: 'groupBy-oneCol'
+      },
       {
         path: 'list',
         name: 'list'

packages/vtable/src/layout/cell-range/simple-cell-range.ts

@@ -123,18 +123,43 @@ function getTreeTitleMerge(col: number, row: number, cellRange: CellRange, layou
     return;
   }
 
-  const cellRecord = layout._table.getCellRawRecord(col, row);
-  if (layout._table.internalProps.groupTitleCheckbox && layout._table.internalProps.rowSeriesNumber) {
-    if (cellRecord?.vtableMerge && col >= layout.leftRowSeriesNumberColumnCount) {
-      cellRange.start.col = layout.rowHeaderLevelCount + layout.leftRowSeriesNumberColumnCount;
-      cellRange.end.col = layout.colCount - 1;
-      cellRange.start.row = cellRange.end.row = row;
-    }
+  const table: any = layout._table;
+  const internalProps = table.internalProps || {};
+  const isGroupMode = !!internalProps.groupBy;
+  const cellRecord = table.getCellRawRecord(col, row);
+
+  if (!cellRecord?.vtableMerge) {
+    return;
+  }
+
+  if (
+    internalProps.groupTitleCheckbox &&
+    internalProps.rowSeriesNumber &&
+    col >= layout.leftRowSeriesNumberColumnCount
+  ) {
+    cellRange.start.col = layout.rowHeaderLevelCount + layout.leftRowSeriesNumberColumnCount;
   } else {
-    if (cellRecord?.vtableMerge) {
-      cellRange.start.col = layout.rowHeaderLevelCount;
-      cellRange.end.col = layout.colCount - 1;
-      cellRange.start.row = cellRange.end.row = row;
+    cellRange.start.col = layout.rowHeaderLevelCount;
+  }
+  cellRange.end.col = layout.colCount - 1;
+  cellRange.start.row = cellRange.end.row = row;
+
+  // 特殊处理：分组模式下且仅有一列数据列时，分组标题行本质上仍应视为“整行合并”
+  // 为了在这种情况下正确展示分组标题文本（尤其是 vtableMerge/vtableMergeName 与 groupTitleFieldFormat），
+  // 这里在源记录上补充该单列对应字段的值，避免依赖多列合并逻辑。
+  if (isGroupMode && layout.columnObjects?.length === 1) {
+    const onlyColumn = layout.columnObjects[0];
+    const field = onlyColumn?.field;
+    if (field != null) {
+      let text = cellRecord.vtableMergeName;
+      const groupTitleFieldFormat = internalProps.groupTitleFieldFormat;
+      if (typeof groupTitleFieldFormat === 'function') {
+        text = groupTitleFieldFormat(cellRecord, col, row, table);
+      }
+      const current = (cellRecord as any)[field as any];
+      if (current == null && text != null) {
+        (cellRecord as any)[field as any] = text;
+      }
     }
   }
 }