Office.CustomProperties interface

  • Referencia
Paquete:
outlook

El CustomProperties objeto representa propiedades personalizadas que son específicas de un elemento de correo determinado y específicas de un complemento de Outlook. Por ejemplo, es posible que sea necesario que un complemento guarde algunos datos específicos del mensaje actual que activó el complemento. Si el usuario vuelve a visitar el mismo mensaje en el futuro y vuelve a activar el complemento, el complemento podrá recuperar los datos guardados como propiedades personalizadas.

Para obtener más información sobre CustomProperties, vea Obtener y establecer metadatos de complemento para un complemento de Outlook.

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Al usar propiedades personalizadas en el complemento, tenga en cuenta lo siguiente:

  • Las propiedades personalizadas guardadas mientras están en modo de redacción no se transmiten a los destinatarios del elemento de correo. Cuando se envía un mensaje o una cita con propiedades personalizadas, se puede acceder a sus propiedades desde el elemento de la carpeta Elementos enviados. Si desea que los datos personalizados sean accesibles para los destinatarios, considere la posibilidad de usar InternetHeaders en su lugar.

  • La longitud máxima de un CustomProperties objeto JSON es de 2500 caracteres.

  • Outlook en Mac no almacena en caché las propiedades personalizadas. Si la red del usuario deja de funcionar, los complementos de correo no pueden acceder a sus propiedades personalizadas.

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Redacción o lectura

Métodos

get(name)

Devuelve el valor de la propiedad personalizada especificada.
getAll()

Devuelve un objeto con todas las propiedades personalizadas de una colección de pares nombre-valor. Las siguientes son equivalentes.

customProps.get("name")

var dictionary = customProps.getAll(); dictionary["name"]

Puede recorrer en iteración el objeto de diccionario para detectar todo names y values.
remove(name)

Elimina la propiedad especificada de la colección de propiedades personalizadas.

Para que la eliminación de la propiedad sea permanente, debe llamar al método saveAsync del objeto CustomProperties.
saveAsync(callback, asyncContext)

Guarda las propiedades personalizadas en un mensaje o una cita.

Debe llamar al método saveAsync para almacenar cualquier cambio realizado con el método set o el método remove del objeto CustomProperties. La acción de guardado es asincrónica.

Es recomendable que la función de devolución de llamada compruebe y controle los errores de saveAsync. En particular, un complemento de lectura puede activarse mientras el usuario está en un estado de conexión en un formulario de lectura y, posteriormente, se desconecta al usuario. Si el complemento llama a saveAsync en el estado desconectado, saveAsync devolverá un error. La función de devolución de llamada debe controlar este error en consecuencia.
saveAsync(asyncContext)

Guarda las propiedades personalizadas en un mensaje o una cita.

Debe llamar al método saveAsync para almacenar cualquier cambio realizado con el método set o el método remove del objeto CustomProperties. La acción de guardado es asincrónica.

Es recomendable que la función de devolución de llamada compruebe y controle los errores de saveAsync. En particular, un complemento de lectura puede activarse mientras el usuario está en un estado de conexión en un formulario de lectura y, posteriormente, se desconecta al usuario. Si el complemento llama a saveAsync en el estado desconectado, saveAsync devolverá un error. La función de devolución de llamada debe controlar este error en consecuencia.
set(name, value)

Configura la propiedad especificada al valor especificado.

El método set configura la propiedad especificada al valor especificado. Para asegurarse de que la propiedad set y el valor persisten en el elemento de correo, debe llamar al saveAsync método .

El set método crea una nueva propiedad si la propiedad especificada aún no existe; de lo contrario, el valor existente se reemplaza por el nuevo valor. El value parámetro puede ser de cualquier tipo; sin embargo, siempre se pasa al servidor como una cadena.

Detalles del método

get(name)

Devuelve el valor de la propiedad personalizada especificada.

get(name: string): any;

Parámetros

name

string

Nombre de la propiedad personalizada que se devolverá.

Devoluciones

any

Valor de la propiedad personalizada especificada.

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Redacción o lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = $("#propertyName").val();
const propertyValue = customProps.get(propertyName);
$("#propertyValue").val(propertyValue);
console.log(`The value of custom property "${propertyName}" is "${propertyValue}".`);

getAll()

Devuelve un objeto con todas las propiedades personalizadas de una colección de pares nombre-valor. Las siguientes son equivalentes.

customProps.get("name")

var dictionary = customProps.getAll(); dictionary["name"]

Puede recorrer en iteración el objeto de diccionario para detectar todo names y values.

getAll(): any;

