手动为自定义函数创建 JSON 元数据

项目
03/15/2023

如自定义函数概述文章中所述，自定义函数项目必须包含 JSON 元数据文件和脚本 (JavaScript 或 TypeScript) 文件才能注册函数，使其可供使用。当用户首次运行加载项时，将注册自定义函数，之后，所有工作簿中的同一用户都可以使用自定义函数。

重要

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

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

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

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

建议尽可能使用 JSON 自动生成，而不是创建自己的 JSON 文件。自动生成不太容易出现用户错误， yo office 基架文件已包含此内容。有关 JSDoc 标记和 JSON 自动生成过程的详细信息，请参阅自动生成自定义函数的 JSON 元数据。

但是，可以从头开始创建自定义函数项目。此过程要求你：

编写 JSON 文件。
检查清单文件是否已连接到 JSON 文件。
在脚本文件中关联函数 id 和 name 属性，以便注册函数。

下图说明了使用 yo office 基架文件和从头开始编写 JSON 之间的差异。

将 Yeoman 生成器用于 Office 加载项和编写自己的 JSON 之间的差异的图像。

注意

如果不对 Office 外接程序使用 Yeoman 生成器，请记得通过 <XML 清单文件中的“资源>”部分将清单连接到创建的 JSON 文件。

创作元数据并连接到清单

Create项目中的 JSON 文件，并提供有关其中函数的所有详细信息，例如函数的参数。有关函数属性的完整列表，请参阅以下元数据示例和元数据参考。

确保 XML 清单文件引用“资源>”部分中的< JSON 文件，类似于以下示例。

<Resources>
    <bt:Urls>
        <bt:Url id="JSON-URL" DefaultValue="https://subdomain.contoso.com/config/customfunctions.json"/>
        <bt:Url id="JS-URL" DefaultValue="https://subdomain.contoso.com/dist/win32/ship/index.win32.bundle"/>
            <bt:Url id="HTML-URL" DefaultValue="https://subdomain.contoso.com/index.html"/>
    </bt:Urls>
    <bt:ShortStrings>
        <bt:String id="namespace" DefaultValue="CONTOSO"/>
    </bt:ShortStrings>
</Resources>

JSON 元数据示例

以下示例介绍了定义自定义函数的加载项的 JSON 元数据文件的内容。此示例后面的部分提供了有关此 JSON 示例中各个属性的详细信息。

{
  "allowCustomDataForDataTypeAny": true,
  "allowErrorForDataTypeAny": true,
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      "description": "Add two numbers",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "type": "number",
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "first",
          "description": "first number to add",
          "type": "number",
          "dimensionality": "scalar"
        },
        {
          "name": "second",
          "description": "second number to add",
          "type": "number",
          "dimensionality": "scalar"
        }
      ]
    },
    {
      "id": "GETDAY",
      "name": "GETDAY",
      "description": "Get the day of the week",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": []
    },
    {
      "id": "INCREMENTVALUE",
      "name": "INCREMENTVALUE",
      "description": "Count up from zero",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "increment",
          "description": "the number to be added each time",
          "type": "number",
          "dimensionality": "scalar"
        }
      ],
      "options": {
        "stream": true,
        "cancelable": true
      }
    },
    {
      "id": "SECONDHIGHEST",
      "name": "SECONDHIGHEST",
      "description": "Get the second highest number from a range",
      "helpUrl": "http://www.contoso.com/help",
      "result": {
        "dimensionality": "scalar"
      },
      "parameters": [
        {
          "name": "range",
          "description": "the input range",
          "type": "number",
          "dimensionality": "matrix"
        }
      ]
    }
  ]
}

注意

OfficeDev/Excel-Custom-Functions GitHub 存储库的提交历史记录中提供了完整的示例 JSON 文件。由于项目已调整为自动生成 JSON，因此手写 JSON 的完整示例仅在项目的早期版本中可用。

元数据参考

allowCustomDataForDataTypeAny

