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 страницы также должны находиться в том же домене, что и родительская страница.

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

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

Область задач надстройки 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

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

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

void

Область задач надстройки Office может в любой момент открыть только одно диалоговое окно. Из команд надстроек (настраиваемые кнопки ленты или пункты меню) можно открыть одновременно несколько диалогов.
Пользователь может перемещать все диалоговые окна и изменять их размер.
При открытии все диалоговые окна размещаются по центру экрана.
Диалоговые окна отображаются поверх приложения в том порядке, в котором они были созданы.

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

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

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

DisplayDialogAsync Errors

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

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

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

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)

Параметры

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

Комментарии

Примеры

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