使用 Excel JavaScript API 获取公式先例和依赖项

Excel 公式通常包含对同一工作表或工作簿中其他单元格的引用。 这些跨单元格引用称为“先例”和“从属引用”。 前例是向公式提供数据的单元格。 从属单元格是包含引用其他单元格的公式的单元格。 若要详细了解 Excel UI 中与先例和依赖项相关的功能(例如 跟踪先例跟踪依赖项),请参阅 显示公式和单元格之间的关系

一个前置单元格可能有其自己的前例单元格。 此先例链中的每个先例单元格仍然是原始单元格的先例。 依赖项存在相同的关系。 受另一个单元格影响的任何单元格都是该单元格的依赖项。 “直接先例”是此序列中的前一组单元格,类似于父子关系中的父级概念。 “直接依赖”是序列中的第一组单元格,类似于父子关系中的子级。

本文提供了使用 Excel JavaScript API 检索公式的先例和依赖项的代码示例。 有关对象支持的属性和方法 Range 的完整列表,请参阅 Range Object (JavaScript API for Excel)

获取公式的先例

使用 Range.getPrecedents 查找公式的前置单元格。 Range.getPrecedents 返回 对象 WorkbookRangeAreas 。 此对象包含工作簿中所有先例的地址。 它为每个工作表提供一个单独的 RangeAreas 对象,其中包含至少一个公式前例。 若要了解有关对象的详细信息 RangeAreas ,请参阅 在 Excel 外接程序中同时处理多个区域

若要仅查找公式的直接单元格,请使用 Range.getDirectPrecedentsRange.getDirectPrecedents 工作方式类似于 Range.getPrecedents ,并返回一个 WorkbookRangeAreas 对象,其中包含直接先例的地址。

以下屏幕截图显示了在 Excel UI 中选择 “跟踪先例 ”按钮的结果。 此按钮将箭头从前置单元格绘制到所选单元格。 所选单元格 E3 包含公式“=C3 * D3”,因此 C3D3 都是前置单元格。 与 Excel UI 按钮不同, getPrecedentsgetDirectPrecedents 方法不绘制箭头。

Excel UI 中的箭头跟踪前置单元格。

重要

getPrecedentsgetDirectPrecedents 方法不会跨工作簿检索前置单元格。

以下代码示例演示如何使用 Range.getPrecedentsRange.getDirectPrecedents 方法。 该示例获取活动区域的前例,然后更改这些单元格的背景色。 直接单元格的背景色设置为黄色,其他前置单元格的背景色设置为橙色。

// This code sample shows how to find and highlight the precedents 
// and direct precedents of the currently selected cell.
await Excel.run(async (context) => {
  let range = context.workbook.getActiveCell();
  // Precedents are all cells that provide data to the selected formula.
  let precedents = range.getPrecedents();
  // Direct precedents are the parent cells, or the first preceding group of cells that provide data to the selected formula.    
  let directPrecedents = range.getDirectPrecedents();

  range.load("address");
  precedents.areas.load("address");
  directPrecedents.areas.load("address");
  
  await context.sync();

  console.log(`All precedent cells of ${range.address}:`);
  
  // Use the precedents API to loop through all precedents of the active cell.
  for (let i = 0; i < precedents.areas.items.length; i++) {
    // Highlight and print out the address of all precedent cells.
    precedents.areas.items[i].format.fill.color = "Orange";
    console.log(`  ${precedents.areas.items[i].address}`);
  }

  console.log(`Direct precedent cells of ${range.address}:`);

  // Use the direct precedents API to loop through direct precedents of the active cell.
  for (let i = 0; i < directPrecedents.areas.items.length; i++) {
    // Highlight and print out the address of each direct precedent cell.
    directPrecedents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directPrecedents.areas.items[i].address}`);
  }
});

注意

Range.getPrecedents如果未找到任何单元格,和 Range.getDirectPrecedents 方法将返回ItemNotFound错误。

获取公式的依赖项

使用 Range.getDependents 查找公式的依赖单元格。 与 一样 Range.getPrecedentsRange.getDependents 也返回 对象 WorkbookRangeAreas 。 此对象包含工作簿中所有依赖项的地址。 每个工作表都有一个单独的 RangeAreas 对象,其中包含至少一个依赖于公式的。 有关使用 RangeAreas 对象的详细信息,请参阅 在 Excel 外接程序中同时处理多个区域

若要仅查找公式的直接依赖单元格,请使用 Range.getDirectDependentsRange.getDirectDependents 工作方式类似于 Range.getDependents ,并返回一个 WorkbookRangeAreas 对象,其中包含直接依赖项的地址。

以下屏幕截图显示了在 Excel UI 中选择“ 跟踪依赖项 ”按钮的结果。 此按钮将箭头从所选单元格绘制到依赖单元格。 所选单元格 D3 将单元格 E3 作为从属单元格。 E3 包含公式“=C3 * D3”。 与 Excel UI 按钮不同, getDependentsgetDirectDependents 方法不绘制箭头。

Excel UI 中的箭头跟踪依赖单元格。

重要

getDependentsgetDirectDependents 方法不会跨工作簿检索依赖单元格。

以下代码示例演示如何使用 Range.getDependentsRange.getDirectDependents 方法。 该示例获取活动区域的依赖项,然后更改这些依赖单元格的背景色。 直接依赖单元格的背景色设置为黄色,其他依赖单元格的背景色设置为橙色。

// This code sample shows how to find and highlight the dependents 
// and direct dependents of the currently selected cell.
await Excel.run(async (context) => {
    let range = context.workbook.getActiveCell();
    // Dependents are all cells that contain formulas that refer to other cells.
    let dependents = range.getDependents();  
    // Direct dependents are the child cells, or the first succeeding group of cells in a sequence of cells that refer to other cells.
    let directDependents = range.getDirectDependents();

    range.load("address");
    dependents.areas.load("address");    
    directDependents.areas.load("address");
    
    await context.sync();

    console.log(`All dependent cells of ${range.address}:`);
    
    // Use the dependents API to loop through all dependents of the active cell.
    for (let i = 0; i < dependents.areas.items.length; i++) {
      // Highlight and print out the addresses of all dependent cells.
      dependents.areas.items[i].format.fill.color = "Orange";
      console.log(`  ${dependents.areas.items[i].address}`);
    }

    console.log(`Direct dependent cells of ${range.address}:`);

    // Use the direct dependents API to loop through direct dependents of the active cell.
    for (let i = 0; i < directDependents.areas.items.length; i++) {
      // Highlight and print the address of each dependent cell.
      directDependents.areas.items[i].format.fill.color = "Yellow";
      console.log(`  ${directDependents.areas.items[i].address}`);
    }
});

注意

Range.getDependents如果未找到依赖单元格,和 Range.getDirectDependents 方法将返回ItemNotFound错误。

另请参阅