Использование Dialog API в надстройках OfficeUse the Dialog API in your Office Add-ins

Вы можете использовать Dialog API, чтобы открывать диалоговые окна в надстройке Office. Эта статья содержит рекомендации по использованию Dialog API в надстройке Office.You can use the Dialog API to open dialog boxes in your Office Add-in. This article provides guidance for using the Dialog API in your Office Add-in.

Примечание

Сведения о поддержке Dialog API см. в статье Наборы обязательных элементов Dialog API. В настоящее время Dialog API поддерживается для Word, Excel, PowerPoint и Outlook.For information about where the Dialog API is currently supported, see Dialog API requirement sets. The Dialog API is currently supported for Word, Excel, PowerPoint, and Outlook.

Основной сценарий применения Dialog API — обеспечение проверки подлинности с использованием таких ресурсов, как Google, Facebook или Microsoft Graph.A primary scenario for the Dialog APIs is to enable authentication with a resource such as Google or Facebook. Дополнительные сведения см. в статье Проверка подлинности с помощью Dialog API для Office после прочтения текущей статьи.For more information, see Authenticate with the Office Dialog API after you are familiar with this article.

Возможность открытия диалогового окна с помощью области задач, контентной надстройки или команды надстройки может позволить следующее:Consider opening a dialog box from a task pane or content add-in or add-in command to do the following:

  • отобразить страницу входа, которую невозможно открыть непосредственно в области задач;Display sign in pages that cannot be opened directly in a task pane.
  • предоставить больше места на экране (или даже весь экран) для некоторых задач в надстройке;Provide more screen space, or even a full screen, for some tasks in your add-in.
  • разместить видео, которое будет слишком маленьким в области задач.Host a video that would be too small if confined to a task pane.

Примечание

Так как пользователей раздражают элементы интерфейса, перекрывающие основное содержимое, не допускайте открытия диалогового окна из области задач, если этого не требует сценарий. При планировании контактной зоны помните, что в области задач можно использовать вкладки. Например, как в надстройке SalesTracker на JavaScript для Excel.Because overlapping UI elements are discouraged, avoid opening a dialog from a task pane unless your scenario requires it. When you consider how to use the surface area of a task pane, note that task panes can be tabbed. For an example, see the Excel Add-in JavaScript SalesTracker sample.

На приведенном ниже изображении показан пример диалогового окна. The following image shows an example of a dialog box.

Команды надстроек

Обратите внимание на то, что диалоговое окно всегда открывается в центре экрана. Пользователь может перемещать его и изменять его размер. Окно не модальное: пользователь может продолжать работать и с документом в ведущем приложении Office, и с главной страницей в области задач.Note that the dialog box always opens in the center of the screen. The user can move and resize it. The window is nonmodal--a user can continue to interact with both the document in the host Office application and with the host page in the task pane, if there is one.

Сценарии с Dialog APIDialog API scenarios

Интерфейсы API JavaScript для Office поддерживают указанные ниже сценарии с объектом Dialog и две функции в пространстве имен Office.context.ui.The Office JavaScript APIs support the following scenarios with a Dialog object and two functions in the Office.context.ui namespace.

Открытие диалогового окнаOpen a dialog box

Чтобы открыть диалоговое окно, код в области задач вызывает метод displayDialogAsync и передает ему URL-адрес ресурса, который нужно открыть. Таким ресурсом обычно является страница, но может быть и метод контроллера в приложении MVC, метод веб-службы, маршрута или любой другой ресурс. В этой статье термин "страница" или "веб-сайт" означает ресурс в диалоговом окне. Ниже приведен простой пример кода.To open a dialog box, your code in the task pane calls the displayDialogAsync method and passes to it the URL of the resource that you want to open. This is usually a page, but it can be a controller method in an MVC application, a route, a web service method, or any other resource. In this article, 'page' or 'website' refers to the resource in the dialog. The following code is a simple example:

Office.context.ui.displayDialogAsync('https://myAddinDomain/myDialog.html');

Примечание

  • В случае URL-адреса используется протокол HTTPS, обязательный для всех страниц, загружаемых в диалоговом окне, а не только для первой страницы.The URL uses the HTTPS protocol. This is mandatory for all pages loaded in a dialog box, not just the first page loaded.
  • Домен ресурса диалоговых окон совпадает с доменом страницы ведущего приложения, которая может быть страницей в области задач или файле функций для команды надстройки.The dialog resource's domain is the same as the domain of the host page, which can be the page in a task pane or the function file of an add-in command. Страница, метод контроллера или другой ресурс, передаваемый в метод displayDialogAsync, должен быть в том же домене, что и страница ведущего приложения.This is required: the page, controller method, or other resource that is passed to the displayDialogAsync method must be in the same domain as the host page.

