Share via

Рекомендации и правила Office dialog API

  • Статья

В этой статье содержатся правила, gotchas и рекомендации для API диалога Office, включая рекомендации по проектированию пользовательского интерфейса диалога и использованию API в одностраничных приложениях (SPA).

Примечание.

Чтобы ознакомиться с основами использования API диалога Office, см. статью Использование API диалога Office в надстройках Office.

См. также раздел Обработка ошибок и событий с помощью диалогового окна Office.

Правила и подсказки

  • Диалоговое окно может переходить только по URL-адресам HTTPS, а не ПО HTTP.

  • URL-адрес, передаваемый методу displayDialogAsync , должен находиться в том же домене, что и сама надстройка. Он не может быть поддоменом. Однако страница, передаваемая ей, может перенаправляться на страницу в другом домене.

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

  • В диалоговом окне можно вызвать только два API Office:

  • Функция messageParent обычно должна вызываться со страницы в том же домене, что и сама надстройка, но это необязательно. Дополнительные сведения см. в разделе Междоменные сообщения в основной среде выполнения.

    Совет

    В Office в Интернете и новом Outlook в Windows (предварительная версия) если домен диалогового окна отличается от домена надстройки и применяет заголовок ответа Cross-Origin-Opener-Policy: same-origin-origin response, надстройка будет заблокирована для доступа к сообщениям из диалогового окна, а пользователи получат сообщение об ошибке 12006. Чтобы избежать этого, необходимо задать для заголовка Cross-Origin-Opener-Policy: unsafe-none значение или настроить надстройку и диалоговое окно в одном домене.

Лучшие методики

Избегайте чрезмерного использовать диалоговые окна

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

Разработка пользовательского интерфейса диалогового окна

Рекомендации по проектированию диалоговых окон см . в разделе Диалоговые окна в надстройках Office.

Обработка блокировщиков всплывающих окон с помощью Office в Интернете

Попытка отобразить диалоговое окно при использовании Office в Интернете может привести к блокировке диалогового окна браузера. Чтобы избежать этого, Office в Интернете предлагает пользователю разрешить или игнорировать открытие диалогового окна.

Запрос с кратким описанием и кнопками

Если пользователь выберет Разрешить, откроется диалоговое окно Office. Если пользователь выбирает Игнорировать, запрос закрывается, а диалоговое окно Office не открывается. Вместо этого displayDialogAsync метод возвращает ошибку 12009. Код должен перехватывать эту ошибку и либо предоставлять альтернативный интерфейс, который не требует диалога, либо выводить пользователю сообщение о том, что надстройка должна разрешить диалог. (Дополнительные сведения о 12009 см. в разделе Ошибки из displayDialogAsync.)

Если по какой-либо причине вы хотите отключить эту функцию, ваш код должен отказаться. Этот запрос выполняется с помощью объекта DialogOptions , который передается в displayDialogAsync метод . В частности, объект должен содержать promptBeforeOpen: false. Если для этого параметра задано значение false, Office в Интернете не будет предлагать пользователю разрешить надстройке открывать диалоговое окно, а диалоговое окно Office не откроется.

Запрос доступа к возможностям устройств в Office в Интернете и новом Outlook в Windows (предварительная версия)

Если надстройке требуется доступ к возможностям устройства пользователя, через API разрешений устройства будет доступно диалоговое окно для запроса разрешений. К возможностям устройства относятся камера пользователя, географическое расположение и микрофон. Это относится к следующим приложениям Office.

Когда надстройка вызывает Office.context.devicePermission.requestPermissions или Office.context.devicePermission.requestPermissionsAsync, отображается диалоговое окно с запрошенными возможностями устройства и параметрами Разрешить, Разрешить один раз или Запретить доступ. Дополнительные сведения см. в статье Просмотр, управление и установка надстроек для Excel, PowerPoint и Word.

Примечание.

  • Надстройки, которые выполняются в классических клиентах Office или в браузерах, не основанных на Chromium автоматически отображают диалоговое окно с запросом разрешения пользователя. Разработчику не нужно реализовывать API разрешений устройства на этих платформах.
  • Надстройкам, работающим в Safari, запрещен доступ к возможностям устройства пользователя. API разрешений устройства не поддерживается в Safari.

Не используйте значение _host_info

Office автоматически добавляет параметр запроса _host_info в URL-адрес, который передается displayDialogAsync. Он добавляется после пользовательских параметров запроса, если таковые есть. Он не добавляется к последующим URL-адресам, по которым выполняется переход в диалоговом окне. Корпорация Майкрософт может изменить содержимое этого значения или полностью удалить его, поэтому ваш код не должен читать его. Это же значение добавляется в хранилище сеансов диалогового окна (то есть в свойство Window.sessionStorage ). Ваш код не должен ни считывать это значение, ни записывать в него данные.

Открытие другого диалогового окна сразу после закрытия

