Merge pull request #4983 from VisActor/feat/batch_cell_values&filterApi

Feat/batch cell values&filter api

Author: fangsmile

common/changes/@visactor/vtable/4871-bug-prepareEdit_2026-01-07-08-16.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix: prepareEdit occor error #4871\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

common/changes/@visactor/vtable/feat-search-latency-optimize_2026-01-08-03-16.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat: optimize search latency\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "liuhualin@bytedance.com"
+}

common/changes/@visactor/vtable/feat-support_cell_values_change_2026-01-07-06-52.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat(table): 新增基于记录索引的单元格值修改方法及优化范围删除性能\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "zhanghao.gino@bytedance.com"
+}

common/changes/@visactor/vtable/feat-support_cell_values_change_2026-01-12-07-50.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat(数据操作): 添加syncRecordOperationsToSourceRecords选项支持同步操作到源数据\n\n添加syncRecordOperationsToSourceRecords配置选项，当设置为true时，表格的增删改操作会同步到原始records数组\n修改DataSource类实现源数据同步逻辑，包括添加、删除和更新记录时对原始数据的处理\n添加相关测试用例验证同步功能\n在示例中添加同步选项的UI控制\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "zhanghao.gino@bytedance.com"
+}

common/changes/@visactor/vtable/feat-support_cell_values_change_2026-01-12-12-44.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix(vtable): 修复过滤状态下新增记录位置错误问题\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "zhanghao.gino@bytedance.com"
+}

common/changes/@visactor/vtable/feat-support_cell_values_change_2026-01-29-08-35.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat: 新增批量修改单元格值接口及优化筛选态数据同步\n\nrefactor: 重命名 changeCellValuesByIds 为 changeCellValuesByRanges\nfeat: 新增批量修改离散选区单元格值的接口 changeCellValuesByRanges\nfeat: 增加 syncRecordOperationsToSourceRecords 配置支持筛选态数据同步\nfeat: 新增 CHANGE_CELL_VALUES 聚合事件及相关文档\ndocs: 更新接口文档和指南说明新增功能\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "zhanghao.gino@bytedance.com"
+}

docs/assets/api/en/event/event.md

@@ -594,6 +594,31 @@ Parameter types of event callback function:
 { col: number; row: number; rawValue: string | number; currentValue: string | number; changedValue: string | number };
 ```
 
+## CHANGE_CELL_VALUES
+
+Batch cell value change event (aggregated).
+
+Parameter types of event callback function:
+
+```
+{
+  values: Array<{
+    col: number;
+    row: number;
+    recordIndex?: number | number[];
+    field?: string | number;
+    rawValue: string | number;
+    currentValue: string | number;
+    changedValue: string | number;
+  }>;
+};
+```
+
+**Notes:**
+
+- This event may be suppressed by the `noTriggerChangeCellValuesEvent` parameter in relevant APIs.
+- When multiple cells are updated in batch, the event will be fired once with an aggregated `values` list.
+
 ## CHECKBOX_STATE_CHANGE
 
 Change the checkbox state. **ListTable table exclusive event**

docs/assets/api/en/methods.md

@@ -1708,8 +1708,43 @@ Change the value of the cell:
    * @param value Changed value
    * @param workOnEditableCell Whether to only change editable cells
    * @param triggerEvent Whether to trigger change_cell_value event when the value changes
+   * @param noTriggerChangeCellValuesEvent Whether to suppress the aggregated change_cell_values event
    */
-  changeCellValue: (col: number, row: number, value: string | number | null, workOnEditableCell = false, triggerEvent = true) => void;
+  changeCellValue: (
+    col: number,
+    row: number,
+    value: string | number | null,
+    workOnEditableCell = false,
+    triggerEvent = true,
+    noTriggerChangeCellValuesEvent?: boolean
+  ) => void;
+```
+
+## changeCellValuesByRanges(Function)
+
+Batch update data within multiple selected ranges.
+
+Currently it only supports setting all cells in the ranges to the same value.
+
+**ListTable specific**
+
+```
+  /**
+   * Batch update data within multiple selected ranges.
+   * Currently it only supports setting all cells in the ranges to the same value.
+   * @param ranges Selected ranges
+   * @param value The unified value to set
+   * @param workOnEditableCell Whether to only change editable cells
+   * @param triggerEvent Whether to trigger change_cell_value/change_cell_values events
+   * @param noTriggerChangeCellValuesEvent Whether to suppress the aggregated change_cell_values event
+   */
+  changeCellValuesByRanges: (
+    ranges: CellRange[],
+    value: string | number | null,
+    workOnEditableCell?: boolean,
+    triggerEvent?: boolean,
+    noTriggerChangeCellValuesEvent?: boolean
+  ) => void;
 ```
 
 ## changeCellValues(Function)
@@ -1724,8 +1759,111 @@ Batch change the values of cells:
    * @param values Data array for multiple cells
    * @param workOnEditableCell Whether to only change editable cells
    * @param triggerEvent Whether to trigger change_cell_value event when values change