Важно!

Страница ведущего приложения и ресурсы диалоговых окон должны иметь одинаковые полные доменные имена.The host page and the resources of the dialog must have the same full domain. Если вы попробуете передать поддомен домена надстройки в displayDialogAsync, ничего не получится.If you attempt to pass displayDialogAsync a subdomain of the add-in's domain, it will not work. Полные доменные имена, включая поддомены, должны совпадать.The full domain, including any subdomain, must match.

После загрузки первой страницы (или другого ресурса) пользователь может перейти к любому веб-сайту (или другому ресурсу), который использует HTTPS. Первая страница также может сразу перенаправлять пользователя на другой сайт.After the first page (or other resource) is loaded, a user can go to any website (or other resource) that uses HTTPS. You can also design the first page to immediately redirect to another site.

По умолчанию диалоговое окно занимает 80 % высоты и ширины экрана устройства, но вы можете установить другие соотношения путем передачи объекта конфигурации в метод, как показано в приведенном ниже примере.By default, the dialog box will occupy 80% of the height and width of the device screen, but you can set different percentages by passing a configuration object to the method, as shown in the following example:

Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html', {height: 30, width: 20});

Подобная надстройка приведена в статье Пример надстройки Office с Dialog API.For a sample add-in that does this, see Office Add-in Dialog API Example.

Установите оба значения равными 100 %, чтобы надстройка открывалась во весь экран. (На самом деле, максимальное значение составляет 99,5 %, возможность перемещать окно и изменять его размер сохраняется.)Set both values to 100% to get what is effectively a full screen experience. (The effective maximum is 99.5%, and the window is still moveable and resizable.)

Примечание

Из главного окна можно открыть только одно диалоговое окно. При попытке открыть еще одно диалоговое окно произойдет ошибка. Поэтому если пользователь, например, откроет диалоговое окно из области задач, он не сможет открыть второе диалоговое окно на другой странице в области задач. Но при открытии диалогового окна с помощью команды надстройки каждый раз открывается новый (невидимый) HTML-файл. При этом создается новое (невидимое) главное окно, которое может запускать собственное диалоговое окно. Дополнительные сведения см. в разделе Ошибки метода displayDialogAsync.You can open only one dialog box from a host window. An attempt to open another dialog box generates an error. For example, if a user opens a dialog box from a task pane, she cannot open a second dialog box, from a different page in the task pane. However, when a dialog box is opened from an add-in command, the command opens a new (but unseen) HTML file each time it is selected. This creates a new (unseen) host window, so each such window can launch its own dialog box. For more information, see Errors from displayDialogAsync.

Использование параметра производительности в Office в ИнтернетеTake advantage of a performance option in Office Online

displayInIframe — дополнительное свойство в объекте конфигурации, которое можно передать displayDialogAsync.The displayInIframe property is an additional property in the configuration object that you can pass to displayDialogAsync. Когда этому свойству присвоено значение true, а надстройка запущена для документа в Office в Интернете, диалоговое окно будет открываться быстрее, потому что будет выступать как плавающий фрейм iframe.When this property is set to true, and the add-in is running in a document opened in Office Online, the dialog box will open as a floating iframe rather than an independent window, which makes it open faster. Ниже приведен пример.The following is an example:

Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html', {height: 30, width: 20, displayInIframe: true});

Значение по умолчанию: false. Его использование равнозначно пропуску всего свойства.The default value is false, which is the same as omitting the property entirely. Если надстройка не работает в Office в Интернете, displayInIframe игнорируется.If the add-in is not running in Office Online, the displayInIframe is ignored.

Примечание

Не следует использовать displayInIframe: true, если диалоговое окно будет выполнять перенаправление на страницу, которую невозможно открыть в элементе iframe. Например, страницы входа многих популярных веб-служб (который выполняется, например, с помощью учетной записи Майкрософт или Google), невозможно открыть в элементе iframe.You should not use displayInIframe: true if the dialog will at any point redirect to a page that cannot be opened in an iframe. For example, the sign in pages of many popular web services, such as Google and Microsoft Account, cannot be opened in an iframe.

