Office.UI interface

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

Посетите "Используйте API диалогов в Office надстройкиДополнительные сведения.

Методы

addHandlerAsync(eventType, handler, options, callback)

Добавляет обработник событий в объект с помощью указанного типа события.

addHandlerAsync(eventType, handler, callback)

Добавляет обработник событий в объект с помощью указанного типа события.

closeContainer()

Закрывает контейнер пользовательского интерфейса, в котором выполняется код JavaScript.

displayDialogAsync(startAddress, options, callback)

Отображает диалоговое окно для отображения или сбора сведений от пользователя или для облегчения веб-навигации.

displayDialogAsync(startAddress, callback)

Отображает диалоговое окно для отображения или сбора сведений от пользователя или для облегчения веб-навигации.

messageParent(message, messageOptions)

Доставляет сообщение из диалогового окна родительской странице.

openBrowserWindow(url)

Открывает окно браузера и загружает указанный URL-адрес.

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

addHandlerAsync(eventType, handler, options, callback)

Добавляет обработник событий в объект с помощью указанного типа события.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Параметры

eventType
Office.EventType

Указывает тип добавляемого события. Это должно быть Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

Добавлена функция обработера событий, единственным параметром которой является тип Office. DialogParentMessageReceivedEventArgs.

options
Office.AsyncContextOptions

Предоставляет возможность сохранения контекстных данных любого типа без изменений для использования в вызове.

callback

(result: Office.AsyncResult<void>) => void

Необязательный параметр. Функция, вызываемая при возвращении регистрации обработки, единственным параметром которой является тип Office. AsyncResult.

Возвращаемое значение

void

Комментарии

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

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

addHandlerAsync(eventType, handler, callback)

Добавляет обработник событий в объект с помощью указанного типа события.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): void;

Параметры

eventType
Office.EventType

Указывает тип добавляемого события. Это должно быть Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

Добавлена функция обработера событий, единственным параметром которой является тип Office. DialogParentMessageReceivedEventArgs.

callback

(result: Office.AsyncResult<void>) => void

Необязательный параметр. Функция, вызываемая при возвращении регистрации обработки, единственным параметром которой является тип Office. AsyncResult.

Возвращаемое значение

void

Комментарии

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

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

closeContainer()

Закрывает контейнер пользовательского интерфейса, в котором выполняется код JavaScript.

closeContainer(): void;

Возвращаемое значение

void

Комментарии

Хосты: Excel, Outlook (минимальный набор требований: почтовый ящик 1.5), PowerPoint, Word

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

Поведение этого метода определяется следующим образом:

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

  • Вызвано из области задач: области задач будет закрыта. Любой диалоговое окно, открытое displayDialogAsync, также закрывается. Если области задач поддерживают закрепление и закреплены пользователем, она будет не закреплена.

  • Вызвано из расширения модуля. Нет эффекта.

displayDialogAsync(startAddress, options, callback)

Отображает диалоговое окно для отображения или сбора сведений от пользователя или для облегчения веб-навигации.

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

Параметры

startAddress

string

Принимает начальный полный URL-адрес HTTPS, который открывается в диалоговом окантове. Не следует использовать относительные URL-адреса.

options
Office.DialogOptions

Необязательный параметр. Принимает Office. Объект DialogOptions для определения диалогового отображения.

callback

(result: Office.AsyncResult<Office.Dialog>) => void

Необязательный параметр. Принимает метод обратного вызова, обрабатывающий попытку создания диалогового окна. В случае успеха значение AsyncResult.value — это объект Диалог.

Возвращаемое значение

void

Комментарии

Хосты: Excel, Outlook, PowerPoint, Word

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

Этот метод доступен в наборе требований DialogApi для надстройок Excel, PowerPoint или Word, а также в наборе требований к почтовым ящикам 1.4 для Outlook. Дополнительные подробности о том, как указать набор требований в манифесте, см. в Office для хостов и API.

Начальная страница должна быть на том же домене, что и родительская страница (параметр startAddress). После загрузки начальной страницы можно перейти к другим доменам.

Все вызовы Office.context.ui.messageParent страниц также должны быть на том же домене, что и родительская страница.

Соображения проектирования:

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

  • В Office области задач надстройки может быть открыто только одно диалоговое окно. Одновременно можно открыть несколько диалогов из команд надстройки (настраиваемые кнопки ленты или элементы меню).

  • Пользователь может перемещать все диалоговые окна и изменять их размер.

  • При открытии все диалоговые окна размещаются по центру экрана.

  • Диалоговые окна отображаются поверх ведущего приложения в порядке создания.

Примеры применения диалогового окна:

  • Отображение страниц проверки подлинности для сбора учетных данных пользователей.

  • Отображение экрана ошибки/прогресса/ввода из команды ShowTaskpane или ExecuteAction.

  • Временное увеличение пространства, доступного пользователю для выполнения задачи.

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

displayDialogAsync Errors:

