Использование Office Dialog API в надстройках Office

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

• Войдите в систему пользователя с помощью ресурса, например Google, Facebook или удостоверения Майкрософт. Дополнительные сведения см. в статье Проверка подлинности с помощью API диалогового окна Office.
• предоставить больше места на экране (или даже весь экран) для некоторых задач в надстройке;
• Размещение видео, которое будет слишком маленьким, если оно ограничено областью задач.
• Отображение ошибки, хода выполнения или экрана ввода.

На приведенном ниже изображении показан пример диалогового окна.

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

Откройте диалоговое окно с главной страницы

Office JavaScript API включает в себя Диалоговый объекта и две функции в Office.context.ui namespace.

Чтобы открыть диалоговое окно, код ( обычно страница в области задач) вызывает метод displayDialogAsync и передает URL-адрес ресурса, который требуется открыть. Страница, на которой вызывается этот метод, называется главной страницей. Например, если вы вызываете этот метод в скрипте index.html в области задач, index.html является главной страницей диалогового окна, которое открывает метод.

Ресурс, который открывается в диалоговом окне, обычно представляет собой страницу, но это может быть метод контроллера в приложении MVC, маршрут, метод веб-службы или любой другой ресурс. В этой статье "страница" или "веб-сайт" относится к ресурсу в диалоговом окне. Ниже приведен простой пример кода.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html");

• В случае URL-адреса используется протокол HTTPS, Этот протокол является обязательным для всех страниц, загруженных в диалоговом окне, а не только для первой загруженной страницы.
• Домен диалогового окна совпадает с доменом главной страницы, которая может быть страницей в панели задач или файлом функции команды надстройки. Страница, метод контроллера или другой ресурс, который передается displayDialogAsync в метод, должны находиться в том же домене, что и хост-страница.

После загрузки первой страницы (или другого ресурса) пользователь может использовать ссылки или другой пользовательский интерфейс для перехода на любой веб-сайт (или другой ресурс), использующий ПРОТОКОЛ HTTPS. Первая страница также может сразу перенаправлять пользователя на другой сайт.

По умолчанию диалоговое окно занимает 80 % высоты и ширины экрана устройства, но можно задать различные процентные значения, передав объект конфигурации в метод, как показано в следующем примере.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });

Пример надстройки, которая делает это, см. в руководстве по Excel — завершено. Дополнительные примеры, использующие displayDialogAsync, см. в разделе Примеры кода.

Установите оба значения равными 100 %, чтобы надстройка открывалась во весь экран. Действующий максимум составляет 99,5 %, а окно по-прежнему перемещается и изменяет размер.

В окне узла можно открыть только одно диалоговое окно. При попытке открыть другое диалоговое окно возникает ошибка. Например, если пользователь открывает диалоговое окно из области задач, он не может открыть второе диалоговое окно с другой страницы в области задач. Однако при открытии диалогового окна из команды надстройки команда открывает новый (но невидимый) HTML-файл каждый раз при его выборе. Этот процесс создает новое (невидимое) основное окно, поэтому каждое такое окно может запускать собственное диалоговое окно. Дополнительные сведения см. в разделе Ошибки из displayDialogAsync.

Использование параметра производительности в Office в Интернете

Свойство displayInIframe является дополнительным свойством объекта конфигурации, передаваемого в displayDialogAsync. Если для этого свойства задано значение true , а надстройка выполняется в документе, открытом в Office в Интернете, диалоговое окно открывается как плавающий iframe, а не как независимое окно. Такой подход ускоряет открытие диалогового окна. В следующем примере показано, как использовать это свойство.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20, displayInIframe: true });

Значение по умолчанию: false. Его использование равнозначно пропуску всего свойства. Если надстройка не выполняется в Office в Интернете, displayInIframe свойство игнорируется.

Отправка сведений из диалогового окна главной странице

Код в диалоговом окне использует функцию messageParent для отправки строкового сообщения на хост-страницу. Строка может быть словом, предложением, BLOB-объектом XML, строкифицированным JSON или другими объектами, которые можно сериализовать в строку или привести к строке. Чтобы использовать messageParent метод , диалоговое окно должно сначала инициализировать API JavaScript для Office.

В следующем примере показано, как инициализировать Office JS и отправить сообщение на хост-страницу.

Office.onReady(() => {
   // Add any initialization code for your dialog here.
});

// Called when dialog signs in the user.
function userSignedIn() {
    Office.context.ui.messageParent(true.toString());
}

В следующем примере показано, как вернуть строку JSON, содержащую сведения о профиле.

function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