属性 allowCustomDataForDataTypeAny 是布尔数据类型。将此值设置为 true 允许自定义函数接受数据类型作为参数并返回值。若要了解详细信息，请参阅自定义函数和数据类型。

注意

与其他大多数 JSON 元数据属性不同， allowCustomDataForDataTypeAny 是顶级属性，不包含任何子属性。有关如何设置此属性格式的示例，请参阅前面的 JSON 元数据代码示例。

allowErrorForDataTypeAny

属性 allowErrorForDataTypeAny 是布尔数据类型。将值设置为 true 允许自定义函数将错误作为输入值进行处理。当设置为 true时allowErrorForDataTypeAny，any类型为或 any[][] 的所有参数都可以接受错误作为输入值。默认值false为 allowErrorForDataTypeAny 。

注意

与其他 JSON 元数据属性不同， allowErrorForDataTypeAny 是顶级属性，不包含任何子属性。有关如何设置此属性格式的示例，请参阅前面的 JSON 元数据代码示例。

functions

functions 属性是自定义函数对象的一个数组。下表列出了每个对象的属性。

属性	数据类型	是否必需	说明
`description`	string	否	最终用户在 Excel 中看到的函数的说明。例如，将摄氏度值转换为华氏度。
`helpUrl`	string	否	提供有关函数的信息的 URL。（它显示在任务窗格中。）例如，`http://contoso.com/help/convertcelsiustofahrenheit.html`。
`id`	string	是	函数的唯一 ID。此 ID 只能包含字母数字字符和句点，设置后不应更改。
`name`	string	是	最终用户在 Excel 中看到的函数的名称。在 Excel 中，此函数名称以 XML 清单文件中指定的自定义函数命名空间为前缀。
`options`	object	否	使用户能够自定义 Excel 执行函数的方式和时间。有关详细信息，请参阅选项。
`parameters`	array	是	定义函数的输入参数的数组。有关详细信息，请参阅参数。
`result`	object	是	定义函数返回的信息类型的对象。有关详细信息，请参阅结果。

options

options 对象使用户能够自定义 Excel 执行函数的方式和时间。下表列出了 options 对象的属性。

属性	数据类型	是否必需	说明
`cancelable`	boolean	否默认值为 `false`。	如果为 `true`，则每次用户执行具有取消函数效果的操作时，Excel 都会调用 `CancelableInvocation` 处理程序；例如，手动触发重新计算或编辑函数引用的单元格。可取消函数通常仅用于返回单个结果并需要处理数据请求取消的异步函数。函数不能同时使用 `stream` 和 `cancelable` 属性。
`requiresAddress`	boolean	否默认值为 `false`。	如果 `true`为，则自定义函数可以访问调用它的单元格的地址。 `address`调用参数的属性包含调用自定义函数的单元格的地址。函数不能同时使用 `stream` 和 `requiresAddress` 属性。
`requiresParameterAddresses`	boolean	否默认值为 `false`。	如果 `true`为，则自定义函数可以访问函数的输入参数的地址。此属性必须与结果对象的属性结合使用`dimensionality`，并且`dimensionality`必须设置为 `matrix`。有关详细信息，请参阅检测参数的地址。
`stream`	boolean	否默认值为 `false`。	如果为 `true`，即使只调用一次，该函数也可能会重复输出到单元格。此选项对于快速变化的数据源（如股票价格）非常有用。函数不应存在 `return` 语句。相反，结果值作为回调函数的参数 `StreamingInvocation.setResult` 传递。有关详细信息，请参阅创建流式处理函数。
`volatile`	boolean	否默认值为 `false`。	如果 `true`为，则函数在每次 Excel 重新计算时重新计算，而不是仅在公式的依赖值已更改时重新计算。函数不能同时使用 `stream` 和 `volatile` 属性。 `stream`如果和 `volatile` 属性都设置为 `true`，则将忽略 volatile 属性。

参数

parameters 属性是参数对象的数组。下表列出了每个对象的属性。

