Среды выполнения в надстройках Office

Надстройки Office выполняются в средах выполнения, внедренных в Office. Как интерпретируемый язык JavaScript должен выполняться в среде выполнения JavaScript. примерами таких сред выполнения являютсяNode.jsи современные браузеры.

Типы сред выполнения

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

• Среда выполнения, доступная только для JavaScript: подсистема JavaScript, дополненная поддержкой WebSocket, full CORS (общий доступ к ресурсам между источниками) и клиентским хранилищем данных. Он не поддерживает локальное хранилище или файлы cookie.
• Среда выполнения браузера. Включает все функции среды выполнения, доступной только для JavaScript, и добавляет поддержку локального хранилища, обработчика отрисовки , который отображает HTML и файлы cookie.

Сведения об этих типах приведены далее в этой статье в статьях Среда выполнения только для JavaScript и Среда выполнения браузера.

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

Тип среды выполнения	Функция надстройки
Только JavaScript	Пользовательские функции Excel(за исключением случаев, когда среда выполнения является общей или надстройка запущена в Office в Интернете) Задача на основе событий Outlook(только если надстройка запущена в классической версии Outlook в Windows) Встроенная функция создания отчетов о нежелательной почте (только если надстройка запущена в классической версии Outlook в Windows)
Обозреватель	область задач диалог команда functionПользовательские функции Excel(когда среда выполнения является общей или надстройка запущена в Office в Интернете) Задача на основе событий Outlook (когда надстройка запущена в Outlook на Mac или Outlook в Интернете или в новом Outlook для Windows) Встроенная функция создания отчетов о нежелательной почте (только если надстройка запущена в Outlook на Mac, в Интернете или в новом Outlook для Windows)

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

Функция надстройки	Тип среды выполнения в Windows	Тип среды выполнения на Mac	Тип среды выполнения в Интернете
Пользовательские функции Excel	Только JavaScript(но браузер , если среда выполнения является общей)	Обозреватель	Обозреватель
Задачи на основе событий Outlook	Только JavaScript (классический Outlook в Windows) браузер (новый Outlook в Windows)	Обозреватель	Обозреватель
Встроенная функция отчетов о нежелательной почте в Outlook (предварительная версия)	Только JavaScript (классический Outlook в Windows) браузер (новый Outlook в Windows)	Обозреватель	Обозреватель
Надстройки области задач	Обозреватель	Обозреватель	Обозреватель
диалоговое окно	Обозреватель	Обозреватель	Обозреватель
команда function	Обозреватель	Обозреватель	Обозреватель

В Office в Интернете все всегда выполняется в среде выполнения типов браузера. За одним исключением все надстройки в Интернете выполняется в том же процессе браузера: в браузере, в котором пользователь открыл Office в Интернете. Исключением является то, что диалоговое окно открывается с помощью вызова Office.ui.displayDialogAsync , а параметр DialogOptions.displayInIFrameне передается и имеет значение true. Если параметр не передается (поэтому он имеет значение по умолчанию false ), диалоговое окно открывается в собственном процессе. Тот же принцип применяется к методу OfficeRuntime.displayWebDialog и параметру OfficeRuntime.DisplayWebDialogOptions.displayInIFrame .

Если надстройка работает на платформе, отличной от Интернета, применяются следующие принципы.

• Диалоговое окно запускается в собственном процессе выполнения.

• Надстройка outlook на основе событий или отчетов о спаме выполняется в собственном процессе выполнения.

  Примечание.

  Функции активации на основе событий и интегрированные функции создания отчетов о нежелательной почте в Outlook должны использовать одну и ту же среду выполнения. Несколько сред выполнения в настоящее время не поддерживаются в Outlook.

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

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

• Надстройка PowerPoint или Word, которая не использует никаких сред выполнения и содержит следующие функции, имеет целых три среды выполнения.

  • Область задач

  • Команда функции

  • Диалоговое окно (диалоговое окно можно запустить из области задач или из команды функции.)

    Примечание.

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

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

  • Область задач
  • Команда функции
  • Пользовательская функция
  • Диалоговое окно (диалоговое окно можно запустить либо из области задач, либо из команды функции, либо из пользовательской функции.)

• Надстройка Excel с теми же функциями и настроена для совместного использования одной среды выполнения в области задач, команде функции и пользовательской функции, имеет две среды выполнения. Общая среда выполнения может одновременно открывать только одно диалоговое окно.

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

• Надстройка Outlook со следующими функциями имеет целых четыре среды выполнения. Общие среды выполнения не поддерживаются в Outlook.

  • Область задач
  • Команда функции
  • Задача на основе событий или встроенная функция создания отчетов о нежелательной почте
  • Диалоговое окно (диалоговое окно может быть запущено из области задач или команды функции, но не из задачи на основе событий.)

