Настройка надстройки Office для использования общей среды выполнения

  • Статья

Важно!

Общая среда выполнения поддерживается только в некоторых приложениях Office. Дополнительные сведения см. в статье Наборы обязательных элементов общей среды выполнения.

Вы можете настроить надстройку Office для выполнения всего кода в одной общей среде выполнения. Это позволяет повысить слаженность работы всей вашей надстройки и обеспечить доступ к DOM и CORS из всех ее частей. Кроме того, это позволяет использовать дополнительные функции, например запуск кода при открытии документа, а также включение и отключение кнопок ленты. Чтобы настроить надстройку для использования общей среды выполнения, следуйте инструкциям, приведенным в этой статье.

Создание проекта надстройки

Если вы начинаете новый проект, используйте генератор Yeoman для настроек Office, чтобы создать проект надстройки Excel, PowerPoint или Word.

Запустите команду yo office --projectType taskpane --name "my office add in" --host <host> --js true, где <host> имеет одно из следующих значений.

  • excel
  • powerpoint
  • word

Важно!

Значение аргумента --name должно быть указано в двойных кавычках, даже если оно не содержит пробелов.

Вы можете использовать различные параметры для параметров командной строки --projecttype, --name и --js. Полный список вариантов см. в статье Генератор Yeoman для надстроек Office.

Генератор создаст проект и установит вспомогательные компоненты Node. Кроме того, с помощью действий из этой статьи вы можете обновить проект Visual Studio, чтобы использовать общую среду выполнения. Однако вам может потребоваться обновить схемы XML для манифеста. Дополнительные сведения см. в статье Устранение ошибок разработки с надстройками Office.

Настройка манифеста

Выполните указанные ниже действия для нового или существующего проекта, чтобы настроить его для использования общей среды выполнения. Эти действия подразумевают, что вы создали проект с помощью генератора Yeoman для надстроек Office.

  1. Запустите Visual Studio Code и откройте свою надстройку.

  2. Откройте файл manifest.xml.

  3. Для надстройки Excel или PowerPoint обновите раздел с требованиями, включив общую среду выполнения. Обязательно удалите требование CustomFunctionsRuntime, если оно присутствует. XML-код должен выглядеть следующим образом.

    <Hosts>
  <Host Name="Workbook"/>
</Hosts>
<Requirements>
  <Sets DefaultMinVersion="1.1">
    <Set Name="SharedRuntime" MinVersion="1.1"/>
  </Sets>
</Requirements>
<DefaultSettings>

  4. Найдите раздел VersionOverrides> и добавьте следующий раздел Runtimes.<<> Время существования должно иметь значение long, чтобы код надстройки мог выполняться даже после закрытия области задач. Значение resid — Taskpane.Url, указывающее расположение файла taskpane.html в разделе <bt:Urls> в нижней части manifest.xml.

    Важно!

    Общая среда выполнения не загружается, если в манифесте resid используются другие значения. Если вы измените значение на значение, отличное от Taskpane.Url, обязательно измените значение во всех расположениях, показанных в следующих шагах этой статьи.

    Кроме того, <раздел Среды выполнения> должен быть введен после <элемента Host> в точном порядке, указанном в следующем XML-коде.

    <VersionOverrides ...>
  <Hosts>
    <Host ...>
      <Runtimes>
        <Runtime resid="Taskpane.Url" lifetime="long" />
      </Runtimes>
    ...
    </Host>

  5. Если вы создали надстройку Excel с пользовательскими функциями <, найдите элемент Page> . Затем измените расположение источника с Functions.Page.Url на Taskpane.Url.

    <AllFormFactors>
...
<Page>
  <SourceLocation resid="Taskpane.Url"/>
</Page>
...

  6. <Найдите тег FunctionFile> и измените resid значение с Commands.Url на Taskpane.Url. Обратите внимание, что если у вас нет команд действий, у вас не <будет записи FunctionFile> и вы можете пропустить этот шаг.

    </GetStarted>
...
<FunctionFile resid="Taskpane.Url"/>
...

  7. Сохраните файл manifest.xml.

Настройка файла webpack.config.js.

Файл webpack.config.js создает несколько загрузчиков среды выполнения. Его необходимо изменить, чтобы загрузить через файлtaskpane.html только общую среду выполнения.

  1. Запустите Visual Studio Code и откройте созданный вами проект надстройки.

  2. Откройте файл webpack.config.js.

  3. Если файл webpack.config.js содержит следующий код подключаемого модуля functions.html, удалите его.

    new HtmlWebpackPlugin({
    filename: "functions.html",
    template: "./src/functions/functions.html",
    chunks: ["polyfill", "functions"]
  })

  4. Если файл webpack.config.js содержит следующий код подключаемого модуля commands.html, удалите его.

    new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"]
  })

  5. Если в проекте используются блоки functions или commands, добавьте их в список блоков, как показано ниже (следующий код предназначен для проекта, применяющего оба блока).

      new HtmlWebpackPlugin({
    filename: "taskpane.html",
    template: "./src/taskpane/taskpane.html",
    chunks: ["polyfill", "taskpane", "commands", "functions"]
  })

  6. Сохраните изменения и выполните повторную сборку проекта.

    npm run build

