自定义函数命名和本地化

本文介绍有关命名自定义函数的准则和最佳做法。 它还演示如何将自定义函数名称本地化为英语以外的语言。

自定义函数命名准则

自定义函数由 id JSON 元数据文件中的 和 name 属性标识。

• 函数 id 用于唯一标识 JavaScript 代码中的自定义函数。
• name函数用作在 Excel 中向用户显示的显示名称。

重要

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

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

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

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

函数 name 可以不同于 函数 id，例如出于本地化目的。 通常，如果函数没有 name 理由不同，则函数的 应与 保持相同 id 。

函数的 name 和 id 共享一些常见要求。

• 函数的 id 只能使用字符 A 到 Z、数字 0 到 9、下划线和句点。

• 函数的 name 可以使用任何 Unicode 字母字符、下划线和句点。

• 函数 name 和 id 都必须以字母开头，并且最小限制为三个字符。

Excel 对内置函数名称使用大写字母 (，例如 SUM) 。 将大写字母用于自定义函数的 name 和 id 作为最佳做法。

函数的 name 不应与以下函数相同：

• A1 到 XFD1048576 之间的任意单元格，或 R1C1 到 R1048576C16384 之间的任意单元格。

• 任何 Excel 4.0 宏函数 (，例如 RUN、 ECHO) 。 有关这些函数的完整列表，请参阅 此 Excel 宏函数参考文档。

命名冲突

如果函数 name 与加载项中已存在的函数 name 相同，则工作簿中将显示 #REF！ 错误。

若要解决命名冲突，请更改 name 外接程序中的 ，然后重试该函数。 还可以卸载具有冲突名称的加载项。 或者，如果要在不同的环境中测试加载项，请尝试使用不同的命名空间来区分函数 (，例如 NAMESPACE_NAMEOFFUNCTION) 。

最佳做法

• 请考虑向一个函数添加多个参数，而不是创建具有相同或相似名称的多个函数。
• 避免在函数名称中使用不明确的缩写。 Clarity比简洁更重要。 选择类似于 =INCREASETIME 的名称，而不是 =INC。
• 函数名称应指示函数的操作，例如 =GETZIPCODE 而不是 ZIPCODE。
• 对于执行类似操作的函数，始终使用相同的谓词。 例如，使用 =DELETEZIPCODE 和 =DELETEADDRESS，而不是 =DELETEZIPCODE 和 =REMOVEADDRESS。
• 命名流式处理函数时，请考虑在函数的说明中添加该效果的注释，或者在函数名称的末尾添加 STREAM 注释。

提示

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

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

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

本地化自定义函数

可以本地化加载项和自定义函数名称。 为此，请在函数的 JSON 文件中提供本地化的函数名称，并在 XML 清单文件中提供区域设置信息。

重要

自动生成的元数据不适用于本地化，因此需要手动更新 JSON 文件。 若要了解如何执行此操作，请参阅 手动为自定义函数创建 JSON 元数据。

本地化函数名称

若要本地化自定义函数，请为每种语言创建新的 JSON 元数据文件。 在每个语言 JSON 文件中，使用目标语言添加 name 和 description 属性。 英语的默认文件名为 functions.json。 对每个附加的 JSON 文件（如 functions-de.json ）使用文件名中的区域设置来帮助识别它们。

name和 description 显示在 Excel 中，并已本地化。 但是， id 每个函数的 未本地化。 属性 id 是 Excel 将函数标识为唯一且在设置函数后不应更改的方式。

重要

避免为函数 id 提供其他语言的内置 Excel 函数的 或 name ，因为此函数与本地化函数冲突。

以下 JSON 演示如何使用 id 属性“MULTIPLY”定义函数。 name函数的 和 description 属性针对德语进行了本地化。 每个参数 name 和 description 也针对德语进行了本地化。

{
    "id": "MULTIPLY",
    "name": "SUMME",
    "description": "Summe zwei Zahlen",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "eins",
            "description": "Erste Nummer",
            "dimensionality": "scalar"
        },
        {
            "name": "zwei",
            "description": "Zweite Nummer",
            "dimensionality": "scalar"
        },
    ],
}

将上一个 JSON 与以下用于英语的 JSON 进行比较。

{
    "id": "MULTIPLY",
    "name": "Multiply",
    "description": "Multiplies two numbers",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "one",
            "description": "first number",
            "dimensionality": "scalar"
        },
        {
            "name": "two",
            "description": "second number",
            "dimensionality": "scalar"
        },
    ],
}

本地化加载项

为每种语言创建 JSON 文件后，为每个区域设置使用替代值更新 XML 清单文件，该值指定每个 JSON 元数据文件的 URL。 以下清单 XML 显示了一个默认 en-us 区域设置，其中包含 (Germany) 的替代 JSON 文件 URL de-de 。 functions-de.json 文件包含本地化的德语函数名称和 ID。

<DefaultLocale>en-us</DefaultLocale>
...
<Resources>
     <bt:Urls>
        <bt:Url id="Contoso.Functions.Metadata.Url" DefaultValue="https://localhost:3000/dist/functions.json"/>
          <bt:Override Locale="de-de" Value="https://localhost:3000/dist/functions-de.json" />
        </bt:url>
        
     </bt:Urls>
</Resources>

有关加载项本地化过程的详细信息，请参阅 Office 外接程序本地化。

后续步骤

了解 错误处理最佳做法。

另请参阅

• 手动为自定义函数创建 JSON 元数据
• Excel 自定义函数教程