Управление вложениями элемента в форме создания в Outlook

  • Статья

API JavaScript для Office предоставляет несколько API, которые можно использовать для управления вложениями элемента при создании пользователем.

Вложение файла или элемента Outlook

Файл или элемент Outlook можно вложить в форму создания, используя метод, соответствующий типу вложения.

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

Если есть задачи, которые зависят от выполняемого действия, их следует выполнять в функции обратного вызова. Эта функция обратного вызова является необязательной и вызывается по завершении отправки вложения. Функция обратного вызова принимает объект AsyncResult в качестве выходного параметра, который предоставляет любое состояние, ошибку и возвращаемое значение при добавлении вложения. Если для обратного вызова требуются дополнительные параметры, их можно указать в необязательном параметре options.asyncContext. options.asyncContext может иметь любой тип, который ожидает функция обратного вызова.

Например, можно определить options.asyncContext как объект JSON, содержащий одну или несколько пар "ключ-значение". Дополнительные примеры передачи необязательных параметров в асинхронные методы на платформе надстроек Office см. в статье Асинхронное программирование в надстройках Office. В следующем примере показано, как использовать asyncContext параметр для передачи двух аргументов в функцию обратного вызова.

const options = { asyncContext: { var1: 1, var2: 2 } };

Office.context.mailbox.item.addFileAttachmentAsync('https://contoso.com/rtm/icon.png', 'icon.png', options, callback);

Для успешного или ошибочного вызова асинхронного метода в функции обратного вызова можно проверка с помощью status свойств AsyncResult и error объекта . Если присоединение завершается успешно, можно использовать AsyncResult.value свойство для получения идентификатора вложения. Это целое число, которое можно использовать в дальнейшем, чтобы удалить вложение.

Примечание.

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

Совет

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

Вложение файла

Файл можно вложить в сообщение или встречу в форме создания, используя addFileAttachmentAsync метод и указав универсальный код ресурса (URI) файла. Можно также использовать addFileAttachmentFromBase64Async метод , указав строку в кодировке Base64 в качестве входных данных. Если файл защищен, можно добавить соответствующее удостоверение или токен проверки подлинности как параметр строки запроса URI. Exchange вызовет URI, чтобы получить вложение, а веб-службе, которая защищает файл, потребуется использовать токен для проверки подлинности.

Следующий пример JavaScript — это надстройка создания, которая прикрепляет файл picture.png с веб-сервера к создаваемому сообщению или встрече. Функция обратного вызова принимает asyncResult в качестве параметра, проверяет состояние результата и получает идентификатор вложения в случае успешного выполнения метода.

Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Add the specified file attachment to the item
        // being composed.
        // When the attachment finishes uploading, the
        // callback function is invoked and gets the attachment ID.
        // You can optionally pass any object that you would
        // access in the callback function as an argument to
        // the asyncContext parameter.
        Office.context.mailbox.item.addFileAttachmentAsync(
            `https://webserver/picture.png`,
            'picture.png',
            { asyncContext: null },
            function (asyncResult) {
                if (asyncResult.status === Office.AsyncResultStatus.Failed){
                    write(asyncResult.error.message);
                } else {
                    // Get the ID of the attached file.
                    const attachmentID = asyncResult.value;
                    write('ID of added attachment: ' + attachmentID);
                }
            });
    });
}

// Writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

Чтобы добавить встроенное изображение base64 в текст создаваемого сообщения или встречи, необходимо сначала получить текущий текст элемента с помощью Office.context.mailbox.item.body.getAsync метода , прежде чем вставлять изображение с помощью addFileAttachmentFromBase64Async метода . В противном случае изображение не будет отображаться в тексте после вставки. Инструкции см. в следующем примере JavaScript, который добавляет встроенное изображение Base64 в начало текста элемента.

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==";

// Get the current body of the message or appointment.
mailItem.body.getAsync(Office.CoercionType.Html, (bodyResult) => {
  if (bodyResult.status === Office.AsyncResultStatus.Succeeded) {
    // Insert the Base64 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.Succeeded) {
        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.Succeeded) {
            console.log("Inline Base64 image added to the body.");
          } else {
            console.log(setResult.error.message);
          }
        });
      } else {
        console.log(attachResult.error.message);
      }
    });
  } else {
    console.log(bodyResult.error.message);
  }
});

Присоединение элемента Outlook

Элемент Outlook (например, электронная почта, календарь или контактный элемент) можно вложить в сообщение или встречу в форме создания, указав идентификатор веб-служб Exchange (EWS) элемента и используя addItemAttachmentAsync метод . Идентификатор EWS электронной почты, календаря, контакта или элемента задачи в почтовом ящике пользователя можно получить с помощью метода mailbox.makeEwsRequestAsync и доступа к операции EWS FindItem. Свойство item.itemId также предоставляет идентификатор EWS существующего элемента в форме чтения.

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

