自定义函数命名和本地化

本文提供命名自定义函数的指南和最佳做法，并说明如何本地化自定义函数。

自定义函数命名准则

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

id：代码中使用的唯一标识符。
name：向用户显示的显示名称。可以本地化它。

重要

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

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

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

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

注意

Microsoft 365 的统一清单目前不支持自定义函数项目。必须对自定义函数项目使用仅外接程序清单。有关详细信息，请参阅 Office 外接程序清单。

对于本地化，函数 name 可以不同于 id 。如果不需要本地化，最好对两者使用相同的值。

函数的 name 和 id 共享一些类似的规则。

两者都必须以字母开头，并且至少为三个字符。
id：仅允许使用 A-Z、0-9、下划线和句点字符。
name：允许使用任何 Unicode 字母字符、下划线和句点字符。

Excel 以大写字母 (显示内置函数名称， SUM 例如) 。对自定义函数使用大写，以帮助它们自然地融入其中。

避免使用匹配的名称：

单元格引用 (A1 到XFD1048576或 R1C1 到R1048576C16384) 。
Excel 4.0 宏函数 (，例如 RUN、 ECHO) 。有关这些函数的完整列表，请参阅此 Excel 宏函数参考文档。

命名冲突

如果函数 name 与另一个加载项中的函数冲突，Excel 将显示 #REF！ 错误。

通过重命名函数或卸载其他加载项来解决冲突。若要在多个环境中进行测试，请使用短命名空间前缀 (，例如 ADDINNAME_FUNCTIONNAME) 。

最佳做法

使用额外的函数参数，而不是创建多个类似的函数名称。例如， GETNAME(firstName, middleName, lastName) 比具有、和 GETLASTNAME等GETFIRSTNAMEGETMIDDLENAME单独函数更高效。
避免使用不清楚的缩写。例如， INCREASETIME 比 INC更易于理解。
为函数名称选择作谓词。使用 GETZIPCODE ，而不只是 ZIPCODE使用。
保持一致。对类似作（如 DELETEZIPCODE 和 DELETEADDRESS）使用相同的谓词。
对于流式处理函数，请将添加到 STREAM 名称或在说明中包含注释。
在函数名称中使用短供应商前缀，以避免与其他加载项冲突。例如，使用 CONTOSO_GETPRICE 或 CONTOSO_TAX_CALC。

提示

如果要跨多个环境测试加载项， (例如开发、过渡、演示等 ) ，我们建议为每个环境维护不同的清单文件。在每个清单文件中，可以：

指定与环境对应的 URL。
自定义元数据值，以便最终用户能够识别旁加载加载项的相应环境。例如：
- 在 Microsoft 365 的统一清单中，自定义 "name" 加载项的属性和 "label" 各种 UI 控件的属性以指示环境。
- 在仅外接程序清单中，自定义元素中的 DisplayNameResources 元素和和标签以指示环境。
如果加载项定义了自定义函数，则请自定义自定义函数 namespace 以指示环境。

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

命名约束快速参考

准则	`id`	`name`	注释
允许的字符	A–Z 0–9 `_.`	Unicode 字母字符 `_.`	保持 `id` 简单。本地化 `name`。
必须以字母开头	是	是	避免单元格引用混淆。
最小长度	3	3	短名称会降低清晰度。
大写格式	建议使用所有大写	建议使用所有大写	匹配 Excel 样式。
可本地化	否	是	保持 `id` 稳定。根据需要本地化 `name` 。
可以模拟单元格地址	否	否	防止地址分析错误。
保留的宏名称	禁止	禁止	一些示例： `RUN`、 `ECHO`。

本地化自定义函数

可以本地化加载项和自定义函数名称。在 JSON 文件中添加本地化的函数名称，并在仅外接程序清单中设置区域设置替代。

重要

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

本地化函数名称

若要本地化自定义函数，请为每种语言创建单独的 JSON 元数据文件。在每个文件中，添加 name 目标语言的和 description 属性。将 functions.json 用于英语，并在文件名中包含其他语言的区域设置，例如德语 的 functions-de.json 。

Excel 仅本地化 name 和 description 属性。 id未本地化，在设置后应保持不变。

重要

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 显示了德国) (的默认 en-us 区域设置和替代 JSON 文件 URL de-de 。

<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 外接程序本地化。

后续步骤

了解错误处理最佳做法。

另请参阅

反馈

此页面是否有帮助？

Last updated on 2025-10-31