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

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

Примеры

// The following example shows how to add an event handler for the DialogParentMessageReceived event.
Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onMessageFromParent(arg) {
    const messageFromParent = JSON.parse(arg.message);
    document.querySelector('h1').textContent = messageFromParent.name;
}

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }
}

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 является объектом Dialog.

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

void

Комментарии

Приложения: Excel, Outlook, PowerPoint, Word

Наборы обязательных элементов:

Этот метод доступен в наборе обязательных элементов DialogApi для надстроек Excel, PowerPoint или Word, а также в наборе требований почтового ящика 1.4 для Outlook. Дополнительные сведения о том, как указать набор требований в манифесте, см. в статье Указание приложений Office и требований API, если вы используете XML-манифест. Если вы используете манифест Teams (предварительная версия), см. раздел Манифест Teams для надстроек Office (предварительная версия).

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

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

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

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

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

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

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

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

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

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

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

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

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

DisplayDialogAsync Errors

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

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

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

Примеры

// The following example shows how to open a dialog with a specified size. It also shows
// how to register a function to handle the message when Office.UI.messageParent() is called
// in the dialog. The implementation of the processMessage() function is omitted.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

// The following example does the same thing in TypeScript.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult: Office.AsyncResult) => {
        const dialog: Office.Dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

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 является объектом Dialog.

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

void

Комментарии

Приложения: Excel, Outlook, PowerPoint, Word

Наборы обязательных элементов:

Этот метод доступен в наборе обязательных элементов DialogApi для надстроек Excel, PowerPoint или Word, а также в наборе требований почтового ящика 1.4 для Outlook. Дополнительные сведения о том, как указать набор требований в манифесте, см. в статье Указание приложений Office и требований API, если вы используете XML-манифест. Если вы используете манифест Teams (предварительная версия), см. раздел Манифест Teams для надстроек Office (предварительная версия).

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

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

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

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

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

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

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

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

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

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

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

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

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

DisplayDialogAsync Errors

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

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

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

messageParent(message, messageOptions)

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

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

Параметры

message

string

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

messageOptions
Office.DialogMessageOptions

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

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

void

Комментарии

Наборы обязательных элементов:

  • DialogAPI

  • messageOptions Если используется параметр, также требуется DialogOrigin 1.1.

Примеры

// The following example shows how to send a JSON string to the parent. The profile object
// is returned from some website when a user signs into it.
function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

openBrowserWindow(url)

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

openBrowserWindow(url: string): void;

Параметры

url

string

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

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

void

Комментарии

Набор обязательных требований: OpenBrowserWindowAPI 1.1