属性	数据类型	是否必需	说明
`description`	string	否	参数的说明。这显示在 Excel 的 IntelliSense 中。
`dimensionality`	string	否	必须是 `scalar` (非数组值) 或 `matrix` (二维数组) 。
`name`	string	是	参数的名称。此名称显示在 Excel 的 IntelliSense 中。
`type`	string	否	参数的数据类型。可以是 `boolean`、 `number`、 `string`或 `any`，这允许使用前三种类型中的任何一种。如果未指定此属性，则数据类型默认为 `any`。
`optional`	boolean	否	如果为 `true`，则参数是可选的。
`repeating`	boolean	否	如果 `true`为，则从指定的数组填充参数。请注意，函数的所有重复参数按定义被视为可选参数。

result

result 对象定义函数返回的信息类型。下表列出了 result 对象的属性。

属性	数据类型	是否必需	说明
`dimensionality`	string	否	必须是 `scalar` (非数组值) 或 `matrix` (二维数组) 。
`type`	string	否	结果的数据类型。可以是 `boolean`、 `number`、 `string`或 `any` (，这允许使用前三种类型中的任何一种) 。如果未指定此属性，则数据类型默认为 `any`。

将函数名称与 JSON 元数据相关联

若要使函数正常工作，需要将函数的 id 属性与 JavaScript 实现相关联。请确保存在关联，否则该函数不会注册，并且无法在 Excel 中使用。下面的代码示例演示如何使用 CustomFunctions.associate() 函数进行关联。该示例定义了自定义函数 add，并将其与 JSON 元数据文件中的对象关联，其中 id 属性的值为 ADD。

/**
 * Add two numbers
 * @customfunction
 * @param {number} first First number
 * @param {number} second Second number
 * @returns {number} The sum of the two numbers.
 */
function add(first, second) {
  return first + second;
}

CustomFunctions.associate("ADD", add);

以下 JSON 显示与以前的自定义函数 JavaScript 代码关联的 JSON 元数据。

{
  "functions": [
    {
      "description": "Add two numbers",
      "id": "ADD",
      "name": "ADD",
      "parameters": [
        {
          "description": "First number",
          "name": "first",
          "type": "number"
        },
        {
          "description": "Second number",
          "name": "second",
          "type": "number"
        }
      ],
      "result": {
        "type": "number"
      }
    }
  ]
}

在 JavaScript 文件中创建自定义函数和在 JSON 元数据文件中指定相应信息时，请记住以下最佳实践。

在 JSON 元数据文件中，确保每个 id 属性的值仅包含字母数字字符和句点。
在 JSON 元数据文件中，确保每个 id 属性的值在该文件范围内是唯一的。也就是说，元数据文件中不应存在具有相同 id 值的两个函数对象。
在将 JSON 元数据文件中的 id 属性的值与相应的 JavaScript 函数名称关联后，请勿再更改该值。你可以通过更新 JSON 元数据文件中的 name 属性来更改最终用户在 Excel 中看到的函数名称，但绝不能更改已确定的 id 属性的值。
在 JavaScript 文件中，在每个函数后面使用 CustomFunctions.associate 指定自定义函数关联。

以下示例显示与前面的 JavaScript 代码示例中定义的函数对应的 JSON 元数据。 id和 name 属性值以大写形式，这是描述自定义函数时的最佳做法。仅当手动准备自己的 JSON 文件而不使用自动生成时，才需要添加此 JSON。有关自动生成的详细信息，请参阅自动生成自定义函数的 JSON 元数据。

{
  "$schema": "https://developer.microsoft.com/json-schemas/office-js/custom-functions.schema.json",
  "functions": [
    {
      "id": "ADD",
      "name": "ADD",
      ...
    },
    {
      "id": "INCREMENT",
      "name": "INCREMENT",
      ...
    }
  ]
}

后续步骤

了解命名函数的最佳做法，或了解如何使用前面所述的手写 JSON 方法本地化函数。