Office.UI interface

Предоставляет объекты и методы, которые можно использовать для создания компонентов ПОЛЬЗОВАТЕЛЬСКОГО интерфейса, например диалоговых окон, в надстройках Office и управления ими.Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes, in your Office Add-ins.

Посетите страницу "Использование API диалогОвых окон в надстройках OfficeVisit "Use the Dialog API in your Office Add-ins"для получения дополнительных сведений." for more information.

Методы

closeContainer()

Закрывает контейнер пользовательского интерфейса, в котором выполняется код JavaScript.Closes the UI container where the JavaScript is executing.

displayDialogAsync(startAddress, options, callback)

Отображает диалоговое окно для отображения или сбора сведений о пользователе или для упрощения веб-навигации.Displays a dialog to show or collect information from the user or to facilitate Web navigation.

displayDialogAsync(startAddress, callback)

Отображает диалоговое окно для отображения или сбора сведений о пользователе или для упрощения веб-навигации.Displays a dialog to show or collect information from the user or to facilitate Web navigation.

messageParent(message)

Доставляет сообщение из диалогового окна родительской странице. Страница, вызывающая этот API, и родительская страница должны быть в одном домене.Delivers a message from the dialog box to its parent/opener page. The page calling this API must be on the same domain as the parent.

Сведения о методе

closeContainer()

Закрывает контейнер пользовательского интерфейса, в котором выполняется код JavaScript.Closes the UI container where the JavaScript is executing.

closeContainer(): void;

Возвраты

void

Комментарии

Hosts: Excel, Word, PowerPoint, Outlook (минимальный набор обязательных элементов: Mailbox 1,5)Hosts: Excel, Word, PowerPoint, Outlook (Minimum requirement set: Mailbox 1.5)

Набор требований: DialogAPIRequirement set: DialogAPI

Поведение этого метода задается следующим образом:The behavior of this method is specified by the following:

  • Вызывается из кнопки команды без ПОЛЬЗОВАТЕЛЬСКОГО интерфейса: не оказывает никакого действия.Called from a UI-less command button: No effect. Все диалоговые окна, открытые с помощью метода displayDialogAsync, останутся открытыми.Any dialog opened by displayDialogAsync will remain open.

  • Вызывается из области задач: область задач будет закрыта.Called from a task pane: The task pane will close. Все диалоговые окна, открываемые displayDialogAsync, также будут закрыты.Any dialog opened by displayDialogAsync will also close. Если область задач поддерживает закрепление и была закреплена пользователем, она будет незакрепленной.If the task pane supports pinning and was pinned by the user, it will be un-pinned.

  • Вызывается из расширения модуля: не оказывает никакого действия.Called from a module extension: No effect.

displayDialogAsync(startAddress, options, callback)

Отображает диалоговое окно для отображения или сбора сведений о пользователе или для упрощения веб-навигации.Displays a dialog to show or collect information from the user or to facilitate Web navigation.

displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): void;

Параметры

startAddress
string

Принимает исходный URL-адрес HTTPS, который открывается в диалоговом окне.Accepts the initial HTTPS URL that opens in the dialog.

options
Office.DialogOptions

Необязательно.Optional. Принимает объект Office. диалогоптионс , который определяет отображение диалогового окна.Accepts an Office.DialogOptions object to define dialog display.

callback
(result: AsyncResult<Dialog>) => void

Необязательно.Optional. Принимает метод обратного вызова, обрабатывающий попытку создания диалогового окна.Accepts a callback method to handle the dialog creation attempt. В случае успешного выполнения AsyncResult. Value — это объект Dialog.If successful, the AsyncResult.value is a Dialog object.

Возвраты

void

Комментарии

Узлы: Word, Excel, Outlook, PowerPointHosts: Word, Excel, Outlook, PowerPoint

Наборы требований:Requirement sets:

Этот метод доступен в наборе обязательных элементов DialogAPI для надстроек Word, Excel или PowerPoint, а также в наборе обязательных элементов Mailbox 1.4 для Outlook.This method is available in the DialogApi requirement set for Word, Excel, or PowerPoint add-ins, and in the Mailbox requirement set 1.4 for Outlook. Дополнительные сведения о том, как задать набор обязательных элементов в манифесте, можно узнать в статье Указание ведущих приложений Office и требований к APIFor more on how to specify a requirement set in your manifest, see Specify Office hosts and API requirements.

Начальная страница должна находиться в том же домене, что и родительская страница (параметр Стартаддресс).The initial page must be on the same domain as the parent page (the startAddress parameter). После загрузки начальной страницы можно перейти к другим доменам.After the initial page loads, you can go to other domains.

