Office.UI interface

Ссылка

Пакет:: office

Предоставляет объекты и методы для создания компонентов пользовательского интерфейса, таких как диалоговые окна, и управления ими в надстройках 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

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

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

void

Примеры

// 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

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

Примеры

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();

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

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

Важно!

Начальная страница должна находиться в том же домене, что и родительская страница (параметр startAddress). После загрузки начальной страницы можно перейти к другим доменам.
Все вызовы Office.context.ui.messageParent страницы также должны находиться в том же домене, что и родительская страница.
Сведения о правилах, ограничениях и рекомендациях для API диалога Office см. в статье Рекомендации и правила для API диалога Office.
Сведения об ошибках и способах их обработки см. в разделе Обработка ошибок и событий в диалоговом окне Office.
В Outlook в Интернете и новом Outlook в Windows не устанавливайте свойство window.name при настройке диалогового окна в надстройке. Свойство window.name используется этими клиентами Outlook для поддержания функциональности перенаправлений страниц.
В функции обратного вызова, переданной методу 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

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

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

void

Начальная страница должна находиться в том же домене, что и родительская страница (параметр startAddress). После загрузки начальной страницы можно перейти к другим доменам.
Все вызовы Office.context.ui.messageParent страницы также должны находиться в том же домене, что и родительская страница.
Сведения о правилах, ограничениях и рекомендациях для API диалога Office см. в статье Рекомендации и правила для API диалога Office.
Сведения об ошибках и способах их обработки см. в разделе Обработка ошибок и событий в диалоговом окне Office.
В Outlook в Интернете и новом Outlook в Windows не устанавливайте свойство window.name при настройке диалогового окна в надстройке. Свойство window.name используется этими клиентами Outlook для поддержания функциональности перенаправлений страниц.
В функции обратного вызова, переданной методу 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

Примеры

// 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-адрес, который необходимо открыть, включая протокол (http или https) и номер порта, если он есть. Другие протоколы, такие как mailto, не поддерживаются.

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

void

Примеры

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();

Поделиться через

Office.UI interface

Комментарии

Примеры

Методы

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

addHandlerAsync(eventType, handler, options, callback)

Параметры

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

Комментарии

addHandlerAsync(eventType, handler, callback)

Параметры

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

Комментарии

Примеры

closeContainer()

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

Комментарии

Примеры

displayDialogAsync(startAddress, options, callback)

Параметры

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

Комментарии

Примеры

displayDialogAsync(startAddress, callback)

Параметры

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

Комментарии

messageParent(message, messageOptions)

Параметры

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

Комментарии

Примеры

openBrowserWindow(url)

Параметры

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

Комментарии

Примеры

Дополнительные ресурсы