+   * @param noTriggerChangeCellValuesEvent Whether to suppress the aggregated change_cell_values event
+   */
+  changeCellValues: (
+    startCol: number,
+    startRow: number,
+    values: string[][],
+    workOnEditableCell?: boolean,
+    triggerEvent?: boolean,
+    noTriggerChangeCellValuesEvent?: boolean
+  ) => Promise<boolean[][]>;
+```
+
+## changeCellValueByRecord(Function)
+
+Change cell value by `recordIndex` (source records index) and `field`.
+
+**ListTable specific**
+
+```
+  /**
+   * Change cell value by recordIndex (source records index) and field.
+   * recordIndex is the index in the original source records: number for normal tables; number[] for tree tables.
+   */
+  changeCellValueByRecord: (
+    recordIndex: number | number[],
+    field: FieldDef,
+    value: string | number | null,
+    options?: {
+      triggerEvent?: boolean;
+      noTriggerChangeCellValuesEvent?: boolean;
+      autoRefresh?: boolean;
+    }
+  ) => void;
+```
+
+## changeCellValuesByRecords(Function)
+
+Batch change cell values by `recordIndex` (source records index) and `field`.
+
+**ListTable specific**
+
+```
+  /**
+   * Batch change cell values by recordIndex (source records index) and field.
    */
-  changeCellValues(startCol: number, startRow: number, values: string[][], workOnEditableCell = false, triggerEvent=true) => Promise<boolean[][]>;
+  changeCellValuesByRecords: (
+    changeValues: Array<{
+      recordIndex: number | number[];
+      field: FieldDef;
+      value: string | number | null;
+    }>,
+    options?: {
+      triggerEvent?: boolean;
+      noTriggerChangeCellValuesEvent?: boolean;
+      autoRefresh?: boolean;
+    }
+  ) => void;
+```
+
+## changeCellValueBySource(Function)
+
+Alias of `changeCellValueByRecord` with positional parameters.
+
+**ListTable specific**
+
+```
+  changeCellValueBySource: (
+    recordIndex: number | number[],
+    field: FieldDef,
+    value: string | number | null,
+    triggerEvent?: boolean,
+    noTriggerChangeCellValuesEvent?: boolean
+  ) => void;
+```
+
+## changeCellValuesBySource(Function)
+
+Alias of `changeCellValuesByRecords` with positional parameters.
+
+**ListTable specific**
+
+```
+  changeCellValuesBySource: (
+    changeValues: Array<{
+      recordIndex: number | number[];
+      field: FieldDef;
+      value: string | number | null;
+    }>,
+    triggerEvent?: boolean,
+    noTriggerChangeCellValuesEvent?: boolean
+  ) => void;
+```
+
+## refreshAfterSourceChange(Function)
+
+Refresh the table after directly changing source records (optionally reapply filter/sort).
+
+**ListTable specific**
+
+```
+  refreshAfterSourceChange: (options?: {
+    reapplyFilter?: boolean;
+    reapplySort?: boolean;
+    clearRowHeightCache?: boolean;
+  }) => void;
 ```
 
 ## getEditor(Function)
@@ -1791,6 +1929,10 @@ Add data, supports multiple data items
   addRecords(records: any[], recordIndex?: number|number[])
 ```
 
+**Notes:**
+
+- If `syncRecordOperationsToSourceRecords` is enabled, add operations in filter/sort state will also sync to the original `records` (source records).
+
 ## addRecord(Function)
 
 Add data, single data item
@@ -1808,6 +1950,10 @@ Add data, single data item
   addRecord(record: any, recordIndex?: number|number[])
 ```
 
+**Notes:**
+
+- If `syncRecordOperationsToSourceRecords` is enabled, add operations in filter/sort state will also sync to the original `records` (source records).
+
 ## deleteRecords(Function)
 
 Delete data, supports multiple data items
@@ -2364,4 +2510,4 @@ Update the content of a range of cells. This interface only refreshes the conten
    * Update the content of a range of cells
    */
   updateCellContentRanges: (ranges: CellRange[]) => void;
-```
+```

docs/assets/api/zh/event/event.md

@@ -629,6 +629,31 @@ MousePointerCellEvent & { axisPosition: 'left' | 'right' | 'top' | 'bottom' };
 
 ```
 
+## CHANGE_CELL_VALUES
+
+批量更改单元格值的聚合事件。
+
+事件回调函数的参数类型:
+
+```
+{
+  values: Array<{
+    col: number;
+    row: number;
+    recordIndex?: number | number[];
+    field?: string | number;
+    rawValue: string | number;
+    currentValue: string | number;
+    changedValue: string | number;
+  }>;
+};
+```
+
+**说明：**
+
+- 相关接口参数 `noTriggerChangeCellValuesEvent` 可用于抑制该聚合事件。
+- 批量更新多个单元格时通常只触发一次该事件，`values` 中包含所有变更项。
+
 ## CHECKBOX_STATE_CHANGE
 
 更改 checkbox 复选框状态。**ListTable 表格专有事件**