通过

从自定义函数调用 Excel JavaScript API

  • 项目

从自定义函数调用 Excel JavaScript API 以获取范围数据并为计算获取更多上下文。 在以下情况下，通过自定义函数调用 Excel JavaScript API 可能会有所帮助：

  • 自定义函数需要在计算之前从 Excel 获取信息。 此信息可能包括文档属性、范围格式、自定义 XML 部件、工作簿名称或其他特定于 Excel 的信息。
  • 自定义函数将在计算后为返回值设置单元格的数字格式。

重要

若要从自定义函数调用 Excel JavaScript API，需要使用 共享运行时。 使用 Office 外接程序的 Yeoman 生成器 使用 共享运行时项目安装 Excel 自定义函数 ，或请参阅 将 Office 外接程序配置为使用共享运行时 了解详细信息。

代码示例

若要从自定义函数调用 Excel JavaScript API，首先需要上下文。 使用 Excel.RequestContext 对象获取上下文。 然后使用上下文调用工作簿中所需的 API。

下面的代码示例演示如何使用 Excel.RequestContext 从工作簿中的单元格获取值。 在此示例中， address 参数将传递到 Excel JavaScript API Worksheet.getRange 方法中，并且必须作为字符串输入。 例如，在 Excel UI 中输入的自定义函数必须遵循模式 =CONTOSO.GETRANGEVALUE("A1")，其中 "A1" 是要从中检索值的单元格的地址。

/**
 * @customfunction
 * @param {string} address The address of the cell from which to retrieve the value.
 * @returns The value of the cell at the input address.
 **/
async function getRangeValue(address) {
 // Retrieve the context object. 
 const context = new Excel.RequestContext();
 
 // Use the context object to access the cell at the input address. 
 const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
 range.load("values");
 await context.sync();
 
 // Return the value of the cell at the input address.
 return range.values[0][0];
}

通过自定义函数调用 Excel JavaScript API 的限制

自定义函数加载项可以调用 Excel JavaScript API，但应谨慎处理它调用的 API。 请勿从自定义函数调用 Excel JavaScript API，该函数会更改运行自定义函数的单元格外部的单元格。 更改其他单元格或 Excel 环境可能会导致 Excel 应用程序中性能不佳、超时和无限循环。 这意味着自定义函数不应执行以下任何操作：

  • 在电子表格中插入、删除单元格或设置单元格格式。
  • 更改另一个单元格的值。
  • 将工作表移动、重命名、删除或添加到工作簿。
  • 向工作簿添加名称。
  • 设置属性。
  • 更改任何 Excel 环境选项，例如计算模式或屏幕视图。

自定义函数加载项可以从运行自定义函数的单元格外部的单元格读取信息，但不应对其他单元格执行写入操作。 相反，请从功能区按钮或任务窗格的上下文对其他单元格或 Excel 环境进行更改。 此外，自定义函数计算不应在 Excel 重新计算时运行，因为此方案会创建不可预测的结果。

后续步骤

另请参阅