Вызов office.context.ui.messageParent любой страницы также должен находиться в том же домене, что и родительская страница.Any page calling office.context.ui.messageParent must also be on the same domain as the parent page.

Рекомендациипо проектированию:Design considerations:

К диалоговым окнам применяются следующие рекомендации по оформлению:The following design considerations apply to dialog boxes:

  • В области задач надстройки Office в любой момент времени может быть открыто только одно диалоговое окно.An Office Add-in task pane can have only one dialog box open at any time. С помощью команд надстроек (настраиваемых кнопок ленты или пунктов меню) можно одновременно открыть несколько диалоговых окон.Multiple dialogs can be open at the same time from Add-in Commands (custom ribbon buttons or menu items).

  • Пользователь может перемещать все диалоговые окна и изменять их размер.Every dialog box can be moved and resized by the user.

  • При открытии все диалоговые окна размещаются по центру экрана.Every dialog box is centered on the screen when opened.

  • Диалоговые окна отображаются поверх ведущего приложения в порядке создания.Dialog boxes appear on top of the host application and in the order in which they were created.

Примеры применения диалогового окна:Use a dialog box to:

  • Отображение страниц проверки подлинности для сбора учетных данных пользователей.Display authentication pages to collect user credentials.

  • Отобразить сообщение об ошибке/ходе выполнения и ввод данных из команды ShowTaskpane или ExecuteAction.Display an error/progress/input screen from a ShowTaskpane or ExecuteAction command.

  • Временное увеличение пространства, доступного пользователю для выполнения задачи.Temporarily increase the surface area that a user has available to complete a task.

Не используйте диалоговое окно для работы с документом. Используйте область задач.Do not use a dialog box to interact with a document. Use a task pane instead.

Шаблон, который можно использовать для создания диалогового окна, см. в репозитории шаблонов на сайте GitHub.For a design pattern that you can use to create a dialog box, see Client Dialog in the Office Add-in UX Design Patterns repository on GitHub.

ошибки displayDialogAsync:displayDialogAsync Errors:

