Partilhar via

Obter ou definir o local ao compor um compromisso no Outlook

  • Artigo

A API javaScript do Office fornece propriedades e métodos para gerir a localização de um compromisso que o utilizador está a compor. Atualmente, existem duas propriedades que fornecem a localização de um compromisso:

  • item.location: API Básica que lhe permite obter e definir a localização.
  • item.enhancedLocation: API avançada que lhe permite obter e definir a localização e inclui especificar o tipo de localização. O tipo é LocationType.Custom se definir a localização com item.location.

A tabela seguinte lista as APIs de localização e os modos (ou seja, Compor ou Ler) onde estão disponíveis.

API Modos de compromisso aplicáveis
item.location Participante/Leitura
item.location.getAsync Organizador/Compor
item.location.setAsync Organizador/Compor
item.enhancedLocation.getAsync Organizador/Compor,
Participante/Leitura
item.enhancedLocation.addAsync Organizador/Compor
item.enhancedLocation.removeAsync Organizador/Compor

Para utilizar os métodos que estão disponíveis apenas para compor suplementos, configure o manifesto apenas de suplemento para ativar o suplemento no modo Organizador/Compor. Consulte Criar suplementos do Outlook para compor formulários para obter mais detalhes. As regras de ativação não são suportadas em suplementos que utilizam um manifesto unificado para o Microsoft 365.

Utilizar a enhancedLocation API

Pode utilizar a enhancedLocation API para obter e definir a localização de um compromisso. O campo de localização suporta várias localizações e, para cada localização, pode definir o nome a apresentar, o tipo e o endereço de e-mail da sala de conferências (se aplicável). Veja LocationType para obter os tipos de localização suportados.

Adicionar localização

O exemplo seguinte mostra como adicionar uma localização ao chamar addAsync em mailbox.item.enhancedLocation.

let item;
const locations = [
    {
        "id": "Contoso",
        "type": Office.MailboxEnums.LocationType.Custom
    }
];

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Check for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Add to the location of the item being composed.
        item.enhancedLocation.addAsync(locations);
    });
}

Obter localização

O exemplo seguinte mostra como obter a localização ao chamar getAsync em mailbox.item.enhancedLocation.

let item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get the location of the item being composed.
        item.enhancedLocation.getAsync(callbackFunction);
    });
}

function callbackFunction(asyncResult) {
    asyncResult.value.forEach(function (place) {
        console.log("Display name: " + place.displayName);
        console.log("Type: " + place.locationIdentifier.type);
        if (place.locationIdentifier.type === Office.MailboxEnums.LocationType.Room) {
            console.log("Email address: " + place.emailAddress);
        }
    });
}

Observação

Os grupos de contactos pessoais adicionados como localizações de compromisso não são devolvidos pelo método enhancedLocation.getAsync .

Remover localização

O exemplo seguinte mostra como remover a localização ao chamar removeAsync em mailbox.item.enhancedLocation.

let item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get the location of the item being composed.
        item.enhancedLocation.getAsync(callbackFunction);
    });
}

function callbackFunction(asyncResult) {
    asyncResult.value.forEach(function (currentValue) {
        // Remove each location from the item being composed.
        item.enhancedLocation.removeAsync([currentValue.locationIdentifier]);
    });
}

Utilizar a location API

Pode utilizar a location API para obter e definir a localização de um compromisso.

Obter o local

Esta seção mostra um exemplo de código que obtém o local do compromisso que o usuário está compondo e o exibe.

Para utilizar item.location.getAsync, forneça uma função de chamada de retorno que verifique o estado e o resultado da chamada assíncrona. Pode fornecer os argumentos necessários à função de chamada de retorno através do asyncContext parâmetro opcional. Pode obter o estado, os resultados e qualquer erro com o parâmetro asyncResult de saída da chamada de retorno. Se a chamada assíncrona for bem-sucedida, você poderá obter o local como uma cadeia de caracteres usando a propriedade AsyncResult.value.

let item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get the location of the item being composed.
        getLocation();
    });
}

// Get the location of the item that the user is composing.
function getLocation() {
    item.location.getAsync(
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Successfully got the location, display it.
                write ('The location is: ' + asyncResult.value);
            }
        });
}

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

Definir o local

Esta seção mostra um exemplo de código que define a localização do compromisso que o usuário está redigindo.

Para usar item.location.setAsync, especifique uma cadeia de até 255 caracteres no parâmetro de dados. Opcionalmente, pode fornecer uma função de chamada de retorno e quaisquer argumentos para a função de chamada de retorno no asyncContext parâmetro . Deve verificar o estado, o resultado e qualquer mensagem de erro no asyncResult parâmetro de saída da chamada de retorno. Se a chamada assíncrona for bem-sucedida, setAsync inserirá a cadeia de caracteres de local especificada como texto sem formatação, substituindo o local existente pelo item.

Observação

Pode definir várias localizações utilizando um ponto e vírgula como separador (por exemplo, "Sala de conferências A; Sala de conferências B').

let item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Check for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Set the location of the item being composed.
        setLocation();
    });
}

// Set the location of the item that the user is composing.
function setLocation() {
    item.location.setAsync(
        'Conference room A',
        { asyncContext: { var1: 1, var2: 2 } },
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Successfully set the location.
                // Do whatever is appropriate for your scenario,
                // using the arguments var1 and var2 as applicable.
            }
        });
}

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

Confira também