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

Чтение, запись и добавление получателей при создании встречи или сообщения в Outlook

  • Статья

API JavaScript для Office предоставляет асинхронные методы (Recipients.getAsync, Recipients.setAsync или Recipients.addAsync) для получения, задания или добавления получателей в форму создания встречи или сообщения. Эти асинхронные методы доступны только для создания надстроек. Чтобы использовать эти методы, убедитесь, что манифест надстройки настроен соответствующим образом для Outlook, чтобы активировать надстройку в формах создания, как описано в разделе Создание надстроек Outlook для форм создания.

Некоторые свойства, представляющие получателей в сообщении или встрече, доступны для чтения в формах создания и чтения. Это свойства optionalAttendees и requiredAttendees для встреч и свойства cc и to для сообщений.

В форме чтения доступ к свойству можно получить напрямую из родительского объекта, например:

Office.context.mailbox.item.cc;

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

Office.context.mailbox.item.cc.getAsync(callback);

Эти свойства доступны для доступа к записи только в формах создания, а не в формах чтения.

Как и большинство асинхронных методов в API JavaScript для Office, getAsync, setAsyncи addAsync принимают необязательные входные параметры. Дополнительные сведения о том, как указать эти необязательные входные параметры, см. в разделе Передача необязательных параметров в асинхронные методы статьи Асинхронное программирование в надстройках Office.

Извлечение получателей

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

В API JavaScript для Office, так как свойства, представляющие получателей встречи (optionalAttendees и requiredAttendees), отличаются от свойств сообщения (ск,cc , и to), следует сначала использовать свойство item.itemType, чтобы определить, является ли создаваемый элемент встречей или сообщением. В режиме создания все эти свойства встреч и сообщений являются объектами Recipients , поэтому можно вызвать асинхронный метод , Recipients.getAsyncчтобы получить соответствующих получателей.

Чтобы использовать getAsync, предоставьте функцию обратного вызова для проверка состояния, результатов и любой ошибки, возвращаемой асинхронным getAsync вызовом. Функция обратного вызова возвращает выходной параметр asyncResult . Используйте свойства status и error для проверка состояния и любых сообщений об ошибках в асинхронном вызове, а также для value получения фактических получателей. Они представляются как массив объектов EmailAddressDetails. Вы также можете предоставить дополнительные сведения для функции обратного вызова с помощью необязательного asyncContext параметра в вызове getAsync .

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

Важно!

Метод getAsync возвращает только получателей, разрешенных клиентом Outlook. Разрешенный получатель имеет следующие характеристики.

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

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

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

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        getAllRecipients();
    }
});

// Gets the email addresses of all the recipients of the item being composed.
function getAllRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail item is an appointment or message.
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        toRecipients = item.requiredAttendees;
        ccRecipients = item.optionalAttendees;
    }
    else {
        toRecipients = item.to;
        ccRecipients = item.cc;
        bccRecipients = item.bcc;
    }

    // Get the recipients from the To or Required field of the item being composed.
    toRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the To or Required field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Cc or Optional field of the item being composed.
    ccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients or attendees.
        write(`Recipients in the Cc or Optional field: ${displayAddresses(asyncResult.value)}`);
    });

    // Get the recipients from the Bcc field of the message being composed, if applicable.
    if (bccRecipients.length > 0) {
        bccRecipients.getAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
            return;
        }

        // Display the email addresses of the recipients.
        write(`Recipients in the Bcc field: ${displayAddresses(asyncResult.value)}`);
        });
    } else {
        write("Recipients in the Bcc field: None");
    }
}

// Displays the email address of each recipient.
function displayAddresses (recipients) {
    for (let i = 0; i < recipients.length; i++) {
        write(recipients[i].emailAddress);
    }
}

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

Установка получателей

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

