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

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

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

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

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

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

创作元数据并连接到清单

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

确保外接程序仅清单文件引用 节中的 <Resources> 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": "GETPLANETS", 
      "name": "GETPLANETS", 
      "description": "A function that uses the custom enum as a parameter.", 
      "parameters": [ 
        { 
          "name": "value", 
          "type": "string", 
          "customEnumType": "PLANETS" 
        }
      ]
    }
  ],
  "enums": [ 
    { 
      "id": "PLANETS", 
      "type": "string", 
      "values": [ 
        { 
          "name": "Mercury", 
          "value": "mercury", 
          "tooltip": "Mercury is the first planet from the sun." 
        }, 
        { 
          "name": "Venus", 
          "value": "venus", 
          "tooltip": "Venus is the second planet from the sun." 
        }
      ] 
    }
  ]
}

元数据参考

allowCustomDataForDataTypeAny

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

如果自定义函数使用 cellValueType参数，则无需设置 allowCustomDataForDataTypeAny 即可接受数据类型作为参数并返回值。

allowErrorForDataTypeAny

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

functions

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

enums

属性 enums 是 枚举 对象的数组。 下表列出了每个对象的属性。

options

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

参数

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

"parameters": [
    {
        "name": "range",
        "description": "the input range",
        "type": "any",
            "cellValueType": "webimagecellvalue"
    }
]

result

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

将函数名称与 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 元数据中的自定义枚举

直接使用 enums 属性创建或编辑枚举元数据。 每个自定义枚举必须具有唯一的 ID 值和类型值或 stringnumber。 不支持混合类型枚举。

如果手动为自定义枚举创建 JSON 元数据，则可以将这些枚举与 TypeScript 或 JavaScript 自定义函数相关联。 若要详细了解如何创建自定义枚举，请参阅 创建自定义函数的自定义枚举。

以下 JSON 代码片段显示了两个枚举的元数据：一个枚举，一个 PLANETS 包含水星和金星行星，一个包含星期一 DAYS 和星期二的枚举。

"enums": [ 
  { 
    "id": "PLANETS", 
    "type": "string", 
    "values": [ 
      { 
        "name": "Mercury", 
        "value": "mercury", 
        "tooltip": "Mercury is the first planet from the sun." 
      }, 
      { 
        "name": "Venus", 
        "value": "venus", 
        "tooltip": "Venus is the second planet from the sun." 
      }
    ] 
  },
  {
    "id": "DAYS", 
    "type": "number", 
    "values": [ 
      { 
        "name": "Monday",
        "value": 1,
        "tooltip": "Monday is the first working day of a week."
      },
      { 
        "name": "Tuesday",
        "value": 2,
        "tooltip": "Tuesday is the second working day of a week."
      }
    ] 
  }
]

枚举数组中的每个 values 常量都是具有以下属性的 对象。

• value：常量的值。
• name：常量的简要说明。
• 工具提示 (可选) ：有关可在用户界面中显示为工具提示的常量的其他信息。

若要将自定义枚举与函数相关联，请将 属性 customEnumType 添加到 parameters 对象。 该值 customEnumType 应与枚举的 匹配 id 。 请注意， customEnumType 该值不区分大小写。 以下 JSON 代码片段显示与 functions 枚举关联的 PLANETS 对象。

"functions": [ 
  {
    "description": "A function that uses the custom enum as a parameter.", 
    "id": "GETPLANETS", 
    "name": "GETPLANETS", 
    "parameters": [ 
      { 
        "name": "value", 
        "type": "string", 
        "customEnumType": "PLANETS" 
      }
    ], 
    "result": {} 
  } 
]

后续步骤

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

另请参阅

• 为自定义函数自动生成 JSON 元数据
• 自定义函数参数选项
• 在 Excel 中创建自定义函数