// Adds the specified item as an attachment to the composed item.
// ID is the EWS ID of the item to be attached.
function addItemAttachment(itemId) {
    // When the attachment finishes uploading, the
    // callback function is invoked. Here, the callback
    // function uses only asyncResult as a parameter,
    // and if the attaching succeeds, gets the attachment ID.
    // You can optionally pass any other object you wish to
    // access in the callback function as an argument to
    // the asyncContext parameter.
    Office.context.mailbox.item.addItemAttachmentAsync(
        itemId,
        'Welcome email',
        { asyncContext: null },
        function (asyncResult) {
            if (asyncResult.status === Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            } else {
                const attachmentID = asyncResult.value;
                write('ID of added attachment: ' + attachmentID);
            }
        });
}

Примечание.

Надстройку создания можно использовать для присоединения экземпляра повторяющейся встречи в Outlook в Интернете, на мобильных устройствах или в новом Outlook в Windows (предварительная версия). Однако в поддерживаемом клиенте Outlook в Windows или mac попытка подключения экземпляра приведет к присоединению повторяющегося ряда (родительской встречи).

Получение вложений

API для получения вложений в режиме создания доступны в наборе требований 1.8.

Метод getAttachmentsAsync можно использовать для получения вложений создаваемого сообщения или встречи.

Чтобы получить содержимое вложения, можно использовать метод getAttachmentContentAsync . Поддерживаемые форматы перечислены в перечислении AttachmentContentFormat .

Необходимо указать функцию обратного вызова для проверка состояния и любой ошибки с помощью объекта выходного AsyncResult параметра. Вы также можете передать любые дополнительные параметры в функцию обратного вызова с помощью необязательного asyncContext параметра.

Следующий пример JavaScript получает вложения и позволяет настроить отдельную обработку для каждого поддерживаемого формата вложений.

const item = Office.context.mailbox.item;
const options = {asyncContext: {currentItem: item}};
item.getAttachmentsAsync(options, callback);

function callback(result) {
  if (result.value.length > 0) {
    for (let i = 0 ; i < result.value.length ; i++) {
      result.asyncContext.currentItem.getAttachmentContentAsync(result.value[i].id, handleAttachmentsCallback);
    }
  }
}

function handleAttachmentsCallback(result) {
  // Parse string to be a url, an .eml file, a Base64-encoded string, or an .icalendar file.
  switch (result.value.format) {
    case Office.MailboxEnums.AttachmentContentFormat.Base64:
      // Handle file attachment.
      break;
    case Office.MailboxEnums.AttachmentContentFormat.Eml:
      // Handle email item attachment.
      break;
    case Office.MailboxEnums.AttachmentContentFormat.ICalendar:
      // Handle .icalender attachment.
      break;
    case Office.MailboxEnums.AttachmentContentFormat.Url:
      // Handle cloud attachment.
      break;
    default:
      // Handle attachment formats that are not supported.
  }
}

Удаление вложения

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

Важно!

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

addFileAttachmentAsyncКак и методы , addItemAttachmentAsyncиgetAttachmentsAsync, removeAttachmentAsync является асинхронным методом. Необходимо указать функцию обратного вызова для проверка состояния и любой ошибки с помощью объекта выходного AsyncResult параметра. Вы также можете передать любые дополнительные параметры в функцию обратного вызова с помощью необязательного asyncContext параметра.

Следующая функция JavaScript, removeAttachment, продолжает расширять приведенные выше примеры и удаляет указанное вложение из создаваемого сообщения электронной почты или встречи. В качестве аргумента функция принимает идентификатор вложения, которое требуется удалить. Идентификатор вложения можно получить после успешного addFileAttachmentAsyncвызова метода , addFileAttachmentFromBase64Asyncили addItemAttachmentAsync и использовать его в последующем removeAttachmentAsync вызове метода. Вы также можете вызвать ( getAttachmentsAsync впервые появилось в наборе требований 1.8), чтобы получить вложения и их идентификаторы для этого сеанса надстройки.

// Removes the specified attachment from the composed item.
function removeAttachment(attachmentId) {
    // When the attachment is removed, the callback function is invoked.
    // Here, the callback function uses an asyncResult parameter and
    // gets the ID of the removed attachment if the removal succeeds.
    // You can optionally pass any object you wish to access in the
    // callback function as an argument to the asyncContext parameter.
    Office.context.mailbox.item.removeAttachmentAsync(
        attachmentId,
        { asyncContext: null },
        function (asyncResult) {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                write(asyncResult.error.message);
            } else {
                write('Removed attachment with the ID: ' + asyncResult.value);
            }
        });
}

См. также