Обработка блокировщиков всплывающих окон с помощью Office в ИнтернетеHandling pop-up blockers with Office on the web

Попытка отобразить диалоговое окно при использовании Office в Интернете может вызвать блокировку этого диалогового окна блокировщиком всплывающих окон браузера.Attempting to display a dialog while using Office Online may cause the browser's pop-up blocker to block the dialog. Блокировщик всплывающих окон браузера можно обойти, если пользователь надстройки сначала предоставит согласие на запрос от надстройки.The browser's pop-up blocker can be circumvented if the user of your add-in first agrees to a prompt from the add-in. У объекта DialogOptions метода displayDialogAsync есть свойство promptBeforeOpen, вызывающее такое всплывающее окно.displayDialogAsync's DialogOptions has the promptBeforeOpen property to trigger such a pop-up. promptBeforeOpen предоставляет собой логическое значение, обеспечивающее указанное ниже поведение.promptBeforeOpen is a boolean value which provides the following behavior:

  • true — платформа отображает всплывающее окно, чтобы запустить навигацию и обойти блокировщик всплывающих окон браузера.true - The framework displays a pop-up to trigger the navigation and avoid the browser's pop-up blocker.
  • false — диалоговое окно не отображается. Всплывающие окна должны обрабатываться разработчиком (путем предоставления артефакта пользовательского интерфейса для запуска навигации).false - The dialog will not be shown and the developer must handle pop-ups (by providing a user interface artifact to trigger the navigation).

Всплывающее окно аналогично представленному на снимке экрана ниже.The pop-up looks similiar to that in the following screenshot:

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

Отправка сведений из диалогового окна главной страницеSend information from the dialog box to the host page

Диалоговое окно может взаимодействовать с главной страницей в области задач, если:The dialog box cannot communicate with the host page in the task pane unless:

  • Текущая страница в диалоговом окне не находится в том же домене, что и главная страница.The current page in the dialog box is in the same domain as the host page.
  • Библиотека JavaScript для Office не загружена на странице. (Как и любая страница, которая использует библиотеку JavaScript для Office, сценарий для страницы должен назначить метод свойству Office.initialize. Метод может быть пустой. Дополнительные сведения см. в разделе Инициализация надстройки.)The Office JavaScript library is loaded in the page. (Like any page that uses the Office JavaScript library, script for the page must assign a method to the Office.initialize property, although it can be an empty method. For details, see Initializing your add-in.)

Код в диалоговом окне использует функцию messageParent для отправки логического значения или строки на главную страницу. Строка может быть словом, предложением, большим двоичным объектом XML, строковым представлением JSON или любым другим объектом, который можно сериализовать, представив в виде строки. Ниже приведен пример.Code in the dialog page uses the messageParent function to send either a Boolean value or a string message to the host page. The string can be a word, sentence, XML blob, stringified JSON, or anything else that can be serialized to a string. The following is an example:

if (loginSuccess) {
    Office.context.ui.messageParent(true);
}

Примечание

  • Функция messageParent — это один из двух API Office, которые можно вызывать в диалоговом окне. Другой — Office.context.requirements.isSetSupported. Дополнительные сведения см. в статье Указание ведущих приложений Office и требований к API.The messageParent function is one of only two Office APIs that can be called in the dialog box. The other is Office.context.requirements.isSetSupported. For information about it, see Specify Office hosts and API requirements.
  • Функцию messageParent можно вызывать только на странице, которая относится к тому же домену (включая протокол и порт), что и главная страница.The messageParent function can only be called on a page with the same domain (including protocol and port) as the host page.

В следующем примере googleProfile — это строковое представление профиля Google пользователя.In the next example, googleProfile is a stringified version of the user's Google profile.

if (loginSuccess) {
    Office.context.ui.messageParent(googleProfile);
}

Чтобы главная страница получила сообщение, ее необходимо настроить. Для этого добавьте параметр обратного вызова в исходный вызов displayDialogAsync. Обратный вызов назначает событию DialogMessageReceived обработчик. Ниже приведен пример.The host page must be configured to receive the message. You do this by adding a callback parameter to the original call of displayDialogAsync. The callback assigns a handler to the DialogMessageReceived event. The following is an example:

var dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html', {height: 30, width: 20},
    function (asyncResult) {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

Примечание

  • Office передает объект AsyncResult в функцию обратного вызова. Он представляет собой результат попытки открыть диалоговое окно, но не результат событий в диалоговом окне. Дополнительные сведения об этой особенности см. в разделе Обработка ошибок и событий.Office passes an AsyncResult object to the callback. It represents the result of the attempt to open the dialog box. It does not represent the outcome of any events in the dialog box. For more on this distinction, see the section Handle errors and events.
  • Для свойства value объекта asyncResult задан объект Dialog, который существует на главной странице, а не в контексте выполнения диалогового окна.The value property of the asyncResult is set to a Dialog object, which exists in the host page, not in the dialog box's execution context.
  • processMessage — это функция, которая обрабатывает событие. Вы можете присвоить ей любое имя.The processMessage is the function that handles the event. You can give it any name you want.
  • Переменная dialog объявляется в более широком контексте, чем обратный вызов, так как на нее также ссылается processMessage.The dialog variable is declared at a wider scope than the callback because it is also referenced in processMessage.

Ниже приведен простой пример обработчика для события DialogMessageReceived.The following is a simple example of a handler for the DialogMessageReceived event:

function processMessage(arg) {
    var messageFromDialog = JSON.parse(arg.message);
    showUserName(messageFromDialog.name);
}

Примечание

  • Office передает объект arg в обработчик. Его свойство message — это логическое значение или строка, отправляемая при вызове messageParent в диалоговом окне. В данном примере это профиль пользователя из учетной записи Майкрософт, Google или другой службы, представленный в виде строки, поэтому он десериализируется обратно в объект с помощью метода JSON.parse.Office passes the arg object to the handler. Its message property is the Boolean or string sent by the call of messageParent in the dialog. In this example, it is a stringified representation of a user's profile from a service such as Microsoft Account or Google, so it is deserialized back to an object with JSON.parse.
  • Функция showUserName не показана. Она может отображать персонализированное приветствие в области задач.The showUserName implementation is not shown. It might display a personalized welcome message on the task pane.

Когда взаимодействие пользователя с диалоговым окном закончится, обработчик сообщений должен закрыть диалоговое окно, как показано в этом примере.When the user interaction with the dialog box is completed, your message handler should close the dialog box, as shown in this example.

function processMessage(arg) {
    dialog.close();
    // message processing code goes here;
}

Примечание

  • Объект dialog должен быть таким же, как объект, который возвращается при вызове displayDialogAsync.The dialog object must be the same one that is returned by the call of displayDialogAsync.
  • Вызов метода dialog.close дает указание Office немедленно закрыть диалоговое окно.The call of dialog.close tells Office to immediately close the dialog box.

Пример надстройки, в которой используются эти методы, см. в статье Пример надстройки Office с Dialog API.For a sample add-in that uses these techniques, see Office Add-in Dialog API Example.

Если надстройка должна открыть другую страницу области задач после получения сообщения, можно использовать метод window.location.replace (или window.location.href) в последней строке обработчика. Ниже приведен пример.If the add-in needs to open a different page of the task pane after receiving the message, you can use the window.location.replace method (or window.location.href) as the last line of the handler. The following is an example:

function processMessage(arg) {
    // message processing code goes here;
    window.location.replace("/newPage.html");
    // Alternatively ...
    // window.location.href = "/newPage.html";
}

Пример подобной надстройки см. в статье Вставка диаграмм Excel с помощью Microsoft Graph в надстройке PowerPoint.For an example of an add-in that does this, see the Insert Excel charts using Microsoft Graph in a PowerPoint add-in sample.

Условные сообщенияConditional messaging

Так как из диалогового окна можно отправить несколько вызовов messageParent, но на главной странице есть только один обработчик для события DialogMessageReceived, обработчику необходимо использовать условную логику, чтобы различать сообщения. Например, если диалоговое окно предлагает пользователю войти в учетную запись Майкрософт, Google или другого поставщика удостоверений, оно отправляет профиль пользователя в виде сообщения. Если выполнить аутентификацию не удается, диалоговое окно отправляет сведения об ошибке на главную страницу, как показано в приведенном ниже примере.Because you can send multiple messageParent calls from the dialog box, but you have only one handler in the host page for the DialogMessageReceived event, the handler must use conditional logic to distinguish different messages. For example, if the dialog box prompts a user to sign in to an identity provider such as Microsoft Account or Google, it sends the user's profile as a message. If authentication fails, the dialog box sends error information to the host page, as in the following example:

if (loginSuccess) {
    var userProfile = getProfile();
    var messageObject = {messageType: "signinSuccess", profile: userProfile};
    var jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
} else {
    var errorDetails = getError();
    var messageObject = {messageType: "signinFailure", error: errorDetails};
    var jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Примечание

  • Переменная loginSuccess будет инициализирована после считывания отклика HTTP от поставщика удостоверений.The loginSuccess variable would be initialized by reading the HTTP response from the identity provider.
  • Реализация функций getProfile и getError не показана. Они получают данные из параметра запроса или ответа HTTP.The the implementation of the getProfile and getError functions are not not shown. They each get data from a query parameter or from the body of the HTTP response.
  • В зависимости от того, удалось ли выполнить вход, отправляются анонимные объекты различных типов. Оба содержат свойство messageType, но один содержит свойство profile, а другой — свойство error.Anonymous objects of different types are sent depending on whether the sign in was successful. Both have a messageType property, but one has a profile property and the other has an error property.

Код обработчика на главной странице использует значение свойства messageType для разветвления, как показано в приведенном ниже примере. Обратите внимание на то, что здесь используется та же функция showUserName, что и в примере выше, а функция showNotification отображает сообщение об ошибке в элементе пользовательского интерфейса на главной странице.The handler code in the host page uses the value of the messageType property to branch as shown in the following example. Note that the showUserName function is the same as in the previous example and showNotification function displays the error in the host page's UI.

function processMessage(arg) {
    var messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "signinSuccess") {
        dialog.close();
        showUserName(messageFromDialog.profile.name);
        window.location.replace("/newPage.html");
    } else {
        dialog.close();
        showNotification("Unable to authenticate user: " + messageFromDialog.error);
    }
}

Примечание

Реализация функции showNotification не показана в примере кода, представленном в этой статье.The showNotification implementation is not shown in the sample code provided by this article. Пример возможного способа реализации этой функции в своей надстройке см. в статье Пример использования API диалоговых окон в надстройке Office.For an example of how you might implement this function within your add-in, see Office Add-in Dialog API Example.

Закрытие диалогового окнаClosing the dialog box

Вы можете добавить в диалоговое окно кнопку, которая будет его закрывать. Для этого обработчик событий кнопки должен использовать messageParent, чтобы сообщить главной странице, что кнопка нажата. Ниже приведен пример.You can implement a button in the dialog box that will close it. To do this, the click event handler for the button should use messageParent to tell the host page that the button has been clicked. The following is an example:

function closeButtonClick() {
    var messageObject = {messageType: "dialogClosed"};
    var jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Обработчик главной страницы для DialogMessageReceived вызовет dialog.close, как показано в этом примере. (Примеры инициализации объекта dialog см. выше в этой статье.)The host page handler for DialogMessageReceived would call dialog.close, as in this example. (See previous examples that show how the dialog object is initialized.)

function processMessage(arg) {
    var messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "dialogClosed") {
       dialog.close();
    }
}

Даже если у вас нет собственной кнопки для закрытия диалогового окна, пользователь сможет закрыть его, нажав кнопку X в правом верхнем углу. Это действие запускает событие DialogEventReceived. Чтобы главная область могла реагировать на это событие, для нее должен быть объявлен обработчик этого события. Подробнее: Ошибки и события в диалоговом окне.Even when you don't have your own close dialog UI, an end user can close the dialog box by choosing the X in the upper-right corner. This action triggers the DialogEventReceived event. If your host pane needs to know when this happens, it should declare a handler for this event. See the section Errors and events in the dialog window for details.

Обработка ошибок и событийHandle errors and events

Код должен обрабатывать две категории событий:Your code should handle two categories of events:

  • Ошибки, возвращаемые при вызове метода displayDialogAsync, так как не удается создать диалоговое окно.Errors returned by the call of displayDialogAsync because the dialog box cannot be created.
  • Ошибки и другие события в диалоговом окне.Errors, and other events, in the dialog window.

Ошибки метода displayDialogAsyncErrors from displayDialogAsync

Кроме общих ошибок платформы и системы, при вызове метода displayDialogAsync возникают указанные ниже ошибки.In addition to general platform and system errors, three errors are specific to calling displayDialogAsync.

Цифровой кодCode number ЗначениеMeaning
1200412004 Домен URL-адреса, передаваемого в метод displayDialogAsync, не является доверенным. Домен должен быть таким же, как и для главной страницы (а также протокол и номер порта).The domain of the URL passed to displayDialogAsync is not trusted. The domain must be the same domain as the host page (including protocol and port number).
1200512005 URL-адрес, передаваемый в метод displayDialogAsync, использует протокол HTTP. Необходим протокол HTTPS. (В некоторых версиях Office сообщение об ошибке 12005 совпадает с сообщением 12004.)The URL passed to displayDialogAsync uses the HTTP protocol. HTTPS is required. (In some versions of Office, the error message returned with 12005 is the same one returned for 12004.)
1200712007 Диалоговое окно уже открыто из этого главного окна. Для главного окна, например области задач, невозможно открыть сразу несколько диалоговых окон.A dialog box is already opened from this host window. A host window, such as a task pane, can only have one dialog box open at a time.
1200912009 Пользователь проигнорировал диалоговое окно.The user chose to ignore the dialog box. Эта ошибка может возникнуть в веб-версиях Office, где пользователи могут не разрешить надстройке открыть диалоговое окно.This error can occur in online versions of Office, where users may choose not to allow an add-in to present a dialog.

При вызове displayDialogAsync он всегда передает объект AsyncResult в функцию обратного вызова.When displayDialogAsync is called, it always passes an AsyncResult object to its callback function. Если вызов выполнен, т. е. диалоговое окно открыто, свойство value объекта AsyncResult представляет собой объект Dialog.When the call is successful - that is, the dialog window is opened - the value property of the AsyncResult object is a Dialog object. См. пример в разделе Отправка данных из диалогового окна на страницу ведущего приложения.An example of this is in the section Send information from the dialog box to the host page. Если вызвать displayDialogAsync не удается, то окно не создается, свойству status объекта AsyncResult присваивается значение Office.AsyncResultStatus.Failed, а также заполняется свойство error объекта.When the call to displayDialogAsync fails, the window is not created, the status property of the AsyncResult object is set to Office.AsyncResultStatus.Failed, and the error property of the object is populated. У вас всегда должна быть функция обратного вызова, которая проверяет status и сообщает об ошибке.You should always have a callback that tests the status and responds when it's an error. Ниже приведен пример кода, сообщающий об ошибке, независимо от ее кода.For an example that simply reports the error message regardless of its code number, see the following code:

var dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        showNotification(asyncResult.error.code = ": " + asyncResult.error.message);
    } else {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
});

