Compartir a través de

Obtener o establecer la ubicación al redactar una cita en Outlook

  • Artículo

La API de JavaScript de Office proporciona propiedades y métodos para administrar la ubicación de una cita que el usuario está redactando. Actualmente, hay dos propiedades que proporcionan la ubicación de una cita:

  • item.location: API básica que permite obtener y establecer la ubicación.
  • item.enhancedLocation: API mejorada que permite obtener y establecer la ubicación, e incluye especificar el tipo de ubicación. El tipo es LocationType.Custom si establece la ubicación mediante item.location.

En la tabla siguiente se enumeran las API de ubicación y los modos (es decir, Compose o Lectura) donde están disponibles.

API Modos de cita aplicables
item.location Asistente/Lectura
item.location.getAsync Organizador/Compose
item.location.setAsync Organizador/Compose
item.enhancedLocation.getAsync Organizador/Compose,
Asistente/Lectura
item.enhancedLocation.addAsync Organizador/Compose
item.enhancedLocation.removeAsync Organizador/Compose

Para usar los métodos que solo están disponibles para crear complementos, configure el manifiesto de solo complemento para activar el complemento en el modo Organizador/Compose. Vea Crear complementos de Outlook para formularios de redacción para obtener más detalles. Las reglas de activación no se admiten en complementos que usan un manifiesto unificado para Microsoft 365.

Uso de la enhancedLocation API

Puede usar la enhancedLocation API para obtener y establecer la ubicación de una cita. El campo de ubicación admite varias ubicaciones y, para cada ubicación, puede establecer el nombre para mostrar, el tipo y la dirección de correo electrónico de la sala de conferencias (si procede). Consulte LocationType para ver los tipos de ubicación admitidos.

Agregar ubicación

En el ejemplo siguiente se muestra cómo agregar una ubicación llamando a addAsync en 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);
    });
}

Obtener ubicación

En el ejemplo siguiente se muestra cómo obtener la ubicación llamando a getAsync en 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);
        }
    });
}

Nota:

El método enhancedLocation.getAsync no devuelve los grupos de contactos personales agregados como ubicaciones de citas.

Quitar ubicación

En el ejemplo siguiente se muestra cómo quitar la ubicación llamando a removeAsync en 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]);
    });
}

Uso de la location API

Puede usar la location API para obtener y establecer la ubicación de una cita.

Obtener la ubicación

En esta sección, se muestra un ejemplo de código que obtiene la ubicación de la cita que redacta el usuario y muestra la ubicación.

Para usar item.location.getAsync, proporcione una función de devolución de llamada que compruebe el estado y el resultado de la llamada asincrónica. Puede proporcionar los argumentos necesarios a la función de devolución de llamada a través del asyncContext parámetro opcional. Puede obtener el estado, los resultados y cualquier error mediante el parámetro asyncResult de salida de la devolución de llamada. Si la llamada asincrónica se realiza correctamente, puede obtener la ubicación como una cadena con la propiedad 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;
}

Establecer la ubicación

En esta sección, se muestra un ejemplo de código que establece la ubicación de la cita que redacta el usuario.

Para usar item.location.setAsync, especifique una cadena de un máximo de 255 caracteres en el parámetro de datos. Opcionalmente, puede proporcionar una función de devolución de llamada y cualquier argumento para la función de devolución de llamada en el asyncContext parámetro . Debe comprobar el estado, el resultado y cualquier mensaje de error en el asyncResult parámetro de salida de la devolución de llamada. Si la llamada asincrónica se realiza correctamente, setAsync inserta la cadena de ubicación especificada como texto sin formato, que reemplaza cualquier ubicación existente para ese elemento.

Nota:

Puede establecer varias ubicaciones usando un punto y coma como separador (por ejemplo, "Sala de conferenciaS A; Sala de conferencias 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;
}

Vea también