Obter, configurar ou adicionar destinatários ao compor um compromisso ou uma mensagem no Outlook

  • Artigo

A API JavaScript do Office fornece métodos assíncronos (Recipients.getAsync, Recipients.setAsync ou Recipients.addAsync) para obter, definir ou adicionar destinatários a uma forma de composição de um compromisso ou mensagem. Esses métodos assíncronos estão disponíveis apenas para compor suplementos. Para usar esses métodos, verifique se você configurou o manifesto de suplemento adequadamente para o Outlook para ativar o suplemento em formulários de composição, conforme descrito em Criar suplementos do Outlook para formulários de composição.

Algumas das propriedades que representam destinatários em um compromisso ou uma mensagem estão disponíveis para acesso de leitura em formulários de composição e de leitura. Essas propriedades incluem opcionaisAttendees e requiredAttendees para compromissos e cc e para mensagens.

No formulário de leitura, você pode acessar a propriedade diretamente do objeto pai, como:

Office.context.mailbox.item.cc;

Mas em um formulário de composição, pois o usuário e seu suplemento podem estar inserindo ou alterando um destinatário ao mesmo tempo, você deve usar o método getAsync assíncrono para obter essas propriedades, como no exemplo a seguir.

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

Essas propriedades estão disponíveis para acesso à gravação apenas em formulários de composição e não em formulários de leitura.

Como acontece com a maioria dos métodos assíncronos na API JavaScript para Office, getAsync, e setAsyncaddAsync use parâmetros de entrada opcionais. Para obter mais informações sobre como especificar esses parâmetros de entrada opcionais, confira "Passando parâmetros opcionais para métodos assíncronos" na programação assíncrona nos Suplementos do Office.

Obter os destinatários

Esta seção mostra um exemplo de código que obtém os destinatários do compromisso ou da mensagem que está sendo composta e exibe os endereços de email dos destinatários.

Na API JavaScript do Office, porque as propriedades que representam os destinatários de um compromisso (optionalAttendees e requiredAttendees) são diferentes das de uma mensagem (bcc, cce to), você deve primeiro usar a propriedade item.itemType para identificar se o item que está sendo composto é um compromisso ou mensagem. No modo de composição, todas essas propriedades de compromissos e mensagens são objetos Destinatários , para que você possa chamar o método assíncrono, Recipients.getAsync, para obter os destinatários correspondentes.

Para usar getAsync, forneça uma função de retorno de chamada para marcar para o status, resultados e qualquer erro retornado pela chamada assíncronagetAsync. A função de retorno de chamada retorna um parâmetro de saída asyncResult . Use suas status propriedades e error para marcar para o status e quaisquer mensagens de erro da chamada assíncrona e sua value propriedade para obter os destinatários reais. Os destinatários são representados como uma matriz de objetos EmailAddressDetails. Você também pode fornecer informações adicionais para a função de retorno de chamada usando o parâmetro opcional asyncContext na getAsync chamada.

Observe que, como o getAsync método é assíncrono, se houver ações subsequentes que dependem da obtenção com êxito dos destinatários, você deverá organizar seu código para iniciar essas ações somente na função de retorno de chamada correspondente quando a chamada assíncrona tiver sido concluída com êxito.

Importante

O getAsync método retorna apenas os destinatários resolvidos pelo cliente do Outlook. Um destinatário resolvido tem as seguintes características.

  • Se o destinatário tiver uma entrada salva no catálogo de endereços do remetente, o Outlook resolverá o endereço de email para o nome de exibição salvo do destinatário.
  • Um ícone de status de reunião do Teams é exibido antes do nome ou endereço de email do destinatário.
  • Um ponto e vírgula é exibido após o nome do destinatário ou endereço de email.
  • O nome ou endereço de email do destinatário é sublinhado ou fechado em uma caixa.

Para resolve um endereço de email depois de adicionado a um item de email, o remetente deve usar a chave Tab ou selecionar um contato sugerido ou endereço de email na lista de preenchimento automático.

Em Outlook na Web e no Windows (clássico e novo (versão prévia)), se um usuário criar uma nova mensagem selecionando o link de endereço de email de um contato de um contato ou perfil cartão, ele deverá primeiro resolve o endereço de email para que ele possa ser incluído nos resultados da getAsync chamada.

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;
}

Definir os destinatários

Esta seção mostra um exemplo de código que define os destinatários do compromisso ou da mensagem que o usuário está compondo. A definição de destinatários substitui os destinatários existentes. Este exemplo primeiro verifica se o item de email é um compromisso ou mensagem, para que ele possa chamar o método assíncrono, Recipients.setAsync, nas propriedades apropriadas que representam os destinatários do compromisso ou da mensagem.

Ao chamar setAsync, forneça uma matriz como o argumento de entrada para o recipients parâmetro, em um dos formatos a seguir.

  • Uma matriz de cadeias de caracteres que são endereços SMTP.
  • Uma matriz de dicionários, cada um contendo um nome para exibição e um endereço de email, conforme mostrado no exemplo de código a seguir.
  • Uma matriz de EmailAddressDetails objetos, semelhante à retornada pelo getAsync método.

Opcionalmente, você pode fornecer uma função de retorno de chamada como um argumento de entrada para o setAsync método, para garantir que qualquer código que dependa de definir com êxito os destinatários só será executado quando isso acontecer. Se você implementar uma função de retorno de chamada, use as status propriedades e error do parâmetro de asyncResult saída para marcar o status e quaisquer mensagens de erro da chamada assíncrona. Para fornecer informações adicionais à função de retorno de chamada, use o parâmetro opcional asyncContext na setAsync chamada.

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.
        });
    }
}

Adicionar destinatários

Se você não quiser substituir nenhum destinatário existente em um compromisso ou mensagem, em vez de usar Recipients.setAsync, use o Recipients.addAsync método assíncrono para acrescentar destinatários. addAsync funciona da mesma forma setAsync que na medida em que requer um argumento de recipients entrada. Opcionalmente, você pode fornecer uma função de retorno de chamada e quaisquer argumentos para o retorno de chamada usando o asyncContext parâmetro. Em seguida, marcar o status, o resultado e qualquer erro da chamada assíncrona addAsync usando o asyncResult parâmetro de saída da função de retorno de chamada. O exemplo a seguir verifica se o item que está sendo composto é um compromisso e, em seguida, acrescenta dois participantes necessários a ele.

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.
        });
    }
}

Confira também