Ошибки и события в диалоговом окнеErrors and events in the dialog window

Три ошибки и события, известных по цифровым кодам, в диалоговом окне вызывают событие DialogEventReceived на главной странице.Three errors and events, known by their code numbers, in the dialog box will trigger a DialogEventReceived event in the host page.

Цифровой кодCode number ЗначениеMeaning
1200212002 Одно из следующих:One of the following:
– По URL-адресу, переданному в displayDialogAsync, не существует страницы.- No page exists at the URL that was passed to displayDialogAsync.
– Страница, переданная в метод displayDialogAsync, загружена, но выполнена попытка открыть из диалогового окна страницу, которую не удается найти или загрузить, или для которой указан URL-адрес с недопустимым синтаксисом.- The page that was passed to displayDialogAsync loaded, but the dialog box was directed to a page that it cannot find or load, or it has been directed to a URL with invalid syntax.
1200312003 Выполнена попытка открыть из диалогового окна страницу, для URL-адреса которой используется протокол HTTP. Необходим протокол HTTPS.The dialog box was directed to a URL with the HTTP protocol. HTTPS is required.
1200612006 Диалоговое окно закрыто. Скорее всего, пользователь нажал кнопку X.The dialog box was closed, usually because the user chooses the X button.

Код может назначить обработчик для события DialogEventReceived при вызове displayDialogAsync. Ниже приведен простой пример.Your code can assign a handler for the DialogEventReceived event in the call to displayDialogAsync. The following is a simple example:

var dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
    function (result) {
        dialog = result.value;
        dialog.addEventHandler(Office.EventType.DialogEventReceived, processDialogEvent);
    }
);

Ниже приведен пример обработчика для события DialogEventReceived, который создает особые сообщения об ошибках для каждого кода ошибки.For an example of a handler for the DialogEventReceived event that creates custom error messages for each error code, see the following example:

function processDialogEvent(arg) {
    switch (arg.error) {
        case 12002:
            showNotification("The dialog box has been directed to a page that it cannot find or load, or the URL syntax is invalid.");
            break;
        case 12003:
            showNotification("The dialog box has been directed to a URL with the HTTP protocol. HTTPS is required.");            break;
        case 12006:
            showNotification("Dialog closed.");
            break;
        default:
            showNotification("Unknown error in dialog box.");
            break;
    }
}

Надстройку с такой обработкой ошибок см. в статье Пример надстройки Office с Dialog API.For a sample add-in that handles errors in this way, see Office Add-in Dialog API Example.

Передача данных диалоговому окнуPass information to the dialog box

Иногда главной странице нужно передать данные в диалоговое окно. Есть два основных способа обеспечить эту возможность:Sometimes the host page needs to pass information to the dialog box. You can do this in two primary ways:

  • Добавьте параметры запроса в URL-адрес, который передается в метод displayDialogAsync.Add query parameters to the URL that is passed to displayDialogAsync.
  • Храните информацию в месте, доступном как для главного, так и для диалогового окна. У всех окон есть отдельное хранилище сеанса, но если для них используется один домен (включая номер порта), у них общее локальное хранилище.Store the information somewhere that is accessible to both the host window and dialog box. The two windows do not share a common session storage, but if they have the same domain (including port number, if any), they share a common local storage.