Эта messageParent функция является одним из двух API Office JS, которые можно вызвать в диалоговом окне. Другой API JS, который можно вызвать в диалоговом окне, — .Office.context.requirements.isSetSupported Дополнительные сведения см. в статье Указание приложений Office и требований к API. Однако в диалоговом окне этот API не поддерживается в корпоративной лицензированной бессрочной Outlook 2016 (то есть в версии MSI).

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

let dialog; // Declare dialog as global for use in later functions.
Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

Office передает объект AsyncResult в функцию обратного вызова. Он представляет результат попытки открыть диалоговое окно. Он не представляет результат каких-либо событий в диалоговом окне. Подробнее об этом различии см. в Обработка ошибок и событий.

• Для свойства value объекта asyncResult задан объект Dialog, который существует на главной странице, а не в контексте выполнения диалогового окна.
• Функция processMessage обрабатывает событие. Вы можете присвоить ей любое имя.
• Переменная dialog объявляется в более широком контексте, чем обратный вызов, так как на нее также ссылается processMessage.

В следующем примере показан простой обработчик для DialogMessageReceived события.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    showUserName(messageFromDialog.name);
}

Office передает объект arg в обработчик. Его message свойство представляет собой строку, отправляемую вызовом messageParent в диалоговом окне. В этом примере это строковое представление профиля пользователя из службы, например учетной записи Майкрософт или Google, поэтому оно десериализируется обратно в объект с JSON.parseпомощью . Реализация showUserName не отображается. Она может отображать персонализированное приветствие в области задач.

Когда взаимодействие пользователя с диалоговым окном закончится, обработчик сообщений должен закрыть диалоговое окно, как показано в этом примере.

function processMessage(arg) {
    dialog.close();
    // Add code to process the message here.
}

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

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);
        });
      }
    );

Если надстройке необходимо открыть другую страницу области задач после получения сообщения, используйте window.location.replace метод (или window.location.href) в качестве последней строки обработчика. В следующем примере показывается, как это можно сделать.

function processMessage(arg) {
    // Add code to process the message here.
    window.location.replace("/newPage.html");
    // Alternatively, use the following:
    // window.location.href = "/newPage.html";
}

Пример подобной надстройки см. в статье Вставка диаграмм Excel с помощью Microsoft Graph в надстройке PowerPoint.

Условные сообщения

Так как из диалогового окна можно отправить несколько вызовов messageParent, но на главной странице есть только один обработчик для события DialogMessageReceived, обработчику необходимо использовать условную логику, чтобы различать сообщения. Например, если диалоговое окно предлагает пользователю войти в поставщик удостоверений, например учетную запись Майкрософт или Google, оно отправляет профиль пользователя в виде сообщения. В случае сбоя проверки подлинности диалоговое окно отправляет сведения об ошибке на хост-страницу, как показано в следующем примере.

if (loginSuccess) {
    const userProfile = getProfile();
    const messageObject = { messageType: "signinSuccess", profile: userProfile };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
} else {
    const errorDetails = getError();
    const messageObject = { messageType: "signinFailure", error: errorDetails };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Что касается предыдущего примера, обратите внимание:

• Переменная loginSuccess инициализируется путем считывания HTTP-ответа от поставщика удостоверений.
• Реализация getProfile функций и getError не отображается. Они получают данные из параметра запроса или ответа HTTP.
• В зависимости от того, удалось ли выполнить вход, отправляются анонимные объекты различных типов. Оба содержат свойство messageType, но один содержит свойство profile, а другой — свойство error.

Код обработчика на главной странице использует значение свойства messageType для разветвления, как показано в приведенном ниже примере. Обратите внимание на то, что здесь используется та же функция showUserName, что и в примере выше, а функция showNotification отображает сообщение об ошибке в элементе пользовательского интерфейса на главной странице.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "signinSuccess") {
        dialog.close();
        showUserName(messageFromDialog.profile.name);
        window.location.replace("/newPage.html");
    } else {
        dialog.close();
        showNotification("Unable to authenticate user: " + messageFromDialog.error);
    }
}

Реализация showNotification не отображается. Состояние может отображаться на панели уведомлений в области задач.

Обмен сообщениями между доменами в среду выполнения узла

После открытия диалогового окна диалоговое окно или родительская среда выполнения может перейти из домена надстройки. Если происходит одно из этих действий, вызов завершается messageParent ошибкой, если в коде не указан домен родительской среды выполнения. Добавьте параметр DialogMessageOptions в вызов messageParent , чтобы указать домен. Этот объект имеет targetOrigin свойство, указывающее домен, в который должно быть отправлено сообщение. Если параметр не используется, Office предполагает, что целевой объект является тем же доменом, в котором сейчас размещается диалоговое окно.

