Автоматическое обновление подписи при переключении между учетными записями Exchange

  • Статья

Применение правильной подписи к сообщениям при использовании нескольких учетных записей Exchange теперь упрощается благодаря добавлению OnMessageFromChanged событий и OnAppointmentFromChanged в функцию активации на основе событий . Событие OnMessageFromChanged возникает при изменении учетной записи в поле From создаваемого сообщения, а OnAppointmentFromChanged событие возникает при изменении организатора создаваемого собрания. Эти события расширяют возможности надстроек сигнатур и позволяют им:

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

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

Примечание.

События OnMessageFromChanged и OnAppointmentFromChanged были введены в наборе требований 1.13. Сведения о поддержке клиентов для этих событий см. в разделе Поддерживаемые клиенты и платформы.

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

В следующих таблицах перечислены сочетания клиента и сервера, которые поддерживают OnMessageFromChanged события и OnAppointmentFromChanged . Выберите вкладку для соответствующего события.

Клиент Exchange Online. Локальная версия Exchange 2019 (накопительное обновление 12 или более поздняя версия) Локальная среда Exchange 2016 (накопительное обновление 22 или более поздняя версия)
Веб-браузер (современный пользовательский интерфейс)

новый Outlook в Windows (предварительная версия)		 Поддерживается Неприменимо Неприменимо
Windows (классическая версия)
Версия 2304 (сборка 16327.20248) или более поздняя		 Поддерживается Поддерживается Поддерживается
Mac
Версия 16.77.816.0 или более поздняя		 Поддерживается Неприменимо Неприменимо
iOS Неприменимо Неприменимо Неприменимо
Android Неприменимо Неприменимо Неприменимо

Предварительные условия

Чтобы протестировать пошаговое руководство, необходимо иметь по крайней мере две учетные записи Exchange.

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

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

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

  1. Откройте файл manifest.json .

  2. Добавьте следующий объект в массив extensions.runtimes. Обратите внимание на следующие особенности этой разметки.

    • MinVersion набора обязательных элементов почтового ящика настроена как "1.13", так как это самая низкая версия набора требований, поддерживающего OnMessageFromChanged событие. Дополнительные сведения см. в таблице "Поддерживаемые события" статьи Настройка надстройки Outlook для активации на основе событий.

    • Для идентификатора среды выполнения задается описательное имя "autorun_runtime".

    • Свойство "code" имеет дочернее свойство page, задается в HTML-файл, а дочернее свойство "script" — файл JavaScript. Вы создадите или измените эти файлы на последующих шагах. Office использует одно из этих значений в зависимости от платформы.

      • Классический Outlook в Windows выполняет обработчик событий в среде выполнения, доступной только для JavaScript, которая загружает файл JavaScript напрямую.
      • Outlook в Интернете и на Mac, а также новый Outlook в Windows (предварительная версия) выполняют обработчик в среде выполнения браузера, которая загружает HTML-файл. HTML-файл содержит <script> тег, который затем загружает файл JavaScript.

      Дополнительные сведения см. в разделе Среды выполнения в надстройках Office.

    • Свойство "время существования" имеет значение "short". Это означает, что среда выполнения запускается при возникновении события и завершает работу по завершении работы обработчика.

    • Существуют "действия" для запуска обработчиков событий OnMessageFromChanged и OnNewMessageCompose . Обработчики будут созданы на следующем шаге.

    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.13"
            }
        ]
    },
    "id": "autorun_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/launchevent.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onMessageFromChangedHandler",
            "type": "executeFunction",
            "displayName": "onMessageFromChangedHandler"
        },
        {
            "id": "onNewMessageComposeHandler",
            "type": "executeFunction",
            "displayName": "onNewMessageComposeHandler"
        }
    ]
}

  3. Добавьте массив autoRunEvents в качестве свойства объекта в массиве extensions. Массив autoRunEvents содержит объект со следующими ключевыми свойствами.

    • Свойство events назначает обработчики событиям OnMessageFromChanged и OnNewMessageCompose . Сведения об именах событий, используемых в унифицированном манифесте, см. в таблице "Поддерживаемые события" статьи Настройка надстройки Outlook для активации на основе событий.
    • Имя функции, указанное в actionId, должно соответствовать свойству id соответствующего объекта в ранее настроенном массиве actions.
    "autoRunEvents": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.13"
                }
            ],
            "scopes": [
                "mail"
            ]
        },
        "events": [
            {
                "type": "messageFromChanged",
                "actionId": "onMessageFromChangedHandler"
            },
            {
                "type": "newMessageComposeCreated",
                "actionId": "onNewMessageComposeHandler"
            }
        ]
    }
]

Совет

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

Обработчики событий должны быть настроены OnNewMessageCompose для событий и OnMessageFromChanged . Функция onNewMessageComposeHandler добавляет подпись в только что созданное сообщение, если оно по умолчанию еще не настроено в текущей учетной записи. При изменении onMessageFromChangedHandler учетной записи в поле From функция обновляет подпись на основе этой только что выбранной учетной записи.

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

  2. В папке ./src/launchevent создайте файл с именемlaunchevent.js.

  3. Откройте файл ./src/launchevent/launchevent.js в редакторе кода и добавьте следующий код JavaScript.

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

