Элемент FunctionFile

Указывает файл исходного кода для операций, которые надстройка предоставляет одним из следующих способов.

• Команды надстроек, которые выполняют функцию JavaScript вместо отображения пользовательского интерфейса.
• Сочетания клавиш, которые выполняют функцию JavaScript.

Тип надстройки: Область задач, почта

Допустимо только в следующих схемах VersionOverrides:

• Область задач 1.0
• Почта 1.0
• Почта 1.1

Дополнительные сведения см. в разделе Переопределения версий в манифесте только надстройки.

Элемент <FunctionFile> является дочерним элементом DesktopFormFactor или MobileFormFactor. Атрибут resid<элемента FunctionFile> может содержать не более 32 символов и имеет значение id атрибута <элемента Url> в элементе Resources , который содержит URL-адрес HTML-файла, который содержит или загружает все функции 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>

JavaScript в HTML-файле, указанном элементом <FunctionFile> , должен инициализировать Office.js и определить именованные функции, которые принимают один параметр: event. Он также должен вызывать event.completed после выполнения. Функции надстроек Outlook должны использовать API-интерфейсы уведомлений , чтобы сообщить пользователю о ходе выполнения, успешном выполнении или неудаче. Имена функций используются в элементе FunctionName для кнопок команд функции.

Вы можете определить и зарегистрировать функцию, указанную элементом <FunctionName> , в отдельном файле JavaScript, который загружается HTML-файлом. Ниже приведен пример такого файла.

// 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; в противном случае функция не будет выполняться.