Поделиться через

Управление вложениями элемента в форме создания в 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);

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

Примечание.

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

Совет

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

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

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

Примечание.

Универсальный код ресурса (URI) присоединяемого файла должен поддерживать кэширование в рабочей среде. Сервер, на котором размещен образ, не должен возвращать заголовок, указывающий Cache-Controlno-cache, no-storeили аналогичные параметры в HTTP-ответе. Однако при разработке надстройки и внесении изменений в файлы кэширование может помешать просмотру изменений. Мы рекомендуем использовать Cache-Control заголовки во время разработки.

Следующий пример 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 в текст создаваемого сообщения или встречи, необходимо сначала получить текущий текст элемента с помощью 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.Failed) {
        console.error(bodyResult.error.message);
        return;
    }

    // Insert the Base64-encoded image at 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.error(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.error(setResult.error.message);
                return;
            }

            console.log("Inline Base64 image added to 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}`);
        }
    );
}

Примечание.

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

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

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

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

Совет

Если клиент Outlook, в котором запущена надстройка, не поддерживает набор обязательных почтовых ящиков 1.8, вы по-прежнему можете получить вложение и его содержимое из элемента, создаваемого с помощью Microsoft Graph или EWS. Дополнительные сведения см. в статье Получение вложений элемента Outlook из Exchange.

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

Чтобы удалить файл или вложение элемента из сообщения или встречи в форме создания, укажите соответствующий идентификатор вложения в методе 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 },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.error(asyncResult.error.message);
                return;
            }

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

Совет

Метод removeAttachmentAsync не удаляет встроенные вложения из почтового элемента. Чтобы удалить встроенное вложение, сначала получите текст элемента, а затем удалите все ссылки на вложение из его содержимого. Используйте API Office.Body , чтобы получить и задать текст элемента.

См. также