Использование локального хранилищаUse local storage

Чтобы использовать локальное хранилище, код вызывает метод setItem объекта window.localStorage на главной странице перед вызовом displayDialogAsync, как показано в приведенном ниже примере.To use local storage, your code calls the setItem method of the window.localStorage object in the host page before the displayDialogAsync call, as in the following example:

localStorage.setItem("clientID", "15963ac5-314f-4d9b-b5a1-ccb2f1aea248");

Код в диалоговом окне считывает элемент, когда это необходимо, как показано в приведенном ниже примере.Code in the dialog window reads the item when it's needed, as in the following example:

var clientID = localStorage.getItem("clientID");
// You can also use property syntax:
// var clientID = localStorage.clientID;

Использование параметров запросаUse query parameters

В приведенном ниже примере показано, как передавать данные с помощью параметра запроса.The following example shows how to pass data with a query parameter:

Office.context.ui.displayDialogAsync('https://myAddinDomain/myDialog.html?clientID=15963ac5-314f-4d9b-b5a1-ccb2f1aea248');

Пример, в котором используется эта техника, см. в статье Вставка диаграмм Excel с помощью Microsoft Graph в надстройке PowerPoint.For a sample that uses this technique, see Insert Excel charts using Microsoft Graph in a PowerPoint add-in.

Код в диалоговом окне может проанализировать URL-адрес и считать значение параметра.Code in your dialog window can parse the URL and read the parameter value.

Примечание

Office автоматически добавляет параметр запроса _host_info в URL-адрес, который передается displayDialogAsync. (Этот параметр добавляется после пользовательских параметров запроса, если они есть. Он не добавляется в последующие URL-адреса, которые открываются в диалоговом окне.) Корпорация Майкрософт может изменить содержимое этого значения или удалить его полностью, поэтому ваш код не должен его считывать. То же значение добавляется в хранилище сеанса диалогового окна. Ваш код не должен ни считывать это значение, ни записывать в него данные.Office automatically adds a query parameter called _host_info to the URL that is passed to displayDialogAsync. (It is appended after your custom query parameters, if any. It is not appended to any subsequent URLs that the dialog box navigates to.) Microsoft may change the content of this value, or remove it entirely, in the future, so your code should not read it. The same value is added to the dialog box's session storage. Again, your code should neither read nor write to this value.

Использование Dialog API для показа видеоUse the Dialog APIs to show a video

Чтобы показать видео в диалоговом окне:To show a video in a dialog box:

  1. Создайте страницу с единственным содержимым — элементом iframe. Атрибут src этого элемента указывает на видео из Интернета. В URL-адресе видео должен быть указан протокол HTTPS. В этой статье мы назовем эту страницу "video.dialogbox.html". Ниже приведен пример кода.Create a page whose only content is an iframe. The src attribute of the iframe points to an online video. The protocol of the video's URL must be HTTPS. In this article we'll call this page "video.dialogbox.html". The following is an example of the markup:

    <iframe class="ms-firstrun-video__player"  width="640" height="360"
        src="https://www.youtube.com/embed/XVfOe5mFbAE?rel=0&autoplay=1"
        frameborder="0" allowfullscreen>
    </iframe>
    
  2. Страница video.dialogbox.html должна находиться в том же домене, что и главная страница.The video.dialogbox.html page must be in the same domain as the host page.

  3. Используйте вызов displayDialogAsync на главной странице, чтобы открыть страницу video.dialogbox.html.Use a call of displayDialogAsync in the host page to open video.dialogbox.html.

  4. Если надстройке необходимо знать, когда пользователь закрывает диалоговое окно, зарегистрируйте обработчик для события DialogEventReceived и обработайте событие 12006. Дополнительные сведения см. в разделе Ошибки и события в диалоговом окне.If your add-in needs to know when the user closes the dialog box, register a handler for the DialogEventReceived event and handle the 12006 event. For details, see the section Errors and events in the dialog window.

