Добавление или добавление содержимого в сообщение или текст встречи при отправке

  • Статья

Функции prepend-on-send и add-on-send позволяют надстройке Outlook вставлять содержимое в текст сообщения или встречи при отправке почтового элемента. Эти функции повышают производительность и безопасность пользователей, позволяя им:

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

В этом пошаговом руководстве вы разработаете надстройку, которая добавляет заголовок и добавляет заявление об отказе от ответственности при отправке сообщения.

Примечание.

Поддержка функции добавления при отправке была введена в наборе требований 1.9, а поддержка функции prepend-on-send была введена в наборе требований 1.13. См . сведения о клиентах и платформах , поддерживающих эти наборы требований.

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

Завершите краткое руководство По созданию проекта надстройки с помощью генератора Yeoman для надстроек Office.

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

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

Ниже показано, как настроить единый манифест для включения функций prepend-on-send и append-on-send.

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

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

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

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

    • Значение mailCompose добавляется в массив contexts для отображения кнопок prepend-on-send и add-on-send в окне создания.
    • Объекты controls создают и настраивают кнопки для функций prepend-on-send и append-on-send. Свойство actionId каждого объекта должно отражать одно и то же значение, указанное в применимом свойстве "actions.id" объекта extensions.runtimes.
    {
    "contexts": [
        "mailCompose"
    ],
    "tabs": [
        {
            "builtInTabId": "TabDefault",
            "groups": [
                {
                    "id": "msgComposeGroup",
                    "label": "Contoso Add-in",
                    "icons": [
                        {
                            "size": 16,
                            "url" "https://localhost:3000/assets/icon-16.png"
                        },
                        {
                            "size": 32,
                            "url" "https://localhost:3000/assets/icon-32.png"
                        },
                        {
                            "size": 80,
                            "url" "https://localhost:3000/assets/icon-80.png"
                        }
                    ],
                    "controls": [
                        {
                            "id": "PrependButton",
                            "type": "button",
                            "label": "Prepend header",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Prepend header on send",
                                "description": "Prepend the Contoso header on send."
                            },
                            "actionId": "prependHeaderOnSend"
                        },
                        {
                            "id": "AppendButton",
                            "type": "button",
                            "label": "Add disclaimer",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Append disclaimer on send",
                                "description": "Append the Contoso disclaimer on send."
                            },
                            "actionId": "appendDisclaimerOnSend"
                        }
                    ]
                }
            ]
        }
    ]
}

  4. В массиве authorization.permissions.resourceSpecific добавьте следующий объект. Убедитесь, что он отделен от других объектов в массиве запятой.

    {
  "name": "Mailbox.AppendOnSend.User",
  "type": "Delegated"
}

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

Совет

  • Функции prepend-on-send и append-on-send должны быть активированы пользователем с помощью панели задач или кнопки команды функции. Если вы хотите добавить содержимое при отправке без дополнительных действий со стороны пользователя, эти функции можно реализовать в надстройке активации на основе событий.
  • Дополнительные сведения о манифестах надстроек Outlook см. в статье Манифесты надстроек Office.

Реализация обработчика prepend-on-send

В этом разделе вы реализуете код JavaScript для добавления примера заголовка компании к почтовому элементу при его отправке.

  1. Перейдите в папку ./src/commands проекта и откройте файлcommands.js .

  2. Вставьте следующую функцию в конец файла.

    function prependHeaderOnSend(event) {
  // It's recommended to call the getTypeAsync method and pass its returned value to the options.coercionType parameter of the prependOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    },
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      // Sets the header to be prepended to the body of the message on send.
      const bodyFormat = asyncResult.value;
      // Because of the various ways in which HTML text can be formatted, the content may render differently when it's prepended to the mail item body.
      // In this scenario, a <br> tag is added to the end of the HTML string to preserve its format.
      const header = '<div style="border:3px solid #000;padding:15px;"><h1 style="text-align:center;">Contoso Limited</h1></div><br>';

      Office.context.mailbox.item.body.prependOnSendAsync(
        header,
        {
          asyncContext: asyncResult.asyncContext,
          coercionType: bodyFormat
        },
        (asyncResult) => {
          if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            return;
          }

          console.log("The header will be prepended when the mail item is sent.");
          asyncResult.asyncContext.completed();
        }
      );
  });
}

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

Реализация обработчика добавления при отправке