Примечание.

Если в проекте есть файлы functions.html или commands.html, их можно удалить. taskpane.html загрузит functions.js и commands.js код в общую среду выполнения с помощью только что внесенных обновлений webpack.

Тестирование изменений надстройки Office

Вы можете убедиться, что используете общую среду выполнения правильно, выполнив следующие инструкции.

  1. Откройте файл taskpane.js.

  2. Замените все содержимое файла указанным ниже кодом. Отобразится количество открытий области задач. Добавление события onVisibilityModeChanged поддерживается только в общей среде выполнения.

    /*global document, Office*/

let _count = 0;

Office.onReady(() => {
  document.getElementById("sideload-msg").style.display = "none";
  document.getElementById("app-body").style.display = "flex";

  updateCount(); // Update count on first open.
  Office.addin.onVisibilityModeChanged(function (args) {
    if (args.visibilityMode === "Taskpane") {
      updateCount(); // Update count on subsequent opens.
    }
  });
});

function updateCount() {
  _count++;
  document.getElementById("run").textContent = "Task pane opened " + _count + " times.";
}

  3. Сохраните изменения и запустите проект.

    npm start

Каждый раз, когда вы открываете область задач, количество открытий увеличивается на единицу. Значение _count не будет потеряно, так как общая среда выполнения продолжает выполнение кода даже при закрытии области задач.

Срок существования среды выполнения

При добавлении <элемента Runtime> также указывается время существования со значением long или short. Установите значение long, чтобы воспользоваться такими функциями, как запуск надстройки при открытии документа, продолжение выполнения кода после закрытия области задач или использование CORS и DOM из пользовательских функций.

Примечание.

По умолчанию используется значение срока жизни short, но мы рекомендуем использовать long в надстройках Excel, PowerPoint и Word. Если вы настроите в этом примере для среды выполнения значение short, ваша надстройка запустится при нажатии одной из кнопок на ленте, но может завершить работу после окончания функционирования обработчика ленты. Аналогичным образом надстройка запустится при открытии области задач, но может завершить работу после закрытия области задач.

<Runtimes>
  <Runtime resid="Taskpane.Url" lifetime="long" />
</Runtimes>

Примечание.

Если надстройка <включает элемент Runtimes> в манифест (требуется для общей среды выполнения) и условия использования WebView2 (Microsoft Edge на основе Chromium), она использует этот элемент управления. Если условия не выполнены, он использует элемент управления webview Trident (Интернет-Обозреватель 11) независимо от версии Windows или Microsoft 365. Дополнительные сведения см. в разделе Среды выполнения , браузеры и элементы управления webview, используемые надстройками Office.

Сведения о общей среде выполнения

В Windows или Mac надстройка будет выполнять код для кнопок ленты, пользовательских функций и области задач в отдельных средах выполнения. Из-за этого возникают ограничения, например невозможность удобно предоставлять общий доступ к глобальным данным и отсутствие доступа ко всей функциональности CORS для пользовательской функции.

Однако вы можете настроить надстройку Office для совместного использования кода в одной среде выполнения (также называемой общей средой выполнения). За счет этого повышается скоординированность работы надстройки и упрощается доступ к модели DOM и CORS области задач из всех компонентов надстройки.

При настройке общей среды выполнения становятся возможными следующие сценарии.

Для Office в Windows общая среда выполнения использует WebView2 (Microsoft Edge Chromium), если условия ее использования выполняются, как описано в разделе Браузеры и элементы управления webview, используемые надстройками Office. В противном случае используется Trident (Интернет Обозреватель 11). Кроме того, все кнопки, которые надстройка отображает на ленте, будут работать в одной и той же общей среде выполнения. На следующем рисунке показано, как пользовательские функции, пользовательский интерфейс ленты и код области задач будут выполняться в одной среде выполнения.

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

Отладка

В настоящее время при использовании общей среды выполнения невозможно использовать Visual Studio Code для отладки пользовательских функций в Excel под управлением Windows. Вместо этого потребуется использовать средства разработчика. Дополнительные сведения см. в статье Отладка надстроек с помощью средств разработчика для Internet Explorer или Отладка надстроек с помощью средств разработчика в Microsoft Edge (на основе Chromium).

Несколько областей задач

Не планируйте использовать в своей надстройке несколько областей задач, если предполагается использование общей среды выполнения. Общая среда выполнения поддерживает только одну область задач. Обратите внимание: любая область задач без <TaskpaneID> считается другой областью задач.

См. также