Реализация активации на основе событий в мобильных надстройках Outlook

Статья
02/29/2024

С помощью функции активации на основе событий разработайте надстройку для автоматической активации и завершения операций при возникновении определенных событий в Outlook в Android или iOS, например при создании нового сообщения.

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

Сведения о том, как реализовать надстройку на основе событий для Outlook в Windows (классическая и новая (предварительная версия)), на Mac и в Интернете, см. в статье Настройка надстройки Outlook для активации на основе событий.

Примечание.

Outlook в Android и в iOS поддерживает только набор обязательных почтовых ящиков 1.5. Однако для поддержки функции активации на основе событий некоторые API из более поздних наборов требований были включены на мобильных клиентах. Дополнительные сведения об этом исключении см. в разделе Дополнительные поддерживаемые API.

Поддерживаемые клиенты

Надстройка, разрабатываемая в этом пошаговом руководстве, поддерживается в Outlook для Android и iOS, начиная с версии 4.2352.0. Для запуска этой функции требуется подписка На Microsoft 365.

Настройка среды

Выполните краткое руководство по Outlook, в котором создается проект надстройки с генератором Yeoman для надстроек Office.

Настройка манифеста

Примечание.

Манифест Microsoft 365 (предварительная версия) в настоящее время не поддерживается на мобильных устройствах.

Чтобы включить надстройку на основе событий в Outlook Mobile, необходимо настроить следующие элементы в VersionOverridesV1_1 узле манифеста.

В элементе Runtimes укажите HTML-файл, который ссылается на файл JavaScript для обработки событий.
Добавьте элемент MobileFormFactor , чтобы сделать надстройку доступной в Outlook Mobile.
Задайте для xsi:type элемента ExtensionPoint значение LaunchEvent. Это включает функцию активации на основе событий в надстройке Outlook для мобильных устройств.
В элементе LaunchEvent задайте для TypeOnNewMessageCompose и укажите имя функции JavaScript обработчика событий в атрибуте FunctionName .

В редакторе кода откройте созданный проект быстрого запуска.
Откройте файлmanifest.xml , расположенный в корне проекта.

Выберите весь <узел VersionOverrides> (включая открытые и закрытые теги) и замените его следующим XML-кодом.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
    <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
        <Requirements>
            <bt:Sets DefaultMinVersion="1.5">
                <bt:Set Name="Mailbox"/>
            </bt:Sets>
        </Requirements>
        <Hosts>
            <Host xsi:type="MailHost">
                <!-- The HTML file that references or contains the JavaScript event handlers.
                    This is used by Outlook on mobile devices. -->
                <Runtimes>
                    <Runtime resid="WebViewRuntime.Url">
                    </Runtime>
                </Runtimes>
                <!-- Defines the add-in for Outlook on Windows (classic and new (preview)), on Mac, and on the web. -->
                <DesktopFormFactor>
                    <FunctionFile resid="Commands.Url"/>
                    <ExtensionPoint xsi:type="MessageReadCommandSurface">
                        <OfficeTab id="TabDefault">
                            <Group id="msgReadGroup">
                                <Label resid="GroupLabel"/>
                                <Control xsi:type="Button" id="msgReadOpenPaneButton">
                                    <Label resid="TaskpaneButton.Label"/>
                                    <Supertip>
                                        <Title resid="TaskpaneButton.Label"/>
                                        <Description resid="TaskpaneButton.Tooltip"/>
                                    </Supertip>
                                    <Icon>
                                        <bt:Image size="16" resid="Icon.16x16"/>
                                        <bt:Image size="32" resid="Icon.32x32"/>
                                        <bt:Image size="80" resid="Icon.80x80"/>
                                    </Icon>
                                    <Action xsi:type="ShowTaskpane">
                                        <SourceLocation resid="Taskpane.Url"/>
                                    </Action>
                                </Control>
                                <Control xsi:type="Button" id="ActionButton">
                                    <Label resid="ActionButton.Label"/>
                                    <Supertip>
                                        <Title resid="ActionButton.Label"/>
                                        <Description resid="ActionButton.Tooltip"/>
                                    </Supertip>
                                    <Icon>
                                        <bt:Image size="16" resid="Icon.16x16"/>
                                        <bt:Image size="32" resid="Icon.32x32"/>
                                        <bt:Image size="80" resid="Icon.80x80"/>
                                    </Icon>
                                    <Action xsi:type="ExecuteFunction">
                                        <FunctionName>action</FunctionName>
                                    </Action>
                                </Control>
                            </Group>
                        </OfficeTab>
                    </ExtensionPoint>
                </DesktopFormFactor>
                <!-- Defines the add-in for Outlook mobile. -->
                <MobileFormFactor>
                    <!-- Configures event-based activation. -->
                    <ExtensionPoint xsi:type="LaunchEvent">
                        <LaunchEvents>
                            <LaunchEvent Type="OnNewMessageCompose" FunctionName="onNewMessageComposeHandler"/>
                        </LaunchEvents>
                        <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
                        <SourceLocation resid="WebViewRuntime.Url"/>
                    </ExtensionPoint>
                </MobileFormFactor>
            </Host>
        </Hosts>
        <!-- This manifest uses a fictitious web server, contoso.com, to host the add-in's files.
             Replace these instances with the information of the web server that hosts your add-in's files. -->
        <Resources>
            <bt:Images>
                <bt:Image id="Icon.16x16" DefaultValue="https://contoso.com/assets/icon-16.png"/>
                <bt:Image id="Icon.32x32" DefaultValue="https://contoso.com/assets/icon-32.png"/>
                <bt:Image id="Icon.80x80" DefaultValue="https://contoso.com/assets/icon-80.png"/>
            </bt:Images>
            <bt:Urls>
                <bt:Url id="Commands.Url" DefaultValue="https://contoso.com/commands.html"/>
                <bt:Url id="Taskpane.Url" DefaultValue="https://contoso.com/taskpane.html"/>
                <bt:Url id="WebViewRuntime.Url" DefaultValue="https://contoso.com/commands.html"/>
            </bt:Urls>
            <bt:ShortStrings>
                <bt:String id="GroupLabel" DefaultValue="Event-based activation on mobile"/>
                <bt:String id="TaskpaneButton.Label" DefaultValue="Show Taskpane"/>
                <bt:String id="ActionButton.Label" DefaultValue="Perform an action"/>
            </bt:ShortStrings>
            <bt:LongStrings>
                <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Opens a pane displaying all available properties."/>
                <bt:String id="ActionButton.Tooltip" DefaultValue="Perform an action when clicked."/>
            </bt:LongStrings>
        </Resources>
    </VersionOverrides>