В этом разделе вы реализуете код JavaScript, чтобы добавить пример заявления об отказе от ответственности компании к почтовому элементу при его отправке.

  1. В том же commands.js файле вставьте следующую функцию после prependHeaderOnSend функции.

    function appendDisclaimerOnSend(event) { 
  // Calls the getTypeAsync method and passes its returned value to the options.coercionType parameter of the appendOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    }, 
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }

    // Sets the disclaimer to be appended to the body of the message on send.
    const bodyFormat = asyncResult.value;
    const disclaimer =
      '<p style = "color:blue"> <i>This and subsequent emails on the same topic are for discussion and information purposes only. Only those matters set out in a fully executed agreement are legally binding. This email may contain confidential information and should not be shared with any third party without the prior written agreement of Contoso. If you are not the intended recipient, take no action and contact the sender immediately.<br><br>Contoso Limited (company number 01624297) is a company registered in England and Wales whose registered office is at Contoso Campus, Thames Valley Park, Reading RG6 1WG</i></p>';  

    Office.context.mailbox.item.body.appendOnSendAsync(
      disclaimer,
      {
        asyncContext: asyncResult.asyncContext,
        coercionType: bodyFormat
      },
      (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        console.log("The disclaimer will be appended when the mail item is sent.");
        asyncResult.asyncContext.completed();
      }
    );
  });
}

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

Регистрация функций JavaScript

  1. В том же commands.js файле вставьте следующую команду после appendDisclaimerOnSend функции. Эти вызовы сопоставляют имя функции, указанное в манифесте, с ее аналогом JavaScript. Расположение имени функции в манифесте зависит от типа манифеста, используемого надстройкой.

  • Только манифест надстройки: имя функции, указанное в элементе <FunctionName> .

  • Унифицированный манифест для Microsoft 365: имя функции, указанное в свойстве id объектов в массиве extensions.runtimes.actions.

    Office.actions.associate("prependHeaderOnSend", prependHeaderOnSend);
Office.actions.associate("appendDisclaimerOnSend", appendDisclaimerOnSend);
  1. Сохраните изменения.

Проверка

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

    npm start

    Примечание.

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

  2. Создайте новое сообщение и добавьте себя в строку Кому .

  3. (Необязательно) Введите текст в текст сообщения.

  4. В меню ленты или переполнения выберите Заголовок Prepend.

  5. В меню ленты или переполнения выберите Добавить заявление об ответственности.

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

    Пример отправленного сообщения с предустановленным заголовком Contoso и заявлением об отказе от ответственности, добавленным в его текст.

    Совет

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

  7. Если вы хотите остановить локальный веб-сервер и удалить надстройку, следуйте применимым инструкциям:

    • Чтобы остановить сервер, выполните следующую команду. Если вы использовали npm start, следующая команда также должна удалить надстройку.

      npm stop

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

Обзор поведения и ограничений функций

При реализации prepend-on-send и add-on-send в надстройке помните следующее.

  • Prepend-on-send и append-on-send поддерживаются только в режиме создания.

  • Строка, добавляемая или добавляемая, не должна превышать 5000 символов.

  • HTML-код не может быть добавлен или добавлен в текст обычного текста сообщения или встречи. Однако обычный текст можно добавить в текст сообщения или встречи в формате HTML.

  • Любое форматирование, применяемое к предварительному или добавляемому содержимому, не влияет на стиль остальной части текста почтового элемента.

  • Prepend-on-send и add-on-send не могут быть реализованы в той же надстройке, которая реализует функцию при отправке. Вместо этого рассмотрите возможность реализации интеллектуальных оповещений .

  • При реализации смарт-оповещений в той же надстройке операции prepend-on-send и add-on-send выполняются перед операциями OnMessageSend обработчика событий и OnAppointmentSend .

  • Если несколько активных надстроек используют prepend-on-send или add-on-send, порядок вставки содержимого зависит от порядка запуска надстройки. При предварительной отправке содержимое надстройки, которая выполняется последней, отображается в верхней части текста почтового элемента перед ранее добавленным содержимым. При добавлении при отправке содержимое надстройки, которая выполняется последней, отображается в нижней части текста почтового элемента после ранее добавленного содержимого.

  • Сценарии делегирования и общего почтового ящика поддерживаются при условии, что надстройка, реализующая prepend-on-send или add-on-send, включена в общем почтовом ящике или учетной записи владельца.

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

Если при реализации функций prepend-on-send и append-on-send возникает ошибка, ознакомьтесь со следующей таблицей.

Ошибка Описание Решение
DataExceedsMaximumSize Добавляемое или добавляемое содержимое имеет длину более 5000 символов. Сократите строку, передаваемую в data параметр вызова prependOnSendAsync или appendOnSendAsync .
InvalidFormatError Текст сообщения или встречи имеет формат обычного текста, но coercionType для метода prependOnSendAsync или appendOnSendAsync задано значение Office.CoercionType.Html. В текст сообщения или встречи можно вставлять только обычный текст. Чтобы проверить формат создаваемого почтового элемента, вызовите Office.context.mailbox.item.body.getTypeAsync, а затем передайте его возвращенное значение в или prependOnSendAsyncappendOnSendAsync вызов.

См. также