Бөлісу құралы:

Чтение, запись и добавление получателей при создании встречи или сообщения в 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.
        });
    }
}

См. также