Office 外接程序 (Add-ins) 的 ExecuteFunction 命令变更

Posted 2022-05-17 Justin-Liu

Office Add-ins 长期以来一直支持自定义功能区按钮和菜单，称为插件命令。对于 Word、Excel、PowerPoint 和 Outlook，有两种方式：打开任务窗格的方式和调用 javascript 函数的方式。ExecuteFunction 命令即调用 JavaScript 函数的命令，我们在 JavaScript 文件中创建一个函数，然后在清单中通过名称标识该函数。JavaScript 文件由一个没有 UI 的 html 文件加载，通常称为 functionfile.html 或 commands.html。

为了提高 Office 外接程序的安全性，微软正在改变创建 ExecuteFunction 外接程序命令的方式。此更改不需要重新提交 Office 外接程序。

除了定义 JavaScript 函数之外，还需要通过调用

Office.actions.associate("name-of-function", function)

向 Office 注册该函数。

下面是一个示例

function writeText(event) 
    // Implement your custom code here. The following code is a simple example.   
    Office.context.document.setSelectedDataAsync("ExecuteFunction works. Button ID=" + event.source.id,
        function(asyncResult) 
            var error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) 
                // Show error message. 
             else 
                // Show success message. 
            
        );
    // Calling event.completed is required. event.completed lets the platform know that processing has completed. 
    event.completed();

// Register the function with the associate API 
Office.actions.associate("writeText", writeText);

重要提醒
这些变更必须在 2022 年 10 月 30 日前完成。从那一天起，ExecuteFunction 类型的外接程序命令中没有以这种方式注册的函数将不能再运行。请尽快更新您的 Office 外接程序，以避免影响外接程序的功能。

要测试是否正确注册了功能，可以模拟 Office 在 2022 年 10 月 30 日的行为。向 <script> 标记添加一个属性，该属性将加载 HTML 文件中的 Office JavaScript 库。示例如下：

[html]
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" data-use-associated-actions-only="1" type="text/javascript"></script>
[html]

当使用 data-use-associated-action-only 属性加载 Office JavaScript 库时，只有注册到关联 API 的外接命令才会运行。没有注册到关联 API 的任何外接程序命令将无法运行。

您可以在微软的 GitHub 库上找到完整的插件示例。要了解有关外接程序命令的更多信息，请参阅微软的 DOC 文档。

对于问题，大家可以参加微软每月的 Office 外接程序社区电话会议。最后，如果您遇到任何问题，请到 GitHub 上报告出来。

另附 Office 开发者中心 的链接