Автоматическое проверка для вложения перед отправкой сообщения

  • Статья

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

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

Примечание.

События OnMessageSend и OnAppointmentSend были введены в наборе требований 1.12. Сведения о том, поддерживает ли клиент Outlook эти события, см. в разделе Поддерживаемые клиенты и платформы.

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

Перед началом пошагового руководства убедитесь, что клиент Outlook поддерживает функцию смарт-оповещений. Рекомендации см. в разделе Поддерживаемые клиенты и платформы.

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

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

Чтобы настроить манифест, выберите вкладку для используемого типа манифеста.

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

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

    • Параметр minVersion набора обязательных элементов почтового ящика имеет значение "1.12", так как в таблице поддерживаемых событий указано, что это самая низкая версия набора требований, поддерживающая OnMessageSend событие.
    • Для идентификатора среды выполнения задается описательное имя "autorun_runtime".
    • Свойство "code" имеет дочернее свойство page, для которого задано значение HTML-файла, и дочернее свойство script, для которого задается файл JavaScript. Вы создадите или измените эти файлы на последующих шагах. Office использует одно из этих значений или другое в зависимости от платформы.
    • Свойство "время существования" имеет значение "short", что означает, что среда выполнения запускается при активации события и завершает работу по завершении обработчика. (В некоторых редких случаях среда выполнения завершает работу до завершения обработчика. См . раздел Среды выполнения в надстройках Office.)
    • Существует действие для запуска обработчика OnMessageSend для события. Вы создадите функцию обработчика на следующем шаге.
     {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.12"
            }
        ]
    },
    "id": "autorun_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/launchevent.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onMessageSendHandler",
            "type": "executeFunction",
            "displayName": "onMessageSendHandler"
        }
    ]
}

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

    "autoRunEvents": [

]

  4. Добавьте следующий объект в массив autoRunEvents. Обратите внимание на следующие особенности этого кода:

    • Объект события назначает событию OnMessageSend функцию обработчика (используя единое имя манифеста события messageSending, как описано в таблице поддерживаемых событий). Имя функции, указанное в actionId, должно соответствовать имени, используемому в свойстве id объекта в массиве actions на предыдущем шаге.
    • Параметр sendMode имеет значение softBlock. Это означает, что если сообщение не соответствует условиям, заданным надстройкой для отправки, пользователь должен принять меры перед отправкой сообщения. Однако если надстройка недоступна во время отправки, элемент будет отправлен.
      {
      "requirements": {
          "capabilities": [
              {
                  "name": "Mailbox",
                  "minVersion": "1.12"
              }
          ],
          "scopes": [
              "mail"
          ]
      },
      "events": [
        {
            "type": "messageSending",
            "actionId": "onMessageSendHandler",
            "options": {
                "sendMode": "softBlock"
            }
        }
      ]
  }

Совет

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

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

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

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

  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.
*/

function onMessageSendHandler(event) {
  Office.context.mailbox.item.body.getAsync(
    "text",
    { asyncContext: event },
    getBodyCallback
  );
}

function getBodyCallback(asyncResult){
  const event = asyncResult.asyncContext;
  let body = "";
  if (asyncResult.status !== Office.AsyncResultStatus.Failed && asyncResult.value !== undefined) {
    body = asyncResult.value;
  } else {
    const message = "Failed to get body text";
    console.error(message);
    event.completed({ allowEvent: false, errorMessage: message });
    return;
  }

  const matches = hasMatches(body);
  if (matches) {
    Office.context.mailbox.item.getAttachmentsAsync(
      { asyncContext: event },
      getAttachmentsCallback);
  } else {
    event.completed({ allowEvent: true });
  }
}

function hasMatches(body) {
  if (body == null || body == "") {
    return false;
  }

  const arrayOfTerms = ["send", "picture", "document", "attachment"];
  for (let index = 0; index < arrayOfTerms.length; index++) {
    const term = arrayOfTerms[index].trim();
    const regex = RegExp(term, 'i');
    if (regex.test(body)) {
      return true;
    }
  }

  return false;
}

function getAttachmentsCallback(asyncResult) {
  const event = asyncResult.asyncContext;
  if (asyncResult.value.length > 0) {
    for (let i = 0; i < asyncResult.value.length; i++) {
      if (asyncResult.value[i].isInline == false) {
        event.completed({ allowEvent: true });
        return;
      }
    }

    event.completed({
      allowEvent: false,
      errorMessage: "Looks like the body of your message includes an image or an inline file. Attach a copy to the message before sending."
    });
  } else {
    event.completed({
      allowEvent: false,
      errorMessage: "Looks like you're forgetting to include an attachment."
    });
  }
}

