在 Excel 中创建自定义函数

  • 项目

开发人员可以借助自定义函数向 Excel 添加新函数，方法是在 JavaScript 中将这些函数定义为加载项的一部分。 Excel 中的用户可以访问自定义函数，就像他们访问 Excel 中的任何本机函数一样，比如 SUM()。

注意

自定义函数 是一个通用术语，可与 用户定义的函数互换。 这两个术语都适用于 VBA、COM 和 Office.js 加载项。Office 加载项文档在引用使用 Office JavaScript API 的自定义 函数时使用 术语自定义函数。

重要

请注意，以下平台上可以使用 Excel 自定义函数。

  • Office 网页版
  • Windows 版 Office
    • Microsoft 365 订阅
    • 零售永久 Office 2016 及更高版本
    • 批量许可永久Office 2021及更高版本
  • Mac 版 Office

以下各项当前不支持 Excel 自定义函数：

  • iPad 版 Office
  • Windows 上 Office 2019 或更早版本的批量许可永久版本

以下动态图像显示调用你使用 JavaScript 或 TypeScript 创建的函数的工作簿。 在此示例中，自定义函数 =MYFUNCTION.SPHEREVOLUME 计算球的体积。

显示最终用户插入 MYFUNCTION 的动画图像。将 SPHEREVOLUME 自定义函数放入 Excel 工作表的单元格中。

以下代码定义 =MYFUNCTION.SPHEREVOLUME 自定义函数。

/**
 * Returns the volume of a sphere.
 * @customfunction
 * @param {number} radius
 */
function sphereVolume(radius) {
  return Math.pow(radius, 3) * 4 * Math.PI / 3;
}

如何在代码中定义自定义函数

如果使用 适用于 Office 加载项的 Yeoman 生成器 创建 Excel 自定义函数加载项项目，则它可创建控制函数和任务窗格的文件。 我们将专注于对自定义函数至关重要的文件。

文件 文件格式 说明
./src/functions/functions.js
或
./src/functions/functions.ts		 JavaScript
或
TypeScript		 包含定义自定义函数的代码。
./src/functions/functions.html HTML 提供对定义自定义函数的 JavaScript 文件的<脚本>引用。
./manifest.xml XML 指定自定义函数使用的多个文件的位置，例如自定义函数 JavaScript、JSON 和 HTML 文件。 它还列出了任务窗格文件、命令文件的位置，并指定自定义函数应使用的运行时。

提示

Office 加载项的 Yeoman 生成器提供了多个 Excel 自定义函数 项目。 建议 使用共享运行时选择项目类型“Excel 自定义函数 ”和脚本类型 “JavaScript”。

脚本文件

脚本文件 (./src/functions/functions.js or ./src/functions/functions.ts) 包含定义自定义函数的代码以及定义函数的注释。

以下代码定义 add 自定义函数。 代码注释用于生成描述 Excel 自定义函数的 JSON 元数据。 首先声明所需的 @customfunction 注释，指示这是一个自定义函数。 接下来，声明两个参数 first 和 second，然后是它们的 description 属性。 最后提供了 returns 描述。 要详细了解自定义函数需要哪些注释，请参阅为自定义函数创建 JSON 元数据。

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number.
 * @param second Second number.
 * @returns The sum of the two numbers.
 */

function add(first, second){
  return first + second;
}

清单文件

用于定义自定义函数的加载项的 XML 清单文件（适用于 Office 的 Yeoman 生成器 创建的项目中的 ./manifest.xml）会执行以下操作。

  • 定义自定义函数的命名空间。 命名空间追加在你的自定义函数之前，可帮助客户将你的函数标识为加载项的一部分。
  • 使用自定义函数清单唯一的 ExtensionPoint> 和 Resources 元素。<>< 这些元素包含有关 JavaScript、JSON 和 HTML 文件的位置的信息。
  • 指定要用于自定义函数的运行时。 除非你对另一运行时有特殊需求，否则建议始终使用共享运行时，因为共享运行时允许在函数和任务窗格之间共享数据。

要从示例加载项中查看完整的工作清单，请参阅 我们的 Office 加载项示例 Github 存储库之一 中的清单。

提示

如果将要跨多个环境（例如，在开发、暂存、演示等中）测试外接程序，建议为每个环境维护不同的 XML 清单文件。 在每个清单文件中，可以：

  • 指定与环境对应的 URL。
  • 自定义元数据值，如 DisplayName 以及 Resources 中的标签，以指示环境，以便最终用户将能够识别旁加载加载项的相应环境。
  • 如果加载项定义了自定义函数，则请自定义自定义函数 namespace 以指示环境。

通过按照本指南操作，你将简化测试过程，并避免在为多个环境同时旁加载加载项时出现的问题。

共同创作

利用连接到 Microsoft 365 订阅的 Excel 网页版和 Windows 版 Excel，最终用户可以在 Excel 中共同创作。 如果最终用户的工作簿使用自定义函数，系统将提示该最终用户的共同创作同事加载相应的自定义函数加载项。 当两个用户均加载此加载项后，自定义函数将通过共同创作共享结果。

若要详细了解共同创作，请参阅关于 Excel 中的共同创作。

后续步骤

想要试用自定义函数？ 检查简单的自定义函数入门或更深入的自定义函数教程（如果还没有）。

另一个尝试自定义函数的简单方法就是使用脚本实验室，这是一个允许您在 Excel 中试验自定义函数的加载项。 可以尝试创建自己的自定义函数或使用提供的示例。

另请参阅