加载项命令

项目
10/16/2024

外接程序命令是 UI 元素，可扩展 Office UI，并在外接程序中启动操作。使用外接程序命令，可以在功能区上添加按钮，也可以向上下文菜单添加项。当用户选择外接程序命令时，将启动操作，如运行 JavaScript 代码或在任务窗格中显示外接程序页面。外接程序命令可帮助用户查找和使用外接程序，从而提高外接程序的采用率和重用率以及客户保留率。

注意

SharePoint 目录不支持外接程序命令。可以通过集中部署或 AppSource 部署加载项命令，也可以使用旁加载部署加载项命令以供测试。
内容加载项暂不支持加载项命令。

加载项命令的类型

根据命令触发的操作类型，有两种类型的加载项命令。

任务窗格命令：按钮或菜单项将打开加载项的任务窗格。在清单中添加带有标记的此类加载项命令。 “代码隐藏”命令由 Office 提供。
函数命令：按钮或菜单项运行任意 JavaScript。代码几乎总是在 Office JavaScript 库中调用 API，但并非必须如此。此类型的加载项通常不显示按钮或菜单项本身以外的 UI。请注意以下有关函数命令的内容：
- 触发的函数可以调用 displayDialogAsync 方法来显示对话框，这是显示错误、显示进度或提示用户输入的好方法。如果外接程序配置为使用共享运行时，则函数还可以调用 showAsTaskpane 方法。
- 运行函数命令的运行时是完全基于浏览器的运行时。它可以呈现 HTML 并调用 Internet 以发送或获取数据。

加载项命令的位置

当用户安装外接程序时，其命令的位置取决于应用程序、平台和上下文。加载项命令位于功能区、默认或自定义选项卡或操作栏上， (仅适用于某些 Outlook 平台) 。它们在 UI 中显示为下拉菜单中的按钮或项。

对于功能区上显示的外接程序命令，如果使用简化的功能区布局，将从应用栏中删除加载项名称。只保留功能区上的外接程序命令按钮。

随着功能区或操作栏越来越拥挤，加载项命令会显示在溢出菜单中。同一加载项的命令通常组合在一起。

Excel、PowerPoint 和 Word

默认选项卡取决于应用程序和上下文。对于 Excel、PowerPoint 和 Word，默认选项卡为“开始”。

Excel 功能区中突出显示的示例外接程序命令。

Outlook

对于 Outlook，外接程序命令的默认位置基于平台和当前 Outlook 模式。有关指导，请参阅在 Outlook 中使用加载项。

下拉菜单加载项命令定义静态的项目列表。菜单可以是执行函数或打开任务窗格的任何项组合。不支持子项。

命令功能

目前支持下列命令功能。

扩展点

功能区选项卡 - 扩展内置选项卡或创建新的自定义选项卡。加载项只能有一个自定义选项卡。
上下文菜单 - 扩展所选上下文菜单。

控件类型

简单按钮 - 触发特定操作。
菜单 - 简单的下拉菜单，内含可触发操作的按钮。

默认启用或禁用状态

可指定在加载项启动时是启用还是禁用该命令，并以编程方式更改设置。

注意

并非所有 Office 应用程序或方案都支持此功能。有关详细信息，请参阅启用和禁用加载项命令。

功能区上的位置（预览）

可以指定自定义选项卡在 Office 应用程序功能区上的显示位置，例如“在“主页”选项卡右侧”。

注意

并非所有 Office 应用程序或方案都支持此功能。有关详细信息，请参阅在功能区上定位自定义选项卡。

内置 Office 按钮集成

可将内置 Office 功能区按钮插入到自定义命令组和自定义功能区选项卡中。

注意

并非所有 Office 应用程序或方案都支持此功能。有关详细信息，请参阅将内置 Office 按钮集成到自定义选项卡中。

上下文选项卡

可指定一个选项卡在某些情况下只在功能区中可见，例如在Excel中选择图表时。

注意

并非所有 Office 应用程序或方案都支持此功能。更多信息，请参见在Office插件中创建自定义上下文选项卡。

支持的平台

目前，以下平台支持加载项命令，但先前命令功能的小节中指定的限制除外。

Office 网页版
Windows (版本 1604 (内部版本 6769.2000) 或更高版本的 Office，已连接到 Microsoft 365 订阅)
Office on Mac (版本 15.33 (17040900) 或更高版本，已连接到 Microsoft 365 订阅)
Windows 或 Mac 上的永久 Office 2019 或更高版本

注意

有关 Outlook 中的支持的信息，请参阅 Outlook 支持说明。

调试

若要调试外接程序命令，必须在 Office web 版中运行它。有关详细信息，请参阅在 Office 网页版中调试加载项。

最佳做法

在开发外接程序命令时应用下面的最佳做法。

使用命令来表示会给用户带来明确具体结果的特定操作。不要在单个按钮中组合多个操作。
提供使您的外接程序中的常见任务执行效率更高的具体操作。尽量减少完成一个操作的步骤。
关于命令在 Office 应用功能区中的位置：
- 将命令放在现有选项卡上 (插入、审阅等) 提供的功能是否适合该选项卡。例如，如果外接程序允许用户插入媒体，请将组添加到“插入”选项卡。请注意，并非所有选项卡都可用于所有 Office 版本。有关详细信息，请参阅 Office 外接程序清单。
- 如果功能不适合其他选项卡，并且你拥有少于 6 个的顶级命令，将命令放置在“开始”选项卡上。如果你的外接程序需要跨 Office 版本 (（例如Office web 版或桌面) ）工作，并且选项卡并非在所有版本中都可用， (例如，Office web 版) 中不存在“设计”选项卡，则还可以向“开始”选项卡添加命令。
- 如果你拥有 6 个以上的顶级命令命令，将命令放置在自定义选项卡上。
- 对组进行命名以与外接程序的名称相匹配。如果你拥有多个组，则基于对应组中的命令提供的功能为每个组命名。
- 不要添加不必要的按钮来增加加载项的空间。
- 不要将自定义选项卡置于“开始”选项卡的左侧，或在文档打开时默认为其指定焦点，除非加载项是用户与文档交互的主要方式。过分强调加载项的不便，并惹恼用户和管理员。
- 如果加载项是用户与文档进行交互的主要方式，而且你具有自定义的功能区选项卡，请考虑将用户经常需要的 Office 功能按钮集成到该选项卡中。
- 如果自定义选项卡提供的功能应仅在某些上下文中可用，请使用自定义上下文选项卡。如果使用自定义上下文选项卡，请确保在插件运行在不支持自定义上下文标签的平台上时，实行后退体验。
注意

占用过多空间的加载项可能无法通过 AppSource 验证。
对于所有图标，请遵循图标设计准则。
提供在 Office 应用程序或平台 (（如不支持命令的 iPad) ）上运行的外接程序版本。单个加载项清单可用于这些版本。

后续步骤

加载项命令的最佳入门方式是参照 GitHub 上的 Office 加载项命令示例。

有关在仅外接程序清单中指定外接程序命令的详细信息，请参阅使用仅外接程序清单创建外接程序命令和 VersionOverrides 引用内容。

有关在 Microsoft 365 的统一清单中指定外接程序命令的详细信息，请参阅使用 Microsoft 365 的统一清单创建外接程序命令。

通过