На данной главной странице не может быть открыто несколько диалогов, поэтому код должен вызвать Dialog.close в открытом диалоговом окне, прежде чем он будет вызывать displayDialogAsync другое диалоговое окно. Метод close является асинхронным. По этой причине при вызове displayDialogAsync сразу после вызова close, первое диалоговое окно может быть не полностью закрыто, когда Office пытается открыть второй. В этом случае Office вернет ошибку 12007 : "Сбой операции, так как у этой надстройки уже есть активное диалоговое окно".

Метод close не принимает параметр обратного вызова и не возвращает объект Promise, поэтому его нельзя ожидать с await помощью ключевое слово или метода then . По этой причине мы предлагаем следующий способ, когда необходимо открыть новое диалоговое окно сразу после закрытия диалогового окна: инкапсулируйте код, чтобы открыть новое диалоговое окно в функции, и спроектируйте функцию так, чтобы она вызывала displayDialogAsync себя рекурсивно, если вызов возвращает 12007. Ниже приведен пример.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync("https://MyDomain/firstDialog.html", { width: 50, height: 50},
     (result) => {
      if(result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        openSecondDialog();
      }
      else {
         // Handle errors
      }
    }
  );
}
 
function openSecondDialog() {
  Office.context.ui.displayDialogAsync("https://MyDomain/secondDialog.html", { width: 50, height: 50},
    (result) => {
      if(result.status === Office.AsyncResultStatus.Failed) {
        if (result.error.code === 12007) {
          openSecondDialog(); // Recursive call
        }
        else {
         // Handle other errors
        }
      }
    }
  );
}

Кроме того, можно принудить код приостановить, прежде чем он попытается открыть второе диалоговое окно с помощью метода setTimeout . Ниже приведен пример.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync("https://MyDomain/firstDialog.html", { width: 50, height: 50},
     (result) => {
      if(result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        setTimeout(() => { 
          Office.context.ui.displayDialogAsync("https://MyDomain/secondDialog.html", { width: 50, height: 50},
             (result) => { /* callback body */ }
          );
        }, 1000);
      }
      else {
         // Handle errors
      }
    }
  );
}

Рекомендации по использованию API диалогового окна Office в SPA

Если надстройка использует маршрутизацию на стороне клиента, как это обычно делают одностраничные приложения ( SPA), вы можете передать URL-адрес маршрута методу displayDialogAsync вместо URL-адреса отдельной HTML-страницы. Мы рекомендуем не делать это по приведенным ниже причинам.

Примечание.

Эта статья не относится к маршрутизации на стороне сервера , например в веб-приложении на основе Express.

Проблемы с spAs и API диалогового окна Office

Диалоговое окно Office находится в новом окне с собственным экземпляром подсистемы JavaScript и, следовательно, является собственным контекстом полного выполнения. При передаче маршрута базовая страница и весь код инициализации и начальной загрузки снова выполняются в этом новом контексте, а для всех переменных в диалоговом окне задаются их начальные значения. Таким образом, этот метод скачивает и запускает второй экземпляр вашего приложения в окне коробки, что частично не соответствует назначению SPA. Кроме того, код, изменяющий переменные в окне диалогового окна, не изменяет версию этих переменных области задач. Аналогичным образом диалоговое окно имеет собственное хранилище сеансов (свойство Window.sessionStorage ), которое недоступно из кода в области задач. Диалоговое окно и страница узла, на которой displayDialogAsync был вызван вызов, выглядят как два разных клиента для вашего сервера. (Напоминание о том, что такое ведущая страница, см. в статье Открытие диалогового окна с главной страницы.)

Таким образом, если вы передали маршрут методу displayDialogAsync , у вас на самом деле не будет SPA; у вас будет два экземпляра одного SPA. Кроме того, большая часть кода в экземпляре области задач никогда не будет использоваться в этом экземпляре, а большая часть кода в экземпляре диалогового окна никогда не будет использоваться в этом экземпляре. Это соответствует применению двух одностраничных приложений в одном пакете.

Рекомендации корпорации Майкрософт

Вместо передачи клиентского маршрута displayDialogAsync в метод рекомендуется выполнить одно из следующих действий:

  • Если код, который требуется запустить в диалоговом окне, является достаточно сложным, создайте два разных spas явным образом; т. е. два субъекта-службы в разных папках одного домена. Один spa запускается в диалоговом окне, а другой — на главной странице диалогового окна, где displayDialogAsync был вызван вызов.
  • В большинстве случаев в диалоговом окне требуется только простая логика. В таких случаях проект будет значительно упрощен путем размещения одной HTML-страницы с внедренным javaScript или ссылкой на нее в домене SPA. Передайте URL-адрес страницы в метод displayDialogAsync. Хотя это означает, что вы отклоняесь от буквальной идеи одностраничного приложения; При использовании API диалога Office у вас нет ни одного экземпляра SPA.