查找 Google 表格中的所有复选框

Question

自从 2018 年将复选框添加到原生 Google Sheets UI 以来，开发人员一直希望以编程方式读取它们或以某种方式处理它们，例如将它们视为“单选按钮”、将它们重置为“未选中”或将它们设置为“检查过”。

我们如何才能最好地在给定的 Google Sheet 中找到复选框，以便避免在操作其他单元格的状态时意外修改它们？

一种方法是检查工作表上的值并将任何true/false值视为复选框：

function getAllCheckboxes() {
  const wb = SpreadsheetApp.getActive();
  const checkboxes = [];

  wb.getSheets().forEach(function (sheet) {
    var rg = sheet.getDataRange();
    var values = rg.getValues();
    var sheetCheckBoxes = [];

    values.forEach(function (row, r) {
      row.forEach(function (val, c) {
        // Checkbox values are stored as `false` (unchecked) and `true` (checked)
        if (val === false || val === true) {
          sheetCheckBoxes.push({
            rowIndex: r,
            colIndex: c,
            value: val,
            r1c1: "R" + (r+1) + "C" + (c+1)
          });
        }
      });
    });
    if (sheetCheckBoxes.length) {
      checkboxes.push({
        name: sheet.getName(),
        sheetId: sheet.getSheetId(),
        boxes: sheetCheckBoxes
      });
    }
  });

  return checkboxes; // An array of objects describing a sheet and its checkboxes.
}

但是，这并不适用于所有用例：单元格可能显示为文字TRUE或FALSE，而不是显示为复选框。上面的代码将把它视为一个，因为它共享相同的值。

Answer 1

复选框在 Google 表格应用程序中作为特定类型的数据验证实现，并且可以具有用户指定的“选中”和“未选中”值，而不仅仅是true和false。因此，为了正确查找复选框单元格，我们必须检查应用于每个单元格的数据验证类型。这可以通过两种方式在 Google Apps 脚本中完成：使用电子表格服务或使用 Google Sheets API (v4)。

电子表格服务

电子表格服务方法不需要您启用任何其他符号标识符或启用 Google Cloud Platform 中的任何 API。但是，在某些情况下，它可能不如 Sheets API 快。

该脚本与问题中的脚本非常相似，不同之处在于我们必须迭代 2D 数据验证规则数组，而不是值数组。（如果我们不需要复选框的当前值，我们可以跳过获取数组values。）

function getAllCheckboxesViaService() {
  const wb = SpreadsheetApp.getActive();
  const checkboxes = [];
  // The specific type of Data Validation that demarcates a UI checkbox.
  const CB = SpreadsheetApp.DataValidationCriteria.CHECKBOX;

  wb.getSheets().forEach(function (sheet) {
    var rg = sheet.getDataRange();
    var values = rg.getValues();
    var sheetCheckBoxes = [];

    var dvRules = rg.getDataValidations();
    dvRules.forEach(function (row, r) { // iterate data validations instead of values
      row.forEach(function (rule, c) {
        if (rule && rule.getCriteriaType() === CB) {
          sheetCheckBoxes.push({
            rowIndex: r,
            colIndex: c,
            r1c1: "R" + (r+1) + "C" + (c+1),
            choices: (rule.getCriteriaValues().length ? rule.getCriteriaValues() : [true, false]),
            value: values[r][c],
          });
        }
      });
    });
    if (sheetCheckBoxes.length) {
      checkboxes.push({
        name: sheet.getName(),
        sheetId: sheet.getSheetId(),
        boxes: sheetCheckBoxes
      });
    }
  });

  return checkboxes;
}

表格API

要使用 Sheets API，必须首先在应用程序的 Google Cloud Platform 项目中启用它。对于 Apps 脚本项目，其中之一会自动创建，并可从 Apps 脚本编辑器的“资源”菜单进行访问。如果您不确定如何激活符号和 Sheets REST API，请查看高级服务指南。Sheets

spreadsheets.get当fields部分响应掩码包含时，数据验证通过端点检索sheets/data/rowData/values/dataValidation。一般来说，仅仅这个特定字段是没有用的——知道关联工作表的标题、ID，也许还有复选框的值也很有用，因此更有用的fields规范是sheets(data(rowData(values(dataValidation,effectiveValue/boolValue))),properties(sheetId,title)). （您可以在Google API Explorer中尝试有效的字段掩码）

Sheets API 中的相关数据验证类型是BOOLEAN。我们可以通过 API 查询所需的电子表格一次，然后在本地检查生成的响应数据以确定哪些单元格具有复选框，哪些单元格没有：