Пример видео в диалоговом окне см. в статье Конструктивный шаблон размещения видео.For a sample that shows a video in a dialog box, see the video placemat design pattern.

Снимок экрана: видео в диалоговом окне надстройки

Использование Dialog API в потоке аутентификацииUse the Dialog APIs in an authentication flow

См. статью Проверка подлинности с помощью Dialog API для Office.See Authenticate with the Office Dialog API.

Использование Dialog API для Office с одностраничными приложениями и клиентской маршрутизациейUsing the Office Dialog API with single-page applications and client-side routing

Если надстройка использует клиентскую маршрутизацию подобно тому, как это делает одностраничное приложение (SPA), вы можете передавать в метод displayDialogAsync (который мы не рекомендуем использовать) не URL-адрес отдельной HTML-страницы, а URL-адрес маршрута.If your add-in uses client-side routing, as single-page applications typically do, you have the option to pass the URL of a route to the displayDialogAsync method, instead of the URL of a complete and separate HTML page.

Диалоговое окно — это новое окно с собственным контекстом выполнения.The dialog box is in a new window with its own execution context. Если вы передаете маршрут, базовая страница со всем ее кодом инициализации и начальной загрузки запускается снова в этом новом контексте, а возможным переменным присваиваются первоначальные значения в диалоговом окне.If you pass a route, your base page and all its initialization and bootstrapping code run again in this new context, and any variables are set to their initial values in the dialog window. Такой способ приводит к скачиванию и запуску второго экземпляра приложения в диалоговом окне, что частично противоречит смыслу одностраничного приложения.So this technique downloads and launches a second instance of your application in the dialog window, which partially defeats the purpose of an SPA. Кроме того, код, меняющий переменные в диалоговом окне, не меняет версию области задач этих переменных.Code that changes variables in the dialog window does not change the task pane version of the same variables. Для диалогового окна предусмотрено отдельное хранилище сеанса, недоступное из кода в области задач.Similarly, the dialog window has its own session storage, which is not accessible from code in the task pane.

Поэтому если вы передавали маршрут методу displayDialogAsync, вы в действительности запускали не одностраничное предложение, а использовали два экземпляра одного одностраничного приложения.So, if you passed a route to the displayDialogAsync method, you wouldn't really have an SPA; you'd have two instances of the same SPA. Кроме того, большая часть кода в экземпляре области задач и большая часть кода в экземпляре диалогового окна никогда не применялись в соответствующих экземплярах.Moreover, much of the code in the task pane instance would never be used in that instance and much of the code in the dialog instance would never be used in that instance. Это соответствует применению двух одностраничных приложений в одном пакете.It would be like having two SPAs in the same bundle. Если код, который нужно выполнить в диалоговом окне достаточно сложен, рекомендуется выполнить его явным образом, то есть разместить два одностраничных приложения в разных папках одного домена.If the code that you want to run in the dialog is sufficiently complex, you might want to do this explicitly; that is, have two SPAs in different folders of the same domain. Но в большинстве случаев в диалоговом окне требуется только простая логика.But in most scenarios, only simple logic is needed in the dialog. В таких случаях проект значительно упрощается благодаря размещению простой HTML-страницы с внедренным или упомянутым кодом JavaScript в домене вашего одностраничного приложения.In such cases, your project will be greatly simplified by simply hosting a simple HTML page, with embedded or referenced JavaScript, in the domain of your SPA. Передайте URL-адрес страницы в метод displayDialogAsync.Pass the URL of the page to the displayDialogAsync method. Это может означать, что вы отклоняетесь от буквальной идеи одностраничного приложения. Но как указано выше, при использовании диалогового окна вы в любом случае применяете не один экземпляр одностраничного приложения.This might mean that you are deviating from the literal idea of a single-page app; but as noted above you don't really have a single instance of an SPA anyway when you are using the dialog.