В следующем примере показано, как использовать messageParent для отправки междоменного сообщения.

Office.context.ui.messageParent("Some message", { targetOrigin: "https://resource.contoso.com" });

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

Office.context.ui.messageParent("Some message", { targetOrigin: "*" });

Передача данных диалоговому окну

Надстройка может отправлять сообщения с главной страницы в диалоговое окно с помощью Dialog.messageChild.

Использование messageChild() с главной страницы

При вызове API диалога Office для открытия диалогового окна возвращается объект Dialog . Назначьте этот объект переменной с глобальной область, чтобы можно было ссылаться на него из других функций. В следующем примере показывается, как это можно сделать.

let dialog; // Declare as global variable.
Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html",
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

function processMessage(arg) {
    dialog.close();

    // Add code to process the message here.

}

Этот Dialog объект имеет метод messageChild , который отправляет в диалоговое окно любую строку, включая строкифицированные данные. Этот метод вызывает DialogParentMessageReceived событие в диалоговом окне. Код должен обрабатывать это событие, как показано в следующем разделе.

Рассмотрим сценарий, в котором пользовательский интерфейс диалогового окна связан с текущим активным листом Excel и положением этого листа относительно других листов. В следующем примере worksheetPropertiesChanged отправляет свойства активного листа в диалоговое окно. Данные строчены таким образом, что они могут быть переданы в messageChild.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    worksheet.load();
    await context.sync();
    worksheetPropertiesChanged(worksheet);
});

...

function worksheetPropertiesChanged(currentWorksheet) {
    const messageToDialog = JSON.stringify(currentWorksheet);
    dialog.messageChild(messageToDialog);
}

Дескриптор DialogParentMessageReceived в диалоговом окне

В JavaScript диалогового окна зарегистрируйте обработчик для DialogParentMessageReceived события с помощью метода UI.addHandlerAsync . Обычно обработчик регистрируется в функции Office.onReady или Office.initialize, как показано в следующем примере. (Более надежный пример приведен далее в этой статье.)

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(Office.EventType.DialogParentMessageReceived,onMessageFromParent);
});

Затем определите onMessageFromParent обработчик. Следующий код продолжает пример из предыдущего раздела. Обратите внимание, что Office передает аргумент обработчику, message а свойство объекта argument содержит строку с главной страницы. В этом примере сообщение перевернуто в объект, а jQuery используется для задания верхнего заголовка диалогового окна в соответствии с новым именем листа.

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

Рекомендуется проверить правильность регистрации обработчика. Это можно сделать, передав обратный вызов методу addHandlerAsync . Этот обратный вызов выполняется по завершении попытки регистрации обработчика. Используйте обработчик для регистрации или отображения ошибки, если обработчик не был успешно зарегистрирован. В следующем примере показывается, как это можно сделать. Обратите внимание, что reportError это функция, не определенная здесь, которая регистрирует или отображает ошибку.

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
        reportError(asyncResult.error.message);
    }
}

Условное обмен сообщениями с родительской страницы в диалоговое окно

Так как на главной странице может выполняться несколько messageChild вызовов, но в диалоговом окне есть только один обработчик события DialogParentMessageReceived , обработчик должен использовать условную логику для различения различных сообщений. Эту условную логику можно структурировать таким образом, чтобы точно аналогично структуре условного обмена сообщениями, когда диалоговое окно отправляет сообщение на хост-страницу, как описано в разделе Условные сообщения.

Обмен сообщениями между доменами в среду выполнения диалога

После открытия диалогового окна диалоговое окно или родительская среда выполнения может перейти из домена надстройки. Если произойдет одно из этих действий, вызовы завершаются ошибкой messageChild , если код не указывает домен среды выполнения диалога. Добавьте параметр DialogMessageOptions в вызов messageChild , чтобы указать домен. Этот объект имеет targetOrigin свойство, указывающее домен, в который должно быть отправлено сообщение. Если параметр не используется, Office предполагает, что целевой домен является тем же доменом, который сейчас размещает родительская среда выполнения.

В следующем примере показано, как использовать messageChild для отправки междоменного сообщения.

dialog.messageChild(messageToDialog, { targetOrigin: "https://resource.contoso.com" });

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

dialog.messageChild(messageToDialog, { targetOrigin: "*" });

Манифест надстройки указывает доверенные домены. В унифицированном манифесте для Microsoft 365 укажите этот домен в свойстве validDomains. В манифесте только надстройки укажите этот домен в элементе <AppDomains> .