function getAllCheckboxesViaAPI() {
  const wbId = SpreadsheetApp.getActive().getId();
  const fields = "sheets(data/rowData/values("
        + "dataValidation(condition(type,values/userEnteredValue)),"
        + "effectiveValue(boolValue,numberValue,stringValue)),"
      + "properties(sheetId,title))";
  const resp = Sheets.Spreadsheets.get(wbId, {fields: fields}); // Enable before use...
  if (!resp.sheets || !resp.sheets.length)
    return [];

  const checkboxes = [];
  resp.sheets.forEach(function (sheetObj) {
    if (!sheetObj.data || !sheetObj.data.length)
      return;
    var sheetCheckBoxes = [];
    sheetObj.data.forEach(function (gridRange) {
      gridRange.rowData.forEach(function (row, r) {
        row.values.forEach(function (cell, c) {
          if (cell.dataValidation && cell.dataValidation.condition
              // Require the cell to be displayed as a Checkbox.
              && cell.dataValidation.condition.type === "BOOLEAN")
          {
            sheetCheckBoxes.push({
              rowIndex: r,
              colIndex: c,
              r1c1: "R" + (r+1) + "C" + (c+1),
              choices: (cell.dataValidation.condition.values ?
                  cell.dataValidation.condition.values : [true, false]),
              value: cell.effectiveValue // object, e.g. {booleanValue: false} or {stringValue: "Yes"}
            });
          }
        });
      });
    });
    checkboxes.push({
      name: sheetObj.properties.title,
      sheetId: sheetObj.properties.sheetId,
      boxes: sheetCheckBoxes
    });
  });

  return checkboxes;
}

有效地使用复选框位置

一旦知道电子表格中的哪些单元格对应于复选框 - 以及哪些值显示为“选中”与“未选中” - 很自然地想要读取或修改它们。盲目写入true或false到复选框单元格仅对默认值（布尔值）有效复选框。要处理所有可能的用户创建的复选框，您必须编写表示“选中”或“未选中”的适当值。（上述脚本将这些值存储在属性中choices。）

重置值最容易在 Apps 脚本中使用类完成RangeList，尽管 Sheets API 端点spreadsheets.values.batchUpdate可以实现类似的结果（是的，R1C1 表示法对于 Sheets APIValueRange规范是可接受的），尽管需要一些样板来构造请求。API 方法能够发出单个请求，而电子表格服务只能在每个工作表中实例化一个请求（并且您需要为每种类型的复选框RangeList创建 1 个，以避免写入不正确的值（例如，当“未选中”值应该是））。RangeListfalse"No"

function getSpecificCBType(checkboxData, checkedVal, uncheckedVal) {
  const desiredCBs = checkboxData.filter(function (sheetObj) {
    return sheetObj.boxes.some(function (checkbox) {
      return checkbox.choices[0] === checkedVal && checkbox.choices[1] === uncheckedVal;
    });
  }).reduce(function (acc, sheetObj) {
    var desiredSheetCBs = sheetObj.boxes.filter(function (checkbox) {
      return checkbox.choices[0] === checkedVal && checkbox.choices[1] === uncheckedVal;
    });
    if (desiredSheetCBs.length) {
      acc.push({
        name: sheetObj.name,
        sheetId: sheetObj.sheetId,
        boxes: desiredSheetCBs
      });
    }
    return acc;
  }, []);
  return desiredCBs;
}


function resetSomeCBsViaService() {
  const allCBs = /* method from above */;
  const checkedValue = true;
  const uncheckedValue = false;
  const someCBs = getSpecificCBType(allCBs, checkedValue, uncheckedValue);    
  const wb = SpreadsheetApp.getActive();

  // Set to checked, using a RangeList (could use Sheets API values#batchUpdate).
  someCBs.forEach(function (sheetObj) {
    wb.getSheetByName(sheetObj.name)
      .getRangeList(sheetObj.boxes.map(function (checkbox) { return checkbox.r1c1; }))
      .setValue(checkedValue);
  });
}

要从 构建 API 请求someCBs，类似这样的内容就足够了：

function resetSomeCBsViaAPI() {
  const allCBs = /* method from above */;
  const checkedValue = true;
  const uncheckedValue = false;
  const someCBs = getSpecificCBType(allCBs, checkedValue, uncheckedValue);    
  const wbId = SpreadsheetApp.getActive().getId();

  const rq = someCBs.reduce(function (rqb, sheetObj) {
    var valueRanges = sheetObj.boxes.map(function (checkbox) {
      return {
        range: "'" + sheetObj.name + "'!" + checkbox.r1c1,
        values: [ [checkedValue] ]
      };
    });
    Array.prototype.push.apply(rqb.data, valueRanges);
    return rqb;
  }, {valueInputOption: "USER_ENTERED", data: []});

  Sheets.Spreadsheets.Values.batchUpdate(rq, wbId);
}