如何在Google Sheets脚本中正确调用UpdateCellsRequest批量更新单元格

完全可以在Google Apps Script对接Google Sheets的单次API调用中，批量完成多个独立单元格的背景色设置、粗体/斜体字体格式调整、单元格备注写入操作，这也是解决大量逐单元格操作触发执行超时问题的官方推荐优化方案。

原代码的错误点 #

你的现有写法不符合Sheets API v4的请求规范，存在4个会直接导致执行失败的问题：

• start字段层级错误：该字段是updateCells对象的内部属性，不应与updateCells平级放置
• 缺少必填的fields参数：updateCells请求必须明确声明需要更新的字段范围，未声明的字段不会被修改，缺失该参数时请求会被API直接拒绝
• 调用方法错误：不存在SpreadsheetApp.UpdateCellsRequest()这个内置方法，批量更新需要通过高级Sheets服务的batchUpdate接口发起
• 索引类型错误：从字符串拆分得到的行、列值为字符串类型，直接传入会导致API解析索引时出现偏移，需要提前转为整数类型

修正后的可运行代码 #

// 全局变量提前初始化，和你原有数据结构对齐
let jobs = [];
const merge_store = {};
const lookup = {};

function createBatchMerge(){
  // 清空上一次执行残留的任务
  jobs = [];
  for (const target_name in merge_store){
    const sheet = lookup[target_name];
    const sheetId = sheet.getSheetId();
    const instructions = merge_store[target_name];
    for (const cellc in instructions){
      const instruction = instructions[cellc];
      // 拆分坐标后转成整数，避免索引解析错误
      const [row, col] = cellc.split(':').map(Number);
      // 按API规范构造更新请求
      const request = {
        updateCells: {
          start: {
            sheetId: sheetId,
            rowIndex: row + 1, // 保留你原有的行偏移逻辑
            columnIndex: col
          },
          rows: [
            {
              values: [
                {
                  userEnteredFormat: {
                    backgroundColor: instruction.colour,
                    textFormat: {
                      italic: instruction.italic,
                      bold: instruction.bold
                    }
                  },
                  note: instruction.names.join(',')
                }
              ]
            }
          ],
          // 必填：声明本次要更新的字段范围
          fields: "userEnteredFormat.backgroundColor,userEnteredFormat.textFormat.italic,userEnteredFormat.textFormat.bold,note"
        }
      };
      jobs.push(request);
    }
  }
}

function dumpMerge(){
  if (jobs.length === 0) {
    createBatchMerge();
  }
  // 单次批量提交所有更新任务
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  Sheets.Spreadsheets.batchUpdate({requests: jobs}, ss.getId());
}

使用注意事项 #

• 首次使用前需要打开脚本编辑器，在左侧「服务」栏点击「添加服务」，选择Google Sheets API并添加，否则批量调用方法会报未定义错误
• 单次batchUpdate请求最多支持提交1000个更新请求，如果总更新单元格数超过1000，可将任务数组按每1000条为一组拆分后多次提交，执行效率依然比逐单元格调用内置格式设置方法高90%以上
• 脚本部署完成后，所有拥有表格编辑权限的协作者，新增、修改图形数据后直接运行脚本即可完成全量合并更新

内容的提问来源于stack exchange，提问作者Mark Lester