FunctionFile 元素

指定外接程序通过以下方式之一公开的操作的源代码文件。

• 执行 JavaScript 函数而不是显示 UI 的外接程序命令。
• 执行 JavaScript 函数的键盘快捷方式。

加载项类型： 任务窗格，邮件

仅在以下 VersionOverrides 架构中有效：

• 任务窗格 1.0
• 邮件 1.0
• 邮件 1.1

有关详细信息，请参阅 清单中的版本替代。

<FunctionFile> 元素是 DesktopFormFactor 或 MobileFormFactor 的子元素。 residFunctionFile> 元素的< 属性不能超过 32 个字符，并且设置为 Resources 元素中 Url> 元素的 属性值<id，该元素包含 HTML 文件的 URL，该文件包含或加载函数命令按钮使用的所有 JavaScript 函数，如 Control 元素所定义。

注意

当外接程序配置为使用 共享运行时时，代码文件中的函数在相同的 JavaScript 运行时 (中运行，并共享一个通用的全局命名空间) 作为加载项任务窗格中的 JavaScript (（如果有) ）。

<FunctionFile> 元素和关联的代码文件还具有使用自定义键盘快捷方式的特殊作用，这需要共享运行时。

下面是 FunctionFile> 元素的示例<。

<DesktopFormFactor>
  <FunctionFile resid="Commands.Url" />
  <ExtensionPoint xsi:type="PrimaryCommandSurface">
    <!-- Information about this extension point. -->
  </ExtensionPoint>

  <!-- You can define more than one ExtensionPoint element as needed. -->
</DesktopFormFactor>

...

<Resources>
    <bt:Urls>
        <bt:Url id="Commands.Url" DefaultValue="https://www.contoso.com/commands.html" />
    </bt:Urls>

    <!-- Define other resources as needed. -->
</Resources>

FunctionFile> 元素指示的 HTML 文件中的< JavaScript 必须初始化 Office.js 并定义采用单个参数的命名函数：事件。 执行完之后，它还应调用 event.completed。 Outlook 加载项中的函数应使用 通知 API 向用户指示进度、成功或失败。 函数的名称用于函数命令按钮的 FunctionName 元素中。

可以在 HTML 文件加载的 <单独 JavaScript 文件中定义和注册 FunctionName> 元素指定的函数。 下面是此类文件的示例。

// Initialize the Office Add-in.
Office.onReady(() => {
  // If needed, Office.js is ready to be called
});

// The command function.
async function highlightSelection(event) {

    // Implement your custom code here. The following code is a simple Excel example.  
    try {
          await Excel.run(async (context) => {
              const range = context.workbook.getSelectedRange();
              range.format.fill.color = "yellow";
              await context.sync();
          });
      } catch (error) {
          // Note: In a production add-in, notify the user through your add-in's UI.
          console.error(error);
      }

    // Calling event.completed is required. event.completed lets the platform know that processing has completed.
    event.completed();
}

// You must register the function with the following line.
Office.actions.associate("highlightSelection", highlightSelection);

重要

对 event.completed 的调用表示已成功处理事件。 当某个函数被多次调用时（例如在同一外接程序命令上进行多次单击），所有事件将自动排队。 第一个事件将自动运行，而其他事件仍保持在队列中。 当函数调用 event.completed时，将运行对该函数的下一个排队调用。 必须调用 event.completed;否则函数将不会运行。