Partilhar via

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. Estes métodos assíncronos estão disponíveis apenas para compor suplementos. Para utilizar estes métodos, certifique-se de que configurou o manifesto de suplemento adequadamente para o Outlook 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. Estas propriedades incluem optionalAttendees e requiredAttendees para compromissos, cc e para para mensagens.

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

Office.context.mailbox.item.cc;

No entanto, num formulário de composição, uma vez que o utilizador e o suplemento podem estar a inserir ou a alterar um destinatário ao mesmo tempo, tem de utilizar o método getAsync assíncrono para obter estas propriedades, como no exemplo seguinte.

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

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

Tal como acontece com a maioria dos métodos assíncronos na API javaScript para o Office, getAsync, setAsynce addAsync utilize parâmetros de entrada opcionais. Para obter mais informações sobre como especificar estes parâmetros de entrada opcionais, consulte "Transmitir parâmetros opcionais para métodos assíncronos" em 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), deve primeiro utilizar a propriedade item.itemType para identificar se o item que está a ser composto é um compromisso ou mensagem. No modo de composição, todas estas propriedades de compromissos e mensagens são objetos destinatários , pelo que pode chamar o método assíncrono, Recipients.getAsync, para obter os destinatários correspondentes.

Para utilizar getAsync, forneça uma função de chamada de retorno para verificar o estado, os resultados e qualquer erro devolvido pela chamada assíncrona getAsync . A função de chamada de retorno devolve um parâmetro de saída asyncResult . Utilize as status respetivas propriedades e error para verificar o estado e quaisquer mensagens de erro da chamada assíncrona e a respetiva value propriedade para obter os destinatários reais. Os destinatários são representados como uma matriz de objetos EmailAddressDetails. Também pode fornecer informações adicionais à função de chamada de retorno com o parâmetro opcional asyncContext na getAsync chamada.

Tenha em atenção que, como o getAsync método é assíncrono, se existirem ações subsequentes que dependam da obtenção com êxito dos destinatários, deve organizar o código para iniciar essas ações apenas na função de chamada de retorno correspondente quando a chamada assíncrona tiver sido concluída com êxito.

Importante

O getAsync método só devolve destinatários resolvidos pelo cliente do Outlook. Um destinatário resolvido tem as seguintes características.

  • Se o destinatário tiver uma entrada guardada no livro de endereços do remetente, o Outlook resolve o endereço de e-mail para o nome a apresentar guardado do destinatário.
  • É apresentado um ícone de estado da reunião do Teams antes do nome ou endereço de e-mail do destinatário.
  • É apresentado um ponto e vírgula após o nome ou endereço de e-mail do destinatário.
  • O nome ou endereço de e-mail do destinatário está sublinhado ou colocado numa caixa.

Para resolver um endereço de e-mail depois de ser adicionado a um item de correio, o remetente tem de utilizar a Tecla de Tabulação ou selecionar um contacto ou endereço de e-mail sugerido a partir da lista de conclusão automática.

No Outlook na Web e no Windows (novo e clássico), se um utilizador criar uma nova mensagem ao selecionar a ligação de endereço de e-mail de um contacto a partir de um cartão de contacto ou perfil, primeiro tem de resolver o endereço de e-mail para que 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 verifica primeiro se o item de correio é um compromisso ou mensagem, para que possa chamar o método assíncrono, Recipients.setAsync, nas propriedades adequadas que representam os destinatários do compromisso ou mensagem.

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

  • 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 à devolvida pelo getAsync método .

Opcionalmente, pode fornecer uma função de chamada de retorno como um argumento de entrada para o setAsync método, para garantir que qualquer código que dependa da definição com êxito dos destinatários só será executado quando isso acontecer. Se implementar uma função de chamada de retorno, utilize as status propriedades e error do asyncResult parâmetro de saída para verificar o estado e quaisquer mensagens de erro da chamada assíncrona. Para fornecer informações adicionais à função de chamada de retorno, utilize 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 não quiser substituir os destinatários existentes num compromisso ou mensagem, em vez de utilizar Recipients.setAsync, utilize o método assíncrono Recipients.addAsync para acrescentar destinatários. addAsync funciona da mesma forma setAsync que requer um recipients argumento de entrada. Opcionalmente, pode fornecer uma função de chamada de retorno e quaisquer argumentos para a chamada de retorno com o asyncContext parâmetro . Em seguida, verifique o estado, o resultado e qualquer erro da chamada assíncrona addAsync com o asyncResult parâmetro de saída da função de chamada de retorno. O exemplo seguinte verifica se o item que está a ser composto é um compromisso e, em seguida, acrescenta dois participantes necessários ao mesmo.

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