Obter ou definir o local ao compor um compromisso no Outlook

  • Artigo

A API JavaScript do Office fornece propriedades e métodos para gerenciar o local de um compromisso que o usuário está compondo. Atualmente, há duas propriedades que fornecem o local de um compromisso:

A tabela a seguir lista as APIs de localização e os modos (ou seja, Compose ou Leitura) em que elas estão disponíveis.

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

Para usar os métodos disponíveis apenas para compor suplementos, configure o manifesto XML do suplemento para ativar o suplemento no modo Organizador/Compose. Consulte Criar suplementos do Outlook para compor formulários para obter mais detalhes. Não há suporte para regras de ativação em suplementos que usam um manifesto unificado para o Microsoft 365 (versão prévia).

Usar a enhancedLocation API

Você pode usar a enhancedLocation API para obter e definir o local de um compromisso. O campo de localização dá suporte a vários locais e, para cada local, você pode definir o nome de exibição, o tipo e o endereço de email da sala de conferência (se aplicável). Consulte LocationType para obter tipos de localização com suporte.

Adicionar localização

O exemplo a seguir mostra como adicionar um local chamando 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 a seguir mostra como obter o local chamando 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

Grupos de contatos pessoais adicionados à medida que os locais de compromisso não são retornados pelo método enhancedLocation.getAsync .

Remover local

O exemplo a seguir mostra como remover o local chamando 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]);
    });
}

Usar a location API

Você pode usar a location API para obter e definir o local 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 usar item.location.getAsync, forneça uma função de retorno de chamada que verifique o status e o resultado da chamada assíncrona. Você pode fornecer todos os argumentos necessários para a função de retorno de chamada por meio do asyncContext parâmetro opcional. Você pode obter status, resultados e qualquer erro usando o parâmetro asyncResult de saída do retorno de chamada. 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, você pode fornecer uma função de retorno de chamada e quaisquer argumentos para a função de retorno de chamada no asyncContext parâmetro. Você deve marcar o status, o resultado e qualquer mensagem de erro no asyncResult parâmetro de saída do retorno de chamada. 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

Você pode definir vários locais usando um ponto semiautônomo como separador (por exemplo, 'Sala de conferência A; Sala de conferência 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