Но среда выполнения, в которой размещается диалоговое окно, не может получить доступ к манифесту и тем самым определить, является ли домен , из которого поступает сообщение , доверенным. Чтобы определить это, DialogParentMessageReceived необходимо использовать обработчик. Объект, передаваемый обработчику, содержит домен, который в настоящее время размещен в родительском объекте в качестве своего origin свойства. В следующем примере показано, как использовать свойство .

function onMessageFromParent(arg) {
    if (arg.origin === "https://addin.fabrikam.com") {
        // Process the message.
    } else {
        // Signal the parent page to close the dialog.
        const messageObject = { messageType: "untrustedDomain" };
        Office.context.ui.messageParent(messageObject);
    }
}

Например, код может использовать функцию Office.onReady или Office.initialize для хранения массива доверенных доменов в глобальной переменной. Затем arg.origin свойство можно проверить с этим списком в обработчике.

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains]
"My trusted domain"="https://www.contoso.com"
"Another trusted domain"="https://fabrikam.com"

Закрытие диалогового окна

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

function closeButtonClick() {
    const messageObject = { messageType: "dialogClosed" };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Обработчик главной страницы для DialogMessageReceived вызовов dialog.close, как показано в этом примере. (См. предыдущие примеры, в которых показано, как dialog инициализируется объект).

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "dialogClosed") {
       dialog.close();
    }
}

Даже если вы не добавите собственный пользовательский интерфейс закрытия диалога, пользователь может закрыть диалоговое окно, выбрав X в правом верхнем углу. Это действие запускает событие DialogEventReceived. Если область узла должна знать, когда происходит это событие, она должна объявить обработчик для этого события. Дополнительные сведения см. в разделе Ошибки и события в диалоговом окне.

Не используйте window.open

Не используйте стандартный метод браузера window.open() для открытия диалоговых окон или всплывающих окон в надстройках Office. Метод window.open() не работает надежно в разных элементах управления браузером и веб-представлением, в которых выполняются надстройки Office. Вы можете столкнуться со следующими проблемами с window.open().

• Не работает в контекстах iframe. Когда надстройка запускается в Office в Интернете, область задач находится внутри iframe. По соображениям безопасности многие браузеры блокируют или строго ограничивают window.open() вызовы из iframes.
• Заблокировано блокированием всплывающих окон. Блокаторы всплывающих окон на основе браузера блокируют window.open() вызовы, а поведение зависит от браузера.
• Несогласованное поведение веб-представлений. Встроенные элементы управления веб-представления, используемые классическими приложениями Office, обрабатываются window.open() иначе, чем полные браузеры, что приводит к непредсказуемому поведению.
• Нет кроссплатформенной гарантии. Даже если window.open() работает на одной платформе (например, windows desktop), она может завершиться сбоем на другой платформе (например, Office в Интернете или Mac).

Всегда используйте API диалогового окна Office. API диалога Office (Office.context.ui.displayDialogAsync) специально разработан для согласованной работы на всех платформах Office и средах выполнения. Он предоставляет надежные функции диалога, которые работают независимо от того, запущена ли ваша надстройка в браузере, элементе управления webview или iframe.

Чтобы открыть внешние URL-адреса в отдельном окне браузера (не для проверки подлинности или обмена данными с надстройкой), используйте Office.context.ui.openBrowserWindow(url) метод , где url обычно это URL-адрес HTTPS.

Примеры кода

Во всех следующих примерах используется displayDialogAsync. Некоторые из них имеют серверы на основе NodeJS, а другие — серверы ASP.NET/IIS-based, но логика использования метода одинакова независимо от того, как реализована серверная часть надстройки.

• Учебник по Excel. Завершено
• Сценарий общей среды выполнения Excel
• Надстройка Office Microsoft Graph ASPNET
• Надстройка Office в Microsoft Graph React
• Единый вход с использованием NodeJS для надстройки Office
• Единый вход ASPNET надстройки Office
• Пример монетизации SAAS надстроек Office
• Надстройка Outlook Microsoft Graph ASPNET
• Единый вход надстроек Outlook
• Средство просмотра маркеров надстройки Outlook
• Сообщение с действиями надстройки Outlook
• Общий доступ к надстройке Outlook в OneDrive
• Надстройка PowerPoint Microsoft Graph ASPNET InsertChart

См. также

• Наборы обязательных элементов API диалоговых окон
• Рекомендации и правила Office dialog API
• Проверка подлинности с помощью API диалогового окна Office
• Использование диалогового окна Office для показа видео
• Обработка ошибок и событий в диалоговом окне "Office"
• Среды выполнения в надстройках Office