Цифровой кодCode number ЗначениеMeaning
1200412004 Домен URL-адреса, переданный в displayDialogAsync, не является доверенным.The domain of the URL passed to displayDialogAsync is not trusted. Домен должен совпадать с главной страницей (включая протокол и номер порта) или должен быть зарегистрирован в разделе манифеста надстройки.The domain must be either the same domain as the host page (including protocol and port number), or it must be registered in the section of the add-in manifest.
1200512005 URL-адрес, переданный в displayDialogAsync, использует протокол HTTP.The URL passed to displayDialogAsync uses the HTTP protocol. Необходим протокол HTTPS.HTTPS is required. (В некоторых версиях Office сообщение об ошибке 12005 совпадает с сообщением 12004.)(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 the task pane. A task pane add-in 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, чтобы получить следующие сведения.In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult object to return the following information.

СвойствоProperty Использовать дляUse to
AsyncResult.valueAsyncResult.value Доступ к объекту Dialog.Access the Dialog object.
AsyncResult.statusAsyncResult.status Определяет, удалось ли выполнить операцию.Determine the success or failure of the operation.
AsyncResult.errorAsyncResult.error Доступ к объекту Error, который предоставляет сведения об ошибке, если операция завершилась неудачно.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextAsyncResult.asyncContext Получает доступ к пользовательскому object или значению, если они переданы в качестве параметра asyncContext.Access your user-defined object or value, if you passed one as the asyncContext parameter.

displayDialogAsync(startAddress, callback)

Отображает диалоговое окно для отображения или сбора сведений о пользователе или для упрощения веб-навигации.Displays a dialog to show or collect information from the user or to facilitate Web navigation.

displayDialogAsync(startAddress: string, callback?: (result: AsyncResult<Dialog>) => void): void;

Параметры

startAddress
string

Принимает исходный URL-адрес HTTPS, который открывается в диалоговом окне.Accepts the initial HTTPS URL that opens in the dialog.

callback
(result: AsyncResult<Dialog>) => void

Необязательно.Optional. Принимает метод обратного вызова, обрабатывающий попытку создания диалогового окна.Accepts a callback method to handle the dialog creation attempt. В случае успешного выполнения AsyncResult. Value — это объект Dialog.If successful, the AsyncResult.value is a Dialog object.

Возвраты

void

Комментарии

Hosts: Excel, Outlook, PowerPoint, WordHosts: Excel, Outlook, PowerPoint, Word

Наборы требований:Requirement sets:

Этот метод доступен в наборе обязательных элементов DialogAPI для надстроек Word, Excel или PowerPoint, а также в наборе обязательных элементов Mailbox 1.4 для Outlook.This method is available in the DialogApi requirement set for Word, Excel, or PowerPoint add-ins, and in the Mailbox requirement set 1.4 for Outlook. Дополнительные сведения о том, как задать набор обязательных элементов в манифесте, можно узнать в статье Указание ведущих приложений Office и требований к APIFor more on how to specify a requirement set in your manifest, see Specify Office hosts and API requirements.

Начальная страница должна находиться в том же домене, что и родительская страница (параметр Стартаддресс).The initial page must be on the same domain as the parent page (the startAddress parameter). После загрузки начальной страницы можно перейти к другим доменам.After the initial page loads, you can go to other domains.

Вызов office.context.ui.messageParent любой страницы также должен находиться в том же домене, что и родительская страница.Any page calling office.context.ui.messageParent must also be on the same domain as the parent page.

Рекомендациипо проектированию:Design considerations:

К диалоговым окнам применяются следующие рекомендации по оформлению:The following design considerations apply to dialog boxes:

  • В области задач надстройки Office в любой момент времени может быть открыто только одно диалоговое окно.An Office Add-in task pane can have only one dialog box open at any time. С помощью команд надстроек (настраиваемых кнопок ленты или пунктов меню) можно одновременно открыть несколько диалоговых окон.Multiple dialogs can be open at the same time from Add-in Commands (custom ribbon buttons or menu items).

  • Пользователь может перемещать все диалоговые окна и изменять их размер.Every dialog box can be moved and resized by the user.

  • При открытии все диалоговые окна размещаются по центру экрана.Every dialog box is centered on the screen when opened.

  • Диалоговые окна отображаются поверх ведущего приложения в порядке создания.Dialog boxes appear on top of the host application and in the order in which they were created.

Примеры применения диалогового окна:Use a dialog box to:

  • Отображение страниц проверки подлинности для сбора учетных данных пользователей.Display authentication pages to collect user credentials.

  • Отобразить сообщение об ошибке/ходе выполнения и ввод данных из команды ShowTaskpane или ExecuteAction.Display an error/progress/input screen from a ShowTaskpane or ExecuteAction command.

  • Временное увеличение пространства, доступного пользователю для выполнения задачи.Temporarily increase the surface area that a user has available to complete a task.

Не используйте диалоговое окно для работы с документом. Используйте область задач.Do not use a dialog box to interact with a document. Use a task pane instead.

Шаблон, который можно использовать для создания диалогового окна, см. в репозитории шаблонов на сайте GitHub.For a design pattern that you can use to create a dialog box, see Client Dialog in the Office Add-in UX Design Patterns repository on GitHub.

ошибки displayDialogAsync:displayDialogAsync Errors:

Цифровой кодCode number ЗначениеMeaning
1200412004 Домен URL-адреса, переданный в displayDialogAsync, не является доверенным.The domain of the URL passed to displayDialogAsync is not trusted. Домен должен совпадать с главной страницей (включая протокол и номер порта) или должен быть зарегистрирован в разделе манифеста надстройки.The domain must be either the same domain as the host page (including protocol and port number), or it must be registered in the section of the add-in manifest.
1200512005 URL-адрес, переданный в displayDialogAsync, использует протокол HTTP.The URL passed to displayDialogAsync uses the HTTP protocol. Необходим протокол HTTPS.HTTPS is required. (В некоторых версиях Office сообщение об ошибке 12005 совпадает с сообщением 12004.)(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 the task pane. A task pane add-in 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, чтобы получить следующие сведения.In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult object to return the following information.

СвойствоProperty Использовать дляUse to
AsyncResult.valueAsyncResult.value Доступ к объекту Dialog.Access the Dialog object.
AsyncResult.statusAsyncResult.status Определяет, удалось ли выполнить операцию.Determine the success or failure of the operation.
AsyncResult.errorAsyncResult.error Доступ к объекту Error, который предоставляет сведения об ошибке, если операция завершилась неудачно.Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContextAsyncResult.asyncContext Получает доступ к пользовательскому object или значению, если они переданы в качестве параметра asyncContext.Access your user-defined object or value, if you passed one as the asyncContext parameter.

messageParent(message)

Доставляет сообщение из диалогового окна родительской странице. Страница, вызывающая этот API, и родительская страница должны быть в одном домене.Delivers a message from the dialog box to its parent/opener page. The page calling this API must be on the same domain as the parent.

messageParent(message: boolean | string): void;

Параметры

message
boolean | string

Принимает от диалогового окна сообщение, доставляемое надстройке.Accepts a message from the dialog to deliver to the add-in. Помимо логического значения могут быть отправлены все данные, которые могут быть сериализованы в строку, включая JSON и XML.In addition to a boolean, anything that can serialized to a string including JSON and XML can be sent.

Возвраты

void

Комментарии

Набор требований: DialogAPIRequirement set: DialogAPI