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

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

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

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

• addFileAttachmentAsync: вложение файла.

  Примечание.

  Метод addFileAttachmentAsync появился в наборе требований 1.1 для Outlook в Windows (классической) и на Mac. addFileAttachmentAsync Поддержка в Outlook в Интернете и новых Outlook для Windows появилась в наборе требований 1.8.

• addFileAttachmentFromBase64Async: вложите файл с помощью строки в кодировке Base64.

• addItemAttachmentAsync: присоединение элемента 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);

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

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

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

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

// 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: { var1: 1, var2: 2 } },
    (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.error(asyncResult.error.message);
            return;
        }

        // Get the ID of the attached file.
        const attachmentID = asyncResult.value;
        console.log(`ID of added attachment: ${attachmentID}`);
    }
);

Чтобы добавить встроенное изображение в кодировке Base64 в текст создаваемого сообщения или встречи, используйте методы API body , такие как prependAsync, setSignatureAsync или setAsync.

Ниже приведен пример изображения в кодировке Base64, который добавляется к тексту почтового элемента.

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

// Add the Base64-encoded image to the beginning of the body.
Office.context.mailbox.item.addFileAttachmentFromBase64Async(base64String, "sample.png", { isInline: true }, (attachmentResult) => {
    if (attachmentResult.status === Office.AsyncResultStatus.Failed) {
      console.log(`Failed to attach file: ${attachmentResult.error.message}`);
      return;
    }

    Office.context.mailbox.item.body.prependAsync('<img src="cid:sample.png" />', { coercionType: Office.CoercionType.Html }, (prependResult) => {
      if (prependResult.status === Office.AsyncResultStatus.Failed) {
        console.log(`Failed to prepend image to body: ${attachmentResult.error.message}`);
        return;
      }

      console.log("Inline Base64-encoded image added to the beginning of the body.");
    })
});

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

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

Следующая функция 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: { var1: 1, var2: 2 } },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.error(asyncResult.error.message);
                return;
            }

            const attachmentID = asyncResult.value;
            console.log(`ID of added attachment: ${attachmentID}`);
        }
    );
}

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

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

• getAttachmentsAsync
• getAttachmentContentAsync

Используйте метод 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 .

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 },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.error(asyncResult.error.message);
                return;
            }

            console.log(`Removed attachment with the ID: ${asyncResult.value}`);
        }
    );
}

См. также

• Получение вложений элемента Outlook из Exchange
• Создание надстроек Outlook для форм создания
• Асинхронное программирование надстроек Office
• Ограничения для активации и API JavaScript для надстроек Outlook