Merge pull request #3237 from VisActor/feat-custom-merge-config

feat: customMergeCell support array config #3202

Author: Rui-Sun

common/changes/@visactor/vtable/feat-custom-merge-config_2024-12-30-11-28.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@visactor/vtable",
+      "comment": "feat: customMergeCell support array config #3202",
+      "type": "none"
+    }
+  ],
+  "packageName": "@visactor/vtable"
+}

docs/assets/guide/en/basic_function/merge_cell.md

@@ -111,6 +111,8 @@ In VTable, you can configure `customMergeCell` to customize the merging method o
 * range: merged range
 * style: style of merged cells
 
+`customMergeCell` can also be configured as an array of merge rules. Each item in the array is a merge rule. The configuration of the rule is the same as the return value of the `customMergeCell` callback function.
+
 ### Example
 
 ```javascript livedemo template=vtable

docs/assets/guide/zh/basic_function/merge_cell.md

@@ -106,11 +106,13 @@ window['tableInstance'] = tableInstance;
 
 ## 自定义单元格合并
 
-在VTable中，可以配置`customMergeCell`自定义单元格的合并方式，这种方式常用来显示一些标注信息。其中`customMergeCell`回调函数会传入行列号和表格实例，在函数中判断需要合并的单元格，并返回相应的合并规则：
+在VTable中，可以配置`customMergeCell`自定义单元格的合并方式，这种方式常用来显示一些标注信息。其中`customMergeCell`可以配置回调函数会传入行列号和表格实例，在函数中判断需要合并的单元格，并返回相应的合并规则：
 * text: 合并单元格内的文字
 * range: 合并的范围
 * style: 合并单元格的样式
 
+`customMergeCell`也可以配置为合并规则的数组，数组中的每一项为一个合并规则，规则的配置与`customMergeCell`回调函数的返回值相同。
+
 ### 示例
 
 ```javascript livedemo template=vtable

docs/assets/option/en/common/option-secondary.md

@@ -444,7 +444,7 @@ Table scrolling behavior, can be set: 'auto'|'none', the default value is 'auto'
 'none': don't triggers the browser's default behavior when the table scrolls to the top or bottom;
 ```
 
-#${prefix} customMergeCell(Function)
+#${prefix} customMergeCell(Function|Object)
 Customize cell merging rules. When the incoming row and column numbers are within the target area, the merging rules are returned:
 
 - text: Merge text in cells
@@ -476,6 +476,8 @@ Customize cell merging rules. When the incoming row and column numbers are withi
 
 ```
 
+`customMergeCell` can also be configured as an array of merge rules. Each item in the array is a merge rule. The configuration of the rule is the same as the return value of the `customMergeCell` callback function.
+
 #${prefix} customCellStyle(Array)
 
 ```

docs/assets/option/zh/common/option-secondary.md

@@ -472,6 +472,8 @@ html 目前实现较完整，先默认使用 html 渲染方式。目前暂不支
 
 ```
 
+`customMergeCell`也可以配置为合并规则的数组，数组中的每一项为一个合并规则，规则的配置与`customMergeCell`回调函数的返回值相同。
+
 #${prefix} customCellStyle(Array)
 
 ```

packages/vtable/src/core/BaseTable.ts

@@ -152,6 +152,7 @@ import type { ITableAnimationOption } from '../ts-types/animation/appear';
 import { checkCellInSelect } from '../state/common/check-in-select';
 import type { CustomCellStylePlugin, ICustomCellStylePlugin } from '../plugins/custom-cell-style';
 import { isCellDisableSelect } from '../state/select/is-cell-select-highlight';
+import { getCustomMergeCellFunc } from './utils/get-custom-merge-cell-func';
 import { vglobal } from '@src/vrender';
 
 const { toBoxArray } = utilStyle;
@@ -508,7 +509,7 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
 
     internalProps.stick = { changedCells: new Map() };
 
-    internalProps.customMergeCell = options.customMergeCell;
+    internalProps.customMergeCell = getCustomMergeCellFunc(options.customMergeCell);
 
     const CustomCellStylePlugin = Factory.getComponent('customCellStylePlugin') as ICustomCellStylePlugin;
     if (CustomCellStylePlugin) {
@@ -2473,7 +2474,7 @@ export abstract class BaseTable extends EventTarget implements BaseTableAPI {
     this.clearColWidthCache();
     this.clearRowHeightCache();
 
-    internalProps.customMergeCell = options.customMergeCell;
+    internalProps.customMergeCell = getCustomMergeCellFunc(options.customMergeCell);
 
     this.customCellStylePlugin?.updateCustomCell(
       options.customCellStyle ?? [],

packages/vtable/src/core/utils/get-custom-merge-cell-func.ts

@@ -0,0 +1,21 @@
+import { isArray, isFunction } from '@visactor/vutils';
+import type { CustomMergeCell } from '../../ts-types';
+
+export function getCustomMergeCellFunc(customMergeCell?: CustomMergeCell) {
+  if (isFunction(customMergeCell)) {
+    return customMergeCell;
+  }
+  if (isArray(customMergeCell)) {
+    return (col: number, row: number) => {
+      return customMergeCell.find(item => {
+        return (
+          item.range.start.col <= col &&
+          item.range.end.col >= col &&
+          item.range.start.row <= row &&
+          item.range.end.row >= row
+        );
+      });
+    };
+  }
+  return undefined;
+}

packages/vtable/src/ts-types/base-table.ts

@@ -72,7 +72,8 @@ import type {
   ColumnInfo,
   RowInfo,
   CellAddressWithBound,
-  Placement
+  Placement,
+  CustomMergeCellFunc
 } from '.';
 import type { TooltipOptions } from './tooltip';
 import type { IWrapTextGraphicAttribute } from '../scenegraph/graphic/text';
@@ -256,7 +257,7 @@ export interface IBaseTableProtected {
 
   stick: { changedCells: Map<string, StickCell> };
 
-  customMergeCell?: CustomMergeCell;
+  customMergeCell?: CustomMergeCellFunc;
   /**
    * 'auto':和浏览器滚动行为一致 表格滚动到顶部/底部时 触发浏览器默认行为;
    *  设置为 'none' 时, 表格滚动到顶部/底部时, 不再触发父容器滚动

packages/vtable/src/ts-types/table-engine.ts

@@ -603,7 +603,10 @@ export interface IExtensionRowDefine {
 
 export type StickCell = { col: number; row: number; dx: number; dy: number };
 
-export type CustomMergeCell = (col: number, row: number, table: BaseTableAPI) => undefined | CustomMerge;
+export type CustomMergeCell = CustomMergeCellFunc | CustomMergeCellArray;
+
+export type CustomMergeCellFunc = (col: number, row: number, table: BaseTableAPI) => undefined | CustomMerge;
+export type CustomMergeCellArray = CustomMerge[];
 export type CustomMerge = {
   range: CellRange;
   text?: string;