</VersionOverrides>

Сохраните изменения.

Совет

Дополнительные сведения о манифестах надстроек Outlook см. в разделах Манифест надстроек Office и Добавление поддержки команд надстроек в Outlook на мобильных устройствах.

Реализация обработчика событий

Чтобы разрешить надстройке выполнять задачи при возникновении OnNewMessageCompose события, необходимо реализовать обработчик событий JavaScript. В этом разделе вы создадите функцию onNewMessageComposeHandler , которая добавляет сигнатуру в новое создаваемое сообщение, а затем отобразит сообщение для уведомления о добавлении подписи.

В том же проекте быстрого запуска перейдите в каталог ./src , а затем создайте папку с именем launchevent.
В папке ./src/launchevent создайте файл с именемlaunchevent.js.

Откройте созданный файлlaunchevent.js и добавьте следующий код JavaScript.

/*
* Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
* See LICENSE in the project root for license information.
*/

// Add start-up logic code here, if any.
Office.onReady();

function onNewMessageComposeHandler(event) {
    const item = Office.context.mailbox.item;
    const signatureIcon = "iVBORw0KGgoAAAANSUhEUgAAACcAAAAnCAMAAAC7faEHAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAzUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKMFRskAAAAQdFJOUwAQIDBAUGBwgI+fr7/P3+8jGoKKAAAACXBIWXMAAA7DAAAOwwHHb6hkAAABT0lEQVQ4T7XT2ZalIAwF0DAJhMH+/6+tJOQqot6X6joPiouNBo3w9/Hd6+hrYnUt6vhLcjEAJevVW0zJxABSlcunhERpjY+UKoNN5+ZgDGu2onNz0OngjP2FM1VdyBW1LtvGeYrBLs7U5I1PTXZt+zifcS3Icw2GcS3vxRY3Vn/iqx31hUyTnV515kdTfbaNhZLI30AceqDiIo4tyKEmJpKdP5M4um+nUwfDWxAXdzqMNKQ14jLdL5ntXzxcRF440mhS6yu882Kxa30RZcUIjTCJg7lscsR4VsMjfX9Q0Vuv/Wd3YosD1J4LuSRtaL7bzXGN1wx2cytUdncDuhA3fu6HPTiCvpQUIjZ3sCcHVbvLtbNTHlysx2w9/s27m9gEb+7CTri6hR1wcTf2gVf3wBRe3CMbcHYvTODkXhnD0+178K/pZ9+n/C1ru/2HAPwAo7YM1X4+tLMAAAAASUVORK5CYII=";

    // Get the sender's account information.
    item.from.getAsync((result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.log(result.error.message);
            event.completed();
            return;
        }

        // Create a signature based on the sender's information.
        const name = result.value.displayName;
        const options = { asyncContext: name, isInline: true };
        item.addFileAttachmentFromBase64Async(signatureIcon, "signatureIcon.png", options, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                console.log(result.error.message);
                event.completed();
                return;
            }

            // Add the created signature to the message.
            const signature = "<img src='cid:signatureIcon.png'>" + result.asyncContext;
            item.body.setSignatureAsync(signature, { coercionType: Office.CoercionType.Html }, (result) => {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    console.log(result.error.message);
                    event.completed();
                    return;
                }

                // Show a notification when the signature is added to the message.
                // Important: Only the InformationalMessage type is supported in Outlook mobile at this time.
                const notification = {
                    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
                    message: "Company signature added.",
                    icon: "none",
                    persistent: false                        
                };
                item.notificationMessages.addAsync("signature_notification", notification, (result) => {
                    if (result.status === Office.AsyncResultStatus.Failed) {
                        console.log(result.error.message);
                        event.completed();
                        return;
                    }

                    event.completed();
                });
            });
        });
    });
}