Совместное использование данных между средами выполнения

Примечание.

• Если вы знаете, что ваша надстройка будет использоваться только в Office в Интернете и что она не будет открывать диалоги с параметром displayInIFrametrue, то этот раздел можно игнорировать. Так как все в надстройке выполняется в одном процессе выполнения, можно просто использовать глобальные переменные для совместного использования данных между компонентами.
• Как отмечалось выше в разделе Типы сред выполнения, тип среды выполнения, используемый компонентом, частично зависит от платформы. Рекомендуется избегать использования кода надстройки, который ветвляется на основе платформы, поэтому в руководстве в этом разделе рекомендуются методы, которые будут работать на разных платформах. Существует только один случай, указанный ниже, в котором требуется код ветвления.

Для надстроек Excel, PowerPoint и Word используйте общую среду выполнения , если какие-либо две или более функций, кроме диалоговых окон, требуют совместного доступа к данным. В Outlook или сценариях, в которых совместное использование среды выполнения невозможно, требуются альтернативные методы. Части надстройки, которые находятся в отдельных процессах среды выполнения, не совместно используют глобальные данные автоматически и обрабатываются сервером веб-приложений надстройки как отдельные сеансы, поэтому Window.sessionStorage не может использоваться для совместного использования данных между ними. В следующем руководстве предполагается, что вы не используете общую среду выполнения.

• Передача данных между диалогом и его родительской областью задач, командой функции или пользовательской функцией с помощью методов Office.ui.messageParent и Dialog.messageChild .

  Примечание.

  Методы OfficeRuntime.storage не могут быть вызваны в диалоговом окне, поэтому это не вариант для совместного использования данных между диалогом и другой средой выполнения.

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

  Примечание.

  LocalStorage недоступен в среде выполнения только для JavaScript и, следовательно, недоступен в пользовательских функциях Excel. Его также нельзя использовать для совместного использования данных с задачами на основе событий Outlook (так как на некоторых платформах эти задачи используют среду выполнения только JavaScript).

  Начиная с версии 115 для браузеров на основе Chromium, таких как Chrome и Edge, секционирование хранилища включено, чтобы предотвратить отслеживание между сайтами по боковому каналу (см. также политики браузера Microsoft Edge). Это означает, что данные, хранящиеся API хранилища, например локальным хранилищем, доступны только для контекстов с тем же источником и тем же сайтом верхнего уровня.

  Совет

  Данные в Window.localStorage сохраняются между сеансами надстройки и совместно используются надстройками с тем же источником. Обе эти характеристики часто нежелательны для надстройки.

  • Чтобы убедиться, что каждый сеанс данной надстройки запускается заново, вызовите метод Window.localStorage.clear при запуске надстройки.
  • Чтобы разрешить сохранение некоторых сохраненных значений, но повторно инициализацию других значений, используйте Window.localStorage.setItem при запуске надстройки для каждого элемента, который должен быть сброшен до начального значения.
  • Чтобы полностью удалить элемент, вызовите Window.localStorage.removeItem.

• Чтобы совместно использовать данные между пользовательской функцией Excel и любой другой средой выполнения, используйте OfficeRuntime.storage.

• Чтобы совместно использовать данные между задачей на основе событий Outlook и командой области задач или функции, необходимо ветвить код по значению свойства Office.context.platform .

  • Если значение равно PC (Windows), храните и извлекаете данные с помощью API Office.sessionData .
  • Если значение равно Mac, используйте Window.localStorage , как описано выше в этом списке.

К другим способам предоставления общего доступа к данным относятся следующие:

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

Дополнительные сведения см. в разделах Сохранение состояния и параметров надстройки и Получение и настройка метаданных надстройки для надстройки Outlook.

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

Среда выполнения только Для JavaScript, используемая в надстройках Office, является изменением среды выполнения с открытым кодом, изначально созданной для React Native. Он содержит подсистему JavaScript, дополненную поддержкой WebSocket, full CORS (общий доступ к ресурсам между источниками) и OfficeRuntime.storage. Он не имеет подсистемы отрисовки и не поддерживает файлы cookie или локальное хранилище.

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

• При использовании для пользовательской функции Excel среда выполнения запускается при пересчете листа или при вычислении пользовательской функции. Он не завершает работу, пока книга не будет закрыта.