// 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 to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onMessageSendHandler", onMessageSendHandler);
}

Важно!

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

  • Импорт в настоящее время не поддерживается в файле JavaScript, в котором реализуется обработка активации на основе событий.
  • Чтобы убедиться, что надстройка работает должным образом при OnMessageSend возникновении события или OnAppointmentSend в Outlook в Windows, вызовите Office.actions.associate в файле JavaScript, где реализованы обработчики. Это сопоставляет имя обработчика событий, указанное в манифесте, с его аналогом JavaScript. Если этот вызов не включен в файл JavaScript, а для свойства режима отправки манифеста задана мягкая блокировка или не указано, пользователи будут заблокированы для отправки сообщений или собраний.

Настройка кнопки "Не отправлять" (необязательно) (предварительная версия)

Примечание.

Функция настройки кнопки "Не отправлять " сейчас доступна в предварительной версии в Outlook в Windows. Функции предварительной версии не следует использовать в рабочих надстройках. Мы приглашаем вас опробовать эту функцию в средах тестирования или разработки и приветствовать отзывы о вашем опыте через GitHub (см. раздел Отзывы в конце этой страницы).

Чтобы просмотреть эту функцию в Outlook в Windows, необходимо установить версию 2308 (сборка 16731.20000) или более позднюю. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите параметр Канал бета-версии , чтобы получить доступ к бета-сборкам Office.

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

Изменение текста и функциональности кнопки "Не отправлять"

Чтобы изменить текст кнопки Не отправлять или назначить ей команду области задач, необходимо задать дополнительные параметры в методе event.completed обработчика событий.

  • Параметр cancelLabel настраивает текст кнопки Не отправлять . Пользовательский текст должен содержать не более 20 символов.

  • Параметр commandId указывает идентификатор области задач, которая открывается при нажатии кнопки Не отправлять . Значение должно соответствовать идентификатору области задач в манифесте надстройки. Разметка зависит от типа манифеста, используемого надстройкой.

    • МАНИФЕСТ XML: id атрибут <элемента Control> , представляющего область задач.
    • Унифицированный манифест для Microsoft 365 (предварительная версия): свойство id команды области задач в массиве controls.

  • Параметр contextData указывает все данные JSON, которые нужно передать надстройке при нажатии кнопки Не отправлять . Если этот параметр включен, необходимо также задать commandId параметр . В противном случае данные JSON игнорируются.

    Совет

    Чтобы получить значение contextData параметра, необходимо вызвать Office.context.mailbox.item.getInitializationContextAsync в реализации JavaScript области задач.

  1. Перейдите в папку ./src/launchevent , а затем откройте launchevent.js.

  2. Замените функцию getAttachmentsCallback следующим кодом.

    function getAttachmentsCallback(asyncResult) {
  const event = asyncResult.asyncContext;
  if (asyncResult.value.length > 0) {
    for (let i = 0; i < asyncResult.value.length; i++) {
      if (asyncResult.value[i].isInline == false) {
        event.completed({ allowEvent: true });
        return;
      }
    }

    event.completed({
      allowEvent: false,
      errorMessage: "Looks like the body of your message includes an image or an inline file. Attach a copy to the message before sending.",
      cancelLabel: "Add an attachment",
      commandId: "msgComposeOpenPaneButton"
    });
  } else {
    event.completed({
      allowEvent: false,
      errorMessage: "Looks like you're forgetting to include an attachment.",
      cancelLabel: "Add an attachment",
      commandId: "msgComposeOpenPaneButton"
    });
  }
}

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

Переопределение параметра режима отправки во время выполнения (необязательно) (предварительная версия)

Примечание.

Функция переопределения режима отправки в настоящее время доступна в предварительной версии в Outlook в Windows. Функции предварительной версии не следует использовать в рабочих надстройках. Мы приглашаем вас опробовать эту функцию в средах тестирования или разработки и приветствовать отзывы о вашем опыте через GitHub (см. раздел Отзывы в конце этой страницы).

Чтобы просмотреть эту функцию в Outlook в Windows, необходимо установить версию 2308 (сборка 16731.20000) или более позднюю. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите параметр Канал бета-версии , чтобы получить доступ к бета-сборкам Office.

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

