使用 Excel JavaScript API 查找区域内的特殊单元格

使用 Excel JavaScript API 快速查找具有公式、常量、错误或其他特征的单元格，以便您可以有效地审核、重构或应用格式。 本文介绍如何使用 Range.getSpecialCells 和 Range.getSpecialCellsOrNullObject，何时选择每个，以及如何使用单元格值类型进一步缩小结果范围。 有关对象支持的完整属性和方法 Range 集，请参阅 Excel.Range 类。

快速参考

查找具有特殊单元格的区域

Range.getSpecialCells 和 Range.getSpecialCellsOrNullObject 方法根据单元格的特征及其单元格值类型查找区域。 这两种方法都返回 RangeAreas 对象。 以下是 TypeScript 数据类型文件中方法的签名：

getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

下面的代码示例使用 getSpecialCells 查找包含公式的所有单元格。 请注意：

• 通过先调用 worksheet.getUsedRange() 来限制搜索范围以提高性能。
• getSpecialCells 返回单个 RangeAreas 对象，因此可以在一个作中设置非连续匹配项的格式。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaRanges = usedRange.getSpecialCells(Excel.SpecialCellType.formulas);
    formulaRanges.format.fill.color = "pink";

    await context.sync();
});

如果区域中不存在具有目标特征的单元格，getSpecialCells 会引发 ItemNotFound错误。 这会将控制流转移到 catch 信息块（如果存在）。 如果没有 catch 块，则错误将停止方法。

如果你希望具有目标特征的单元格始终存在，则你可能想要代码在没有这些单元格的时候引发错误。 若没有匹配单元格是一个有效应用场景，代码应该会检查这种可能的情况并按正常方式处理它，而不会引发错误。 可以用此 getSpecialCellsOrNullObject 方法及其返回的 isNullObject 属性实现此行为。 下面的代码示例使用此模式。 关于此代码，请注意以下几点：

• 方法 getSpecialCellsOrNullObject 始终返回一个代理对象，因此它绝不 null 是普通 JavaScript 意义上的。 但是，如果没有找到匹配的单元格，则对象的 isNullObject 属性将设置为 true。
• 它会在测试 isNullObject 属性之前调用 context.sync 。 这是所有 *OrNullObject 方法和属性的要求，因为你必须始终加载和同步属性才能读取它。 但是，不需要 显式 加载 isNullObject 属性。 即使 load 未在 对象上调用 ，它也会由 context.sync 自动加载。 有关详细信息，请参阅 *OrNullObject 方法和属性。
• 你可以测试此代码，方法是先选择没有公式单元格的区域并运行它。 然后选择至少包含一个带公式的单元格的区域，并再次运行它。

await Excel.run(async (context) => {
    let range = context.workbook.getSelectedRange();
    let formulaRanges = range.getSpecialCellsOrNullObject(Excel.SpecialCellType.formulas);
    await context.sync();
        
    if (formulaRanges.isNullObject) {
        console.log("No cells have formulas");
    }
    else {
        formulaRanges.format.fill.color = "pink";
    }
    
    await context.sync();
});

为简单起见，本文中的其余示例使用 getSpecialCells。

通过单元格值类型缩小目标单元格的范围

Range.getSpecialCells() 和 Range.getSpecialCellsOrNullObject() 方法接受一个可选第二参数，用于进一步缩小目标单元格。 此第二参数是你用于指定只希望包含特定数值类型单元格的一个 Excel.SpecialCellValueType。

测试单个单元格值类型

Excel.SpecialCellValueType 枚举有四种基本类型 （本节后续部分所述其他组合值除外）：

• Excel.SpecialCellValueType.errors
• Excel.SpecialCellValueType.logical (，表示布尔)
• Excel.SpecialCellValueType.numbers
• Excel.SpecialCellValueType.text

下一个示例查找数值常量并将其着色为粉红色。

要点：

• 只有文本数值常量是针对 (计算结果为数字的公式，也不是布尔值、文本或错误单元格) 。
• 若要测试，请使用文本数字值、其他类型的文本值和公式填充工作表。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let constantNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.constants,
        Excel.SpecialCellValueType.numbers);
    constantNumberRanges.format.fill.color = "pink";

    await context.sync();
});

测试多个单元格值类型

有时需要对多个单元格值类型进行作，例如所有文本值和所有布尔值 () Excel.SpecialCellValueType.logical 单元格。 Excel.SpecialCellValueType 枚举具有组合类型的值。 例如， Excel.SpecialCellValueType.logicalText 面向所有布尔值单元格和所有文本值单元格。 Excel.SpecialCellValueType.all 是默认值，并不限制返回的单元格值类型。 以下代码示例使用生成数字或布尔值公式的所有单元格着色。

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let usedRange = sheet.getUsedRange();
    let formulaLogicalNumberRanges = usedRange.getSpecialCells(
        Excel.SpecialCellType.formulas,
        Excel.SpecialCellValueType.logicalNumbers);
    formulaLogicalNumberRanges.format.fill.color = "pink";

    await context.sync();
});

后续步骤

• 将特殊单元格查询与 字符串搜索 相结合，实现更丰富的审核。
• 将格式、注释或数据验证应用于生成的 RangeAreas 对象。

另请参阅

• Excel 加载项中的 Word JavaScript 对象模型
• 使用 Excel JavaScript API 处理单元格