Цифровой код Значение
12004 Домен URL-адреса, переданного для отображенияDialogAsync, не доверяется. Домен должен совпадать с главной страницей (включая протокол и номер порта) или должен быть зарегистрирован в разделе `AppDomains` манифеста надстройки.
12005 URL-адрес, переданный для отображенияDialogAsync, использует протокол HTTP. Необходим протокол HTTPS. (В некоторых версиях Office сообщение об ошибке 12005 совпадает с сообщением 12004.)
12007 Диалоговое окно уже открыто из области задач. Надстройка области задач не может открывать сразу несколько диалоговых окон.
12009 Пользователь проигнорировал диалоговое окно. Эта ошибка может возникнуть в веб-версиях Office, где пользователи могут не разрешить надстройке открыть диалоговое окно.

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

Свойство Использование
AsyncResult.value Доступ к объекту Dialog.
AsyncResult.status Определяет, удалось ли выполнить операцию.
AsyncResult.error Доступ к объекту Error, который предоставляет сведения об ошибке, если операция завершилась неудачно.
AsyncResult.asyncContext Получает доступ к пользовательскому object или значению, если они переданы в качестве параметра asyncContext.

displayDialogAsync(startAddress, callback)

Отображает диалоговое окно для отображения или сбора сведений от пользователя или для облегчения веб-навигации.

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

Параметры

startAddress

string

Принимает начальный полный URL-адрес HTTPS, который открывается в диалоговом окантове. Не следует использовать относительные URL-адреса.

callback

(result: Office.AsyncResult<Office.Dialog>) => void

Необязательный параметр. Принимает метод обратного вызова, обрабатывающий попытку создания диалогового окна. В случае успеха значение AsyncResult.value — это объект Диалог.

Возвращаемое значение

void

Комментарии

Хосты: Excel, Outlook, PowerPoint, Word

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

Этот метод доступен в наборе требований DialogApi для надстройок Excel, PowerPoint или Word, а также в наборе требований к почтовым ящикам 1.4 для Outlook. Дополнительные подробности о том, как указать набор требований в манифесте, см. в Office для хостов и API.

Начальная страница должна быть на том же домене, что и родительская страница (параметр startAddress). После загрузки начальной страницы можно перейти к другим доменам.

Все вызовы Office.context.ui.messageParent страниц также должны быть на том же домене, что и родительская страница.

Соображения проектирования:

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

  • В Office области задач надстройки может быть открыто только одно диалоговое окно. Одновременно можно открыть несколько диалогов из команд надстройки (настраиваемые кнопки ленты или элементы меню).

  • Пользователь может перемещать все диалоговые окна и изменять их размер.

  • При открытии все диалоговые окна размещаются по центру экрана.

  • Диалоговые окна отображаются поверх ведущего приложения в порядке создания.

Примеры применения диалогового окна:

  • Отображение страниц проверки подлинности для сбора учетных данных пользователей.

  • Отображение экрана ошибки/прогресса/ввода из команды ShowTaskpane или ExecuteAction.

  • Временное увеличение пространства, доступного пользователю для выполнения задачи.

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

displayDialogAsync Errors:

Цифровой код Значение
12004 Домен URL-адреса, переданного для отображенияDialogAsync, не доверяется. Домен должен совпадать с главной страницей (включая протокол и номер порта) или должен быть зарегистрирован в разделе `AppDomains` манифеста надстройки.
12005 URL-адрес, переданный для отображенияDialogAsync, использует протокол HTTP. Необходим протокол HTTPS. (В некоторых версиях Office сообщение об ошибке 12005 совпадает с сообщением 12004.)
12007 Диалоговое окно уже открыто из области задач. Надстройка области задач не может открывать сразу несколько диалоговых окон.
12009 Пользователь проигнорировал диалоговое окно. Эта ошибка может возникнуть в веб-версиях Office, где пользователи могут не разрешить надстройке открыть диалоговое окно.

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

Свойство Использование
AsyncResult.value Доступ к объекту Dialog.
AsyncResult.status Определяет, удалось ли выполнить операцию.
AsyncResult.error Доступ к объекту Error, который предоставляет сведения об ошибке, если операция завершилась неудачно.
AsyncResult.asyncContext Получает доступ к пользовательскому object или значению, если они переданы в качестве параметра asyncContext.

messageParent(message, messageOptions)

Доставляет сообщение из диалогового окна родительской странице.

messageParent(message: string, messageOptions?: DialogMessageOptions): void;

Параметры

message

string

Принимает от диалогового окна сообщение, доставляемое надстройке. Все, что может быть отправлено в строку, включая JSON и XML.

messageOptions
Office.DialogMessageOptions

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

Возвращаемое значение

void

Комментарии

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

openBrowserWindow(url)

Открывает окно браузера и загружает указанный URL-адрес.

openBrowserWindow(url: string): void;

Параметры

url

string

Полный URL-адрес, который будет открыт, включая протокол (например, https) и номер порта, если таковые есть.

Возвращаемое значение

void

Комментарии

Набор требований: OpenBrowserWindowAPI 1.1