• При использовании в надстройке на основе событий Outlook или надстройке, сообщающей о спаме, среда выполнения запускается при возникновении события. Он заканчивается, когда происходит первое из следующих действий.

  • Обработчик событий вызывает completed метод своего параметра события.
  • С момента запуска события прошло пять минут.
  • Пользователь изменяет фокус с окна, в котором было активировано событие, например окна создания сообщения (применяется только к надстройкам на основе событий).

  Примечание.

  Функции активации на основе событий и интегрированные функции создания отчетов о нежелательной почте в Outlook должны использовать одну и ту же среду выполнения. Несколько сред выполнения в настоящее время не поддерживаются в Outlook.

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

Важно!

В версиях Office для Windows до 2403 (сборка 16.0.17425.20000) и бессрочных лицензий Office по Office 2021 среда выполнения javaScript, доступная только для JavaScript, напрямую поддерживает стандарт ECMAScript 2016 JavaScript. Однако можно использовать более поздние версии JavaScript или TypeScript. Сведения о том, как это сделать, см. в разделе Поддержка последних версий JavaScript.

Среда выполнения браузера

Надстройки Office используют среду выполнения браузера другого типа в зависимости от платформы, на которой выполняется Office (веб-сайт, Mac или Windows), а также от версии и сборки Windows и Office. Например, если пользователь запускает Office в Интернете в браузере FireFox, используется среда выполнения Firefox. Если пользователь использует Office на Mac, используется среда выполнения Safari. Если пользователь работает под управлением Office в Windows, среда выполнения предоставляется в браузере Edge или Internet Explorer в зависимости от версии Windows и Office. Подробные сведения можно найти в браузерах и элементах управления webview, используемых надстройками Office.

Все эти среды выполнения включают обработчик отрисовки HTML и обеспечивают поддержку WebSocket, full CORS (общий доступ к ресурсам между источниками),локальное хранилище и файлы cookie.

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

• При запуске надстройки с областью задач запускается среда выполнения браузера, если это не общая среда выполнения, которая уже запущена. Если это общая среда выполнения, она завершает работу при закрытии документа. Если это не общая среда выполнения, она завершает работу при закрытии области задач.

• При открытии диалогового окна запускается среда выполнения браузера. Он завершает работу при закрытии диалогового окна.

• При выполнении команды функции (что происходит, когда пользователь нажимает кнопку или пункт меню), запускается среда выполнения браузера, если это не общая среда выполнения, которая уже запущена. Если это общая среда выполнения, она завершает работу при закрытии документа. Если это не общая среда выполнения, она завершает работу при первом из следующих действий.

  • Команда функции вызывает completed метод своего параметра события.
  • С момента запуска события прошло пять минут. (Если диалоговое окно было открыто в команде функции и по-прежнему открыто, когда время ожидания родительской среды выполнения истекло, среда выполнения диалога остается запущенной до закрытия диалогового окна.)

• Если пользовательская функция Excel использует общую среду выполнения, среда выполнения браузера запускается, когда пользовательская функция вычисляет, не запущена ли общая среда выполнения по какой-либо другой причине. Он завершает работу при закрытии документа.

Примечание.

При совместном использовании среды выполнения код может закрыть область задач без завершения работы надстройки. Дополнительные сведения см. в статье Отображение или скрытие области задач надстройки Office .

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

Общее время выполнения

"Общая среда выполнения" не является типом среды выполнения. Он относится к среде выполнения браузерного типа , которая используется функциями надстройки, которые в противном случае будут иметь собственную среду выполнения. В частности, вы можете настроить команды области задач и функций надстройки для совместного использования среды выполнения. В надстройке Excel можно также настроить пользовательские функции для совместного использования среды выполнения области задач или команды функции или и того, и другого. При этом пользовательские функции выполняются в среде выполнения браузера, а не в среде выполнения, доступной только для JavaScript , как это было бы в противном случае. Сведения о преимуществах и ограничениях среды выполнения совместного использования, а также инструкции по настройке надстройки для использования общей среды выполнения см. в статье Настройка надстройки для использования общей среды выполнения. Вкратце, среда выполнения, доступная только для JavaScript, использует меньше памяти и быстрее запускается, но имеет меньше возможностей.

Примечание.

• Вы можете совместно использовать среды выполнения только в Excel, PowerPoint и Word.
• Невозможно настроить диалоговое окно для совместного использования среды выполнения. Каждый диалог всегда имеет свой собственный, за исключением случаев, когда диалог запускается в Office в Интернете с параметром displayInIFrametrue.
• Общая среда выполнения никогда не использует исходную среду выполнения Microsoft Edge WebView (EdgeHTML). Если выполнены условия использования Microsoft Edge с WebView2 (на основе Chromium) (как указано в разделе Браузеры и элементы управления webview, используемые надстройками Office), используется эта среда выполнения. В противном случае используется среда выполнения Internet Explorer 11.