// The OnNewMessageCompose event handler that adds a signature to a new message.
function onNewMessageComposeHandler(event) {
    const item = Office.context.mailbox.item;

    // Check if a default Outlook signature is already configured.
    item.isClientSignatureEnabledAsync({ asyncContext: event }, (result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.log(result.error.message);
            return;
        }

        // Add a signature if there's no default Outlook signature configured.
        if (result.value === false) {
            item.body.setSignatureAsync(
                "<i>This is a sample signature.</i>",
                { asyncContext: result.asyncContext, coercionType: Office.CoercionType.Html },
                addSignatureCallback
            );
        }
    });
}

// The OnMessageFromChanged event handler that updates the signature when the email address in the From field is changed.
function onMessageFromChangedHandler(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 currently selected From account.
    item.from.getAsync({ asyncContext: event }, (result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.log(result.error.message);
            return;
        }

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

            // Add the created signature to the mail item.
            const signature = "<img src='cid:signatureIcon.png'>" + result.asyncContext.name;
            item.body.setSignatureAsync(
                signature,
                { asyncContext: result.asyncContext.event, coercionType: Office.CoercionType.Html },
                addSignatureCallback
            );
        });
    });
}

// Callback function to add a signature to the mail item.
function addSignatureCallback(result) {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        return;
    }

    console.log("Successfully added signature.");
    result.asyncContext.completed();
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to 
// map the event handler name specified in the manifest's LaunchEvent element to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
    Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
    Office.actions.associate("onMessageFromChangedHandler", onMessageFromChangedHandler);
}

Важно!

Windows. В настоящее время импорт не поддерживается в файле JavaScript, в котором реализуется обработка активации на основе событий.

Совет

Надстройки на основе событий, работающие в Outlook в Windows, не выполняют код, включенный Office.onReady() в функции и Office.initialize . Мы рекомендуем добавить логику запуска надстройки, например проверку версии Outlook пользователя, в обработчики событий.

Обновление HTML-файла команд

  1. В папке ./src/commands откройте commands.html.

  2. Добавьте следующий код под существующим тегом скрипта .

    <script type="text/javascript" src="../launchevent/launchevent.js"></script>

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

Обновление настроек конфигурации webpack

  1. В корневом каталоге проекта откройте файлwebpack.config.js .

  2. plugins Найдите массив в объекте config и добавьте следующий новый объект в начало массива.

    new CopyWebpackPlugin({
  patterns: [
    {
      from: "./src/launchevent/launchevent.js",
      to: "launchevent.js",
    },
  ],
}),

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

Проверка

  1. Выполните следующие команды в корневом каталоге проекта. При запуске npm startзапустится локальный веб-сервер (если он еще не запущен), и надстройка будет загружена неопубликованно.

    npm run build

    npm start

    Примечание.

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

  2. В предпочитаемом клиенте Outlook создайте новое сообщение. Если у вас не настроена подпись Outlook по умолчанию, надстройка добавляет ее в созданное сообщение.

    Пример подписи, добавленный в новое сообщение, если в учетной записи не настроена подпись Outlook по умолчанию.

  3. Включите поле От , если применимо. Инструкции по его включению см. в разделе "Почему отсутствует кнопка "От?" статьи Изменение учетной записи, используемой для отправки сообщений электронной почты.

  4. Выберите От, а затем выберите другую учетную запись Exchange. Кроме того, можно вручную ввести адрес электронной почты Exchange, выбрав Из>другого Email адрес. В сообщение добавляется обновленная сигнатура, заменяющая предыдущую.

    Пример обновленной подписи с логотипом при изменении учетной записи в поле From.

Устранение неполадок с надстройкой

Инструкции по устранению неполадок надстройки активации на основе событий см. в статье Устранение неполадок надстроек на основе событий и отчетов о спаме.

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

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

Поведение и ограничения событий

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

Помимо этих характеристик, следующие аспекты также применяются при активации надстройки для этих событий.

  • Событие OnMessageFromChanged поддерживается только в режиме создания сообщений, а OnAppointmentFromChanged событие поддерживается только в режиме создания встреч.
  • В Outlook в Windows поддерживается только OnMessageFromChanged событие.
  • События OnMessageFromChanged и OnAppointmentFromChanged поддерживают только учетные записи Exchange. В создаваемых сообщениях учетная запись Exchange выбирается из раскрывающегося списка Из поля или вводится в поле вручную. При составлении встреч учетная запись Exchange выбирается в раскрывающемся списке поле организатора. Если пользователь переключается на учетную запись, не относясь к Exchange, в поле От или организатор, клиент Outlook автоматически очищает подпись, заданную ранее выбранной учетной записью.
  • Поддерживаются сценарии делегирования и общего почтового ящика.
  • Событие OnAppointmentFromChanged не поддерживается в календарях групп Microsoft 365. Если пользователь переключается со своей учетной записи Exchange на учетную запись календаря группы Microsoft 365 в поле организатора, клиент Outlook автоматически очищает подпись, заданную учетной записью Exchange.
  • При переключении на другую учетную запись Exchange в поле From или organizer надстройки для ранее выбранной учетной записи прекращаются, а надстройки, связанные с только что выбранной учетной записью, загружаются перед запуском OnMessageFromChanged события или OnAppointmentFromChanged .
  • поддерживаются псевдонимы Email учетных записей. Если в поле From или organizer выбран псевдоним для текущей учетной записи, OnMessageFromChanged событие или OnAppointmentFromChanged происходит без перезагрузки надстроек учетной записи.
  • Если раскрывающийся список поле "От " или "организатор" открывается по ошибке или повторно выбрана та же учетная запись, которая отображается в поле "От " или "организатор", OnMessageFromChanged происходит событие или OnAppointmentFromChanged , но надстройки учетной записи не прекращаются и не перезагружаются.

См. также