Devoluciones

any

Objeto con todas las propiedades personalizadas de una colección de pares nombre-valor.

Comentarios

[ Conjunto de API: Buzón 1.9 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Redacción o lectura

remove(name)

Elimina la propiedad especificada de la colección de propiedades personalizadas.

Para que la eliminación de la propiedad sea permanente, debe llamar al método saveAsync del objeto CustomProperties.

remove(name: string): void;

Parámetros

name

string

de name la propiedad que se va a quitar.

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Redacción o lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = $("#propertyName").val();
customProps.remove(propertyName);
console.log(`Custom property "${propertyName}" removed.`);

saveAsync(callback, asyncContext)

Guarda las propiedades personalizadas en un mensaje o una cita.

Debe llamar al método saveAsync para almacenar cualquier cambio realizado con el método set o el método remove del objeto CustomProperties. La acción de guardado es asincrónica.

Es recomendable que la función de devolución de llamada compruebe y controle los errores de saveAsync. En particular, un complemento de lectura puede activarse mientras el usuario está en un estado de conexión en un formulario de lectura y, posteriormente, se desconecta al usuario. Si el complemento llama a saveAsync en el estado desconectado, saveAsync devolverá un error. La función de devolución de llamada debe controlar este error en consecuencia.

saveAsync(callback: (asyncResult: Office.AsyncResult<void>) => void, asyncContext?: any): void;

Parámetros

callback

(asyncResult: Office.AsyncResult<void>) => void

Cuando se completa el método, se llama a la función pasada en el callback parámetro con un único parámetro de tipo Office.AsyncResult.

asyncContext

any

Opcional. Los datos de estado que se pasan a la función de devolución de llamada.

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Importante: En Outlook en Windows, las propiedades personalizadas guardadas mientras están en modo de redacción solo persisten después de que se cierre o se Office.context.mailbox.item.saveAsync llame al elemento que se va a componer.

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Redacción o lectura

Ejemplos

// The following JavaScript code sample shows how to asynchronously use
// the loadCustomPropertiesAsync method to load custom properties that
// are specific to the current item, and the saveAsync method to save
// these to the mail item. After loading the custom properties,
// the code sample uses the get method to read the custom property myProp,
// the set method to write the custom property myProp, and then finally
// calls the saveAsync method to save the custom properties.

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, add-in-specific code can run.
        const item = Office.context.mailbox.item;
        item.loadCustomPropertiesAsync(customPropsCallback);
    });
};

function customPropsCallback(asyncResult) {
    const customProps = asyncResult.value;
    const myProp = customProps.get("myProp");
    console.log("myProp: " + myProp); // First run on current item will return `undefined`.

    // Set myProp custom property.
    customProps.set("myProp", "value");
    customProps.saveAsync(saveCallback);
}

function saveCallback(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error(asyncResult.error.message);
    }
    else {
        // Async call to save custom properties completed.
        // Proceed to do the appropriate for your add-in.
    }
}

saveAsync(asyncContext)

Guarda las propiedades personalizadas en un mensaje o una cita.

Debe llamar al método saveAsync para almacenar cualquier cambio realizado con el método set o el método remove del objeto CustomProperties. La acción de guardado es asincrónica.

Es recomendable que la función de devolución de llamada compruebe y controle los errores de saveAsync. En particular, un complemento de lectura puede activarse mientras el usuario está en un estado de conexión en un formulario de lectura y, posteriormente, se desconecta al usuario. Si el complemento llama a saveAsync en el estado desconectado, saveAsync devolverá un error. La función de devolución de llamada debe controlar este error en consecuencia.

saveAsync(asyncContext?: any): void;

Parámetros

asyncContext

any

Opcional. Los datos de estado que se pasan a la función de devolución de llamada.

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Redacción o lectura

set(name, value)

Configura la propiedad especificada al valor especificado.

El método set configura la propiedad especificada al valor especificado. Para asegurarse de que la propiedad set y el valor persisten en el elemento de correo, debe llamar al saveAsync método .

El set método crea una nueva propiedad si la propiedad especificada aún no existe; de lo contrario, el valor existente se reemplaza por el nuevo valor. El value parámetro puede ser de cualquier tipo; sin embargo, siempre se pasa al servidor como una cadena.

set(name: string, value: string): void;

Parámetros

name

string

Nombre de la propiedad que se va a configurar.

value

string

Valor de la propiedad que se va a configurar.

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: elemento de lectura

Modo de Outlook aplicable: Redacción o lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = $("#propertyName").val();
const propertyValue = $("#propertyValue").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);