Автоматическое обновление подписи при переключении между учетными записями 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 (23081600) или более поздняя |
Поддерживается | Неприменимо | Неприменимо |
iOS | Неприменимо | Неприменимо | Неприменимо |
Android | Неприменимо | Неприменимо | Неприменимо |
Предварительные условия
Чтобы протестировать пошаговое руководство, необходимо иметь по крайней мере две учетные записи Exchange.
Настройка среды
Выполните краткое руководство по Outlook, в котором создается проект надстройки с генератором Yeoman для надстроек Office.
Настройка манифеста
Откройте файл manifest.json .
Перейдите к массиву authorization.permissions.resourceSpecific. В объекте массива замените значение свойства name на MailboxItem.ReadWrite.User. Это необходимо надстройке, чтобы иметь возможность обновлять сигнатуру сообщения.
... "authorization": { "permissions": { "resourceSpecific": [ { "name": "MailboxItem.ReadWrite.User", "type": "Delegated" } ] } }, ...
Добавьте следующий объект в массив 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" } ] }
Добавьте массив 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" } ] } ]
- Свойство events назначает обработчики событиям
Совет
- Сведения о средах выполнения в надстройках см. в статье Среды выполнения в надстройках Office.
- Дополнительные сведения о манифестах надстроек Outlook см. в статье Манифесты надстроек Office.
Реализация обработчиков событий
Обработчики событий должны быть настроены OnNewMessageCompose
для событий и OnMessageFromChanged
. Функция onNewMessageComposeHandler
добавляет подпись в только что созданное сообщение, если оно по умолчанию еще не настроено в текущей учетной записи. При изменении onMessageFromChangedHandler
учетной записи в поле From функция обновляет подпись на основе этой только что выбранной учетной записи.
В том же проекте быстрого запуска перейдите в каталог ./src , а затем создайте папку с именем launchevent.
В папке ./src/launchevent создайте файл с именемlaunchevent.js.
Откройте файл ./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 Outlook, remember to // map the event handler name specified in the manifest's LaunchEvent element (with the add-in only manifest) // or the "autoRunEvents.events.actionId" property (with the unified manifest for Microsoft 365) // to its JavaScript counterpart. Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler); Office.actions.associate("onMessageFromChangedHandler", onMessageFromChangedHandler);
Важно!
Windows. В настоящее время импорт не поддерживается в файле JavaScript, в котором реализуется обработка активации на основе событий.
Совет
Надстройки на основе событий, работающие в классической версии Outlook в Windows, не выполняют код, включенный Office.onReady()
в функции и Office.initialize
. Мы рекомендуем добавить логику запуска надстройки, например проверку версии Outlook пользователя, в обработчики событий.
Обновление HTML-файла команд
В папке ./src/commands откройте commands.html.
Добавьте следующий код под существующим тегом скрипта .
<script type="text/javascript" src="../launchevent/launchevent.js"></script>
Сохраните изменения.
Обновление настроек конфигурации webpack
В корневом каталоге проекта откройте файлwebpack.config.js .
plugins
Найдите массив в объектеconfig
и добавьте следующий новый объект в начало массива.new CopyWebpackPlugin({ patterns: [ { from: "./src/launchevent/launchevent.js", to: "launchevent.js", }, ], }),
Сохраните изменения.
Проверка
Выполните следующие команды в корневом каталоге проекта. При запуске
npm start
запустится локальный веб-сервер (если он еще не запущен), и надстройка будет загружена неопубликованно.npm run build
npm start
Примечание.
Если надстройка не была автоматически загружена неопубликованным приложением, следуйте инструкциям в разделе Загрузка неопубликованных надстроек Outlook для тестирования, чтобы вручную загрузить надстройку неопубликованного приложения в Outlook.
В предпочитаемом клиенте Outlook создайте новое сообщение. Если у вас не настроена подпись Outlook по умолчанию, надстройка добавляет ее в созданное сообщение.
Включите поле От , если применимо. Инструкции по его включению см. в разделе "Почему отсутствует кнопка "От?" статьи Изменение учетной записи, используемой для отправки сообщений электронной почты.
Выберите От, а затем выберите другую учетную запись Exchange. Кроме того, можно вручную ввести адрес электронной почты Exchange, выбрав Из>другого Email адрес. В сообщение добавляется обновленная сигнатура, заменяющая предыдущую.
Если вы хотите остановить локальный веб-сервер и удалить надстройку, следуйте применимым инструкциям:
Чтобы остановить сервер, выполните следующую команду. Если вы использовали
npm start
, следующая команда также должна удалить надстройку.npm stop
Если вы вручную загрузили неопубликованную надстройку, см. статью Удаление неопубликоченной надстройки.
Устранение неполадок с надстройкой
Инструкции по устранению неполадок надстройки активации на основе событий см. в статье Устранение неполадок надстроек на основе событий и отчетов о спаме.
Развертывание для пользователей
Как и другие надстройки на основе событий, надстройки, использующие 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
, но надстройки учетной записи не прекращаются и не перезагружаются.
См. также
Office Add-ins