При вызове setAsyncукажите массив в качестве входного аргумента recipients для параметра в одном из следующих форматов.

  • массив строк, являющихся SMTP-адресами;
  • массив словарей, каждый из которых содержит отображаемое имя и адрес электронной почты, как показано в следующем примере кода;
  • Массив объектов, аналогичный EmailAddressDetails тому, который возвращается методом getAsync .

При необходимости можно указать функцию обратного вызова в качестве входного аргумента setAsync для метода, чтобы убедиться, что любой код, зависящий от успешной настройки получателей, будет выполняться только в этом случае. При реализации функции обратного вызова используйте status свойства и error выходного asyncResult параметра, чтобы проверка состояние и все сообщения об ошибках асинхронного вызова. Чтобы предоставить дополнительные сведения функции обратного вызова, используйте необязательный asyncContext параметр в вызове setAsync .

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        setRecipients();
    }
});

// Sets the recipients of the item being composed.
function setRecipients() {
    let toRecipients, ccRecipients, bccRecipients;

    // Verify if the mail item is an appointment or message.
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        toRecipients = item.requiredAttendees;
        ccRecipients = item.optionalAttendees;
    }
    else {
        toRecipients = item.to;
        ccRecipients = item.cc;
        bccRecipients = item.bcc;
    }

    // Set the recipients in the To or Required field of the item being composed.
    toRecipients.setAsync(
        [{
            "displayName": "Graham Durkin", 
            "emailAddress": "graham@contoso.com"
         },
         {
            "displayName": "Donnie Weinberg",
            "emailAddress": "donnie@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the To or Required field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Cc or Optional field of the item being composed.
    ccRecipients.setAsync(
        [{
            "displayName": "Perry Horning", 
            "emailAddress": "perry@contoso.com"
         },
         {
            "displayName": "Guy Montenegro",
            "emailAddress": "guy@contoso.com"
         }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully set the recipients in the Cc or Optional field.");
            // Run additional operations appropriate to your scenario.
    });

    // Set the recipients in the Bcc field of the message being composed.
    if (bccRecipients) {
        bccRecipients.setAsync(
            [{
                "displayName": "Lewis Cate", 
                "emailAddress": "lewis@contoso.com"
            },
            {
                "displayName": "Francisco Stitt",
                "emailAddress": "francisco@contoso.com"
            }],
            (asyncResult) => {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    console.log(asyncResult.error.message);
                    return;
                }
    
                console.log("Successfully set the recipients in the Bcc field.");
                // Run additional operations appropriate to your scenario.
        });
    }
}

Добавление получателей

Если вы не хотите перезаписывать существующих получателей в встрече или сообщении, вместо использования Recipients.setAsyncиспользуйте Recipients.addAsync асинхронный метод для добавления получателей. addAsync работает так же, как setAsync и в том, что требуется входной recipients аргумент. При необходимости можно указать функцию обратного вызова и любые аргументы для обратного вызова с помощью asyncContext параметра . Затем проверка состояние, результат и любую ошибку асинхронного addAsync вызова с помощью asyncResult выходного параметра функции обратного вызова. В следующем примере проверяется, является ли создаваемый элемент встречей, а затем к нему добавляются два необходимых участника.

let item;

// Confirms that the Office.js library is loaded.
Office.onReady((info) => {
    if (info.host === Office.HostType.Outlook) {
        item = Office.context.mailbox.item;
        addAttendees();
    }
});

// Adds the specified recipients as required attendees of the appointment.
function addAttendees() {
    if (item.itemType === Office.MailboxEnums.ItemType.Appointment) {
        item.requiredAttendees.addAsync(
        [{
            "displayName": "Kristie Jensen",
            "emailAddress": "kristie@contoso.com"
         },
         {
            "displayName": "Pansy Valenzuela",
            "emailAddress": "pansy@contoso.com"
          }],
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(asyncResult.error.message);
                return;
            }

            console.log("Successfully added the required attendees.");
            // Run additional operations appropriate to your scenario.
        });
    }
}

См. также