Сохраните изменения.

Добавление ссылки на файл JavaScript для обработки событий

Убедитесь, что HTML-файл, указанный в элементе <Runtime> манифеста, содержит ссылку на файл JavaScript, содержащий обработчик событий.

Перейдите в папку ./src/commands , а затем откройте commands.html.
Непосредственно перед закрывающим тегом головки (</head>) добавьте запись скрипта для файла JavaScript, содержащего обработчик событий.
```
<script type="text/javascript" src="../launchevent/launchevent.js"></script>
```
Сохраните изменения.

Тестирование и проверка надстройки

Следуйте инструкциям по тестированию и проверке надстройки.
Загрузите неопубликованную надстройку в Outlook в Windows (классическая или новая (предварительная версия)), на Mac или в Интернете.
Откройте Outlook в Android или iOS. Если на вашем устройстве уже открыт Outlook, перезапустите его.
Создайте новое сообщение. Надстройка на основе событий добавляет подпись в сообщение. Если у вас есть подпись, сохраненная на мобильном устройстве, она будет кратко отображаться в создаваемом сообщении, но будет немедленно заменена подписью, добавленной надстройкой.

Поведение и ограничения

При разработке надстройки на основе событий для Outlook Mobile учитывайте следующие особенности поведения и ограничения.

OnNewMessageCompose В настоящее время в Outlook Mobile поддерживается только событие. Это событие возникает при создании нового сообщения (включая ответить, ответить всем и пересылать). Событие OnNewMessageCompose не возникает при редактировании существующего черновика.
Так как ожидается, что надстройки на основе событий будут короткими и упрощенными, надстройка может работать не более 60 секунд с момента ее активации. Чтобы сообщить о том, что надстройка завершила обработку события, обработчик событий должен вызвать метод event.completed . Операция надстройки также завершается, когда пользователь закрывает окно создания или отправляет сообщение.
Одновременно может выполняться только одна надстройка. Если в учетной записи пользователя установлено несколько надстроек на основе событий, они будут выполняться последовательно.
Если вы коснитесь и удерживаете значок Outlook на мобильном устройстве, а затем выберите Создать почту , чтобы создать новое сообщение, надстройка на основе событий может занять несколько секунд, чтобы инициализировать и завершить обработку события.
Если в создаваемое сообщение не внесены изменения, черновик не будет сохранен, даже если надстройка на основе событий добавляет подпись с помощью метода Office.context.mailbox.item.body.setSignatureAsync .
В надстройке на основе событий, которая управляет сигнатурами, если выбрать Ответить в нижней части сообщения, надстройка активирует и добавляет подпись в сообщение. Однако подпись не будет видна в текущем представлении. Чтобы просмотреть сообщение с добавленной подписью, разверните окно создания до полноэкранного режима.
Чтобы улучшить функциональность надстройки, можно использовать поддерживаемые API из более поздних наборов требований в режиме создания. Дополнительные сведения см. в разделе Дополнительные поддерживаемые API.

Дополнительные поддерживаемые API

Хотя Outlook Mobile поддерживает API до набора обязательных для почтовых ящиков 1.5, для дальнейшего расширения возможностей надстройки на основе событий в Outlook Mobile дополнительные API из более поздних наборов требований теперь поддерживаются в режиме создания.

Дополнительные сведения об API-интерфейсах, поддерживаемых в Outlook на мобильных устройствах, см. в статье API JavaScript, поддерживаемые в Outlook на мобильных устройствах.

Развертывание для пользователей

Надстройки на основе событий должны развертываться администратором организации. Инструкции по развертыванию надстройки с помощью Центр администрирования Microsoft 365 см. в разделе "Развертывание для пользователей" статьи Настройка надстройки Outlook для активации на основе событий.