Бөлісу құралы:

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

  • Мақала

Важно!

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

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

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

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

Совет

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

  • Тип проекта: Excel Custom Functions using a Shared Runtime
  • Тип скрипта: JavaScript

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

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

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

Примечание.

Реализация общей среды выполнения с унифицированным манифестом для Microsoft 365 доступна в общедоступной предварительной версии для разработчиков. Его не следует использовать в рабочих надстройках. Мы приглашаем вас опробовать его в средах тестирования или разработки. Дополнительные сведения см. в статье Схема манифеста общедоступной предварительной версии приложения для разработчиков.

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

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

  3. Добавьте следующий объект в массив extensions.runtimes. Обратите внимание на следующие особенности этой разметки.

    • Набор требований SharedRuntime 1.1 указан в объекте requirements.capabilities. Это позволяет настроить надстройку для запуска в общей среде выполнения на поддерживаемых клиентах. Список клиентов, поддерживающих набор обязательных элементов SharedRuntime 1.1, см. в разделе Наборы обязательных элементов для общей среды выполнения.
    • Для идентификатора среды выполнения задается описательное имя SharedRuntime.
    • Свойство "время существования" имеет значение "long", чтобы надстройка могла воспользоваться преимуществами таких функций, как запуск надстройки при открытии документа, продолжение выполнения кода после закрытия области задач или использование CORS и DOM из пользовательских функций. Если в этом примере для свойства задано значение short, надстройка запустится при нажатии одной из кнопок ленты, но она может завершить работу после запуска обработчика ленты. Аналогичным образом надстройка запустится при открытии области задач, но может завершить работу после закрытия области задач.
    "runtimes": [
    "requirements": {
        "capabilities": [
            {
                "name": "SharedRuntime",
                "minVersion": "1.1"
            }
        ]
    },
    "id": "SharedRuntime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/taskpane.html"
    },
    "lifetime": "long",
    "actions": [
        ...
    ]
]

  4. Сохраните изменения.

Настройка файла 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((args) => {
    if (args.visibilityMode === Office.VisibilityMode.taskpane) {
      updateCount(); // Update count on subsequent opens.
    }
  });
});

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

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

    npm start

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

Когда вы будете готовы остановить сервер разработки и удалить надстройку, выполните следующую команду.

npm stop

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

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

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

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

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

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

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

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

См. также