Чтобы переопределить параметр режима отправки во время выполнения, необходимо задать параметр sendModeOverride в event.completed методе обработчика событий.

  1. Перейдите в папку ./src/launchevent , а затем откройте launchevent.js.

  2. Замените функцию getAttachmentsCallback следующим кодом.

    function getAttachmentsCallback(asyncResult) {
  const event = asyncResult.asyncContext;
  if (asyncResult.value.length > 0) {
    for (let i = 0; i < asyncResult.value.length; i++) {
      if (asyncResult.value[i].isInline == false) {
        event.completed({ allowEvent: true });
        return;
      }
    }

    event.completed({
      allowEvent: false,
      errorMessage: "Looks like the body of your message includes an image or an inline file. Would you like to attach a copy of it to the message?",
      cancelLabel: "Attach a copy",
      commandId: "msgComposeOpenPaneButton",
      sendModeOverride: Office.MailboxEnums.SendModeOverride.PromptUser
    });
  } else {
    event.completed({
      allowEvent: false,
      errorMessage: "Looks like you're forgetting to include an attachment.",
      cancelLabel: "Add an attachment",
      commandId: "msgComposeOpenPaneButton"
    });
  }
}

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

Настройка области задач (необязательно)

Если вы реализовали необязательные шаги для настройки кнопки "Не отправлять" или переопределения режима отправки в этом пошаговом руководстве, необходимо также настроить область задач. Хотя в этой реализации требуется область задач, настраивать текст кнопки "Не отправлять " или переопределять режим отправки не требуется.

  1. Перейдите в папку ./src/taskpane , а затем откройте taskpane.html.

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

    <body class="ms-welcome ms-Fabric">
    <header class="ms-welcome__header ms-bgColor-neutralLighter">
        <img width="90" height="90" src="../../assets/logo-filled.png" alt="Contoso" title="Contoso" />
        <h1 class="ms-font-su">Try out the Smart Alerts sample</h1>
    </header>
    <section id="sideload-msg" class="ms-welcome__main">
        <h2 class="ms-font-xl">Please <a href="https://learn.microsoft.com/office/dev/add-ins/testing/test-debug-office-add-ins#sideload-an-office-add-in-for-testing">sideload</a> your add-in to see app body.</h2>
    </section>
    <main id="app-body" class="ms-welcome__main" style="display: none;">
        <p>
            This sample implements a Smart Alerts add-in that activates when you forget to attach a document or picture that you mention in your message.
            To learn more, see the <a href="https://learn.microsoft.com/office/dev/add-ins/outlook/smart-alerts-onmessagesend-walkthrough">Smart Alerts walkthrough</a>.
        </p>
        <h3 class="ms-font-l">Add an attachment</h3>
        <p>Add the URL of a file to add it as an attachment.</p>
        <div class="ms-TextField">
            <label class="ms-Label ms-font-l">URL of file:</label>
            <input id="attachment-url" class="ms-TextField-field" type="text" value="https://localhost:3000/assets/icon-128.png" placeholder="">
        </div>
        <br/>
        <button class="ms-Button ms-Button--primary">
            <span id="add-attachment" class="ms-Button-label">Add as attachment</span>
        </button>
        <br/>
        <h3 class="ms-font-l">Override the send mode option at runtime</h3>
        <p>Add an inline image to test overriding the send mode option at runtime.</p>
        <button class="ms-Button ms-Button--primary">
            <span id="add-inline-image" class="ms-Button-label">Add an inline image</span>
        </button>
    </main>
</body>

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

  4. В той же папке ./src/taskpane откройте taskpane.js.

  5. Замените его содержимое следующим кодом.

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

Office.onReady((info) => {
  if (info.host === Office.HostType.Outlook) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";
    document.getElementById("add-attachment").onclick = addAttachment;
    document.getElementById("add-inline-image").onclick = addInlineImage;
  }
});

// Adds the specified URL as an attachment to the message.
export async function addAttachment() {
  const attachmentUrl = document.querySelector("#attachment-url").value;
  Office.context.mailbox.item.addFileAttachmentAsync(attachmentUrl, getFileName(attachmentUrl), (asyncResult) => {
    console.log(asyncResult);
  });
}

// Gets the file name from a URL.
function getFileName(url) {
  const lastIndex = url.lastIndexOf("/");
  if (lastIndex >= 0) {
    return url.substring(lastIndex + 1);
  }

  return url;
}

// Adds an inline image to the body of the message.
export async function addInlineImage() {
  const mailItem = Office.context.mailbox.item;
  const base64String =
    "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAMAAADVRocKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAnUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN0S+bUAAAAMdFJOUwAQIDBAUI+fr7/P7yEupu8AAAAJcEhZcwAADsMAAA7DAcdvqGQAAAF8SURBVGhD7dfLdoMwDEVR6Cspzf9/b20QYOthS5Zn0Z2kVdY6O2WULrFYLBaLxd5ur4mDZD14b8ogWS/dtxV+dmx9ysA2QUj9TQRWv5D7HyKwuIW9n0vc8tkpHP0W4BOg3wQ8wtlvA+PC1e8Ao8Ld7wFjQtHvAiNC2e8DdqHqKwCrUPc1gE1AfRVgEXBfB+gF0lcCWoH2tYBOYPpqQCNwfT3QF9i+AegJfN8CtAWhbwJagtS3AbIg9o2AJMh9M5C+SVGBvx6zAfmT0r+Bv8JMwP4kyFPir+cswF5KL3WLv14zAFBCLf56Tw9cparFX4upgaJUtPhrOS1QlY5W+vWTXrGgBFB/b72ev3/0igUdQPppP/nfowfKUUEFcP207y/yxKmgAYQ+PywoAFOfCH3A2MdCFzD3kdADBvq10AGG+pXQBgb7pdAEhvuF0AIc/VtoAK7+JciAs38KIuDugyAC/v4hiMCE/i7IwLRBsh68N2WQjMVisVgs9i5bln8LGScNcCrONQAAAABJRU5ErkJggg==";

  // Gets the current body of the message.
  mailItem.body.getAsync(Office.CoercionType.Html, (bodyResult) => {
    if (bodyResult.status === Office.AsyncResultStatus.Failed) {
      console.log(bodyResult.error.message);
      return;
    }

    // Inserts the Base64-encoded image to the beginning of the body.
    const options = { isInline: true, asyncContext: bodyResult.value };
    mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
      if (attachResult.status === Office.AsyncResultStatus.Failed) {
        console.log(attachResult.error.message);
        return;
      }

      let body = attachResult.asyncContext;
      body = body.replace("<p class=MsoNormal>", `<p class=MsoNormal><img src="cid:sample.png">`);
      mailItem.body.setAsync(body, { coercionType: Office.CoercionType.Html }, (setResult) => {
        if (setResult.status === Office.AsyncResultStatus.Failed) {
          console.log(setResult.error.message);
          return;
        }

        console.log("Inline image added to the body.");
      });
    });
  });
}

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

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

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

  2. Непосредственно перед закрывающим тегом головки (</head>) добавьте запись скрипта для кода JavaScript для обработки событий.

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

Важно!

Функция настройки и режима отправки " Не отправлять " в настоящее время доступна в предварительной версии в Outlook в Windows. Если вы тестируете эти функции в проекте надстройки, необходимо включить ссылку на предварительную версию API JavaScript для Office в файлcommands.html .

<script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>
<script type="text/javascript" src="../launchevent/launchevent.js"></script>
  1. Сохраните изменения.

Обновление настроек конфигурации 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 создайте новое сообщение и задайте тему. В тексте добавьте текст. Например, "Вот изображение предлагаемого логотипа".

  3. Отправьте сообщение. Появится диалоговое окно с запросом на добавление вложения. Выберите Не отправлять или добавлять вложение. Доступный параметр зависит от того, реализован ли необязательный шаг для настройки кнопки "Не отправлять ".

    • Кнопка "Не отправлять " по умолчанию.

      Диалоговое окно с запросом на добавление в сообщение вложения.

    • Настроенная кнопка "Добавить вложение ".

      Диалоговое окно с настроенной кнопкой

    Совет

    Если вы назначите область задач кнопке Не отправлять , закрытие диалогового окна также открывает указанную область задач.

  4. Добавьте вложение в сообщение. Если вы реализовали необязательный шаг для настройки кнопки "Не отправлять ", используйте область задач, чтобы добавить вложение.

    Область задач с возможностью добавления вложения.

  5. Отправьте сообщение. На этот раз оповещение не должно быть.

Попробуйте переопределить режим отправки во время выполнения (необязательно)

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

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

    Примечание.

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

  2. В Outlook в Windows создайте новое сообщение и задайте тему. В тексте добавьте текст. Например, "Вот изображение предлагаемого логотипа".

  3. На ленте выберите Contoso Add-in>Show Taskpane (Показать область задач).

  4. В области задач выберите Добавить встроенное изображение. Изображение добавляется в текст сообщения.

  5. Отправьте сообщение. Появится диалоговое окно с рекомендацией прикрепить копию изображения к сообщению.

  6. Выберите Отправить в любом случае , чтобы отправить сообщение как есть, или выберите Вложить копию , чтобы включить копию перед отправкой сообщения.

    Диалоговое окно смарт-оповещений с параметром Отправить в любом случае, доступным во время выполнения.

Важно!

Если надстройка Smart Alerts, реализующая функцию переопределения, не может завершить обработку события из-за ошибки или недоступна при возникновении события, она использует параметр режима отправки, указанный в манифесте.

См. также