Office.RoamingSettings interface

  • Referencia
Paquete:
outlook

La configuración creada mediante los métodos del objeto RoamingSettings se guarda por complemento y por usuario. Es decir, solo están disponibles para el complemento que los creó y solo desde el buzón del usuario en el que se guardan.

Aunque la API del complemento de Outlook limita el acceso a esta configuración solo al complemento que las creó, esta configuración no debe considerarse almacenamiento seguro. Se puede tener acceso mediante Servicios Web Exchange o la biblioteca MAPI extendida. No deben usarse para almacenar información confidencial, como credenciales de usuario o tokens de seguridad.

El nombre de una configuración es una cadena, mientras que el valor puede ser String, Number, Boolean, Null, Object o Array.

Se puede tener acceso al objeto RoamingSettings mediante la propiedad roamingSettings del espacio de nombres Office.context.

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

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Importante:

  • El RoamingSettings objeto se inicializa desde el almacenamiento persistente solo cuando se carga por primera vez el complemento. En el caso de los paneles de tareas, esto significa que solo se inicializa cuando se abre por primera vez el panel de tareas. Si el panel de tareas navega a otra página o vuelve a cargar la página actual, el objeto en memoria se restablece a sus valores iniciales, incluso si el complemento ha conservado los cambios. Los cambios persistentes no estarán disponibles hasta que se cierre y vuelva a abrir el panel de tareas (o el elemento en el caso de complementos sin interfaz de usuario).

  • Cuando se establecen y guardan a través de Outlook en Windows (nuevo o clásico) o en Mac, esta configuración se refleja en Outlook en la Web solo después de una actualización del explorador.

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Métodos

get(name)

Recupera la configuración especificada.
remove(name)

Elimina la configuración especificada.
saveAsync(callback)

Guarda la configuración.

Cualquier configuración guardada anteriormente por un complemento se carga cuando se inicializa, por lo que durante la duración de la sesión solo puede usar el conjunto y obtener métodos para trabajar con la copia en memoria del contenedor de propiedades de configuración. Cuando quiera conservar la configuración para que estén disponibles la próxima vez que se use el complemento, use el saveAsync método .
set(name, value)

Define o crea la configuración especificada.

El set método crea una nueva configuración del nombre especificado si aún no existe o establece una configuración existente del nombre especificado. El valor se almacena en el documento como la representación JSON serializada del tipo de datos correspondiente.

Hay disponible un máximo de 32 KB para la configuración de cada complemento. Se produce un error con el código 9057 cuando se supera ese límite de tamaño.

Los cambios realizados en la configuración mediante el set método no se guardarán en el servidor hasta que se llame al saveAsync método .

Detalles del método

get(name)

Recupera la configuración especificada.

get(name: string): any;

Parámetros

name

string

El nombre con distinción de mayúsculas y minúsculas de la configuración que se debe recuperar.

Devoluciones

any

Tipo: String | Número | Boolean | Objeto | Arreglo

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = $("#settingName").val();
const settingValue = Office.context.roamingSettings.get(settingName);
$("#settingValue").val(settingValue);
console.log(`The value of setting "${settingName}" is "${settingValue}".`);

remove(name)

Elimina la configuración especificada.

remove(name: string): void;

Parámetros

name

string

El nombre con distinción de mayúsculas y minúsculas de la configuración que se debe eliminar.

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

saveAsync(callback)

Guarda la configuración.

Cualquier configuración guardada anteriormente por un complemento se carga cuando se inicializa, por lo que durante la duración de la sesión solo puede usar el conjunto y obtener métodos para trabajar con la copia en memoria del contenedor de propiedades de configuración. Cuando quiera conservar la configuración para que estén disponibles la próxima vez que se use el complemento, use el saveAsync método .

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

Parámetros

callback

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

Opcional. 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.

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

// Save settings in the mailbox to make it available in future sessions.
Office.context.roamingSettings.saveAsync(function(result) {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
  } else {
    console.log(`Settings saved with status: ${result.status}`);
  }
});

set(name, value)

Define o crea la configuración especificada.

El set método crea una nueva configuración del nombre especificado si aún no existe o establece una configuración existente del nombre especificado. El valor se almacena en el documento como la representación JSON serializada del tipo de datos correspondiente.

Hay disponible un máximo de 32 KB para la configuración de cada complemento. Se produce un error con el código 9057 cuando se supera ese límite de tamaño.

Los cambios realizados en la configuración mediante el set método no se guardarán en el servidor hasta que se llame al saveAsync método .

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

Parámetros

name

string

Nombre, con distinción entre mayúsculas y minúsculas, de la configuración que se debe establecer o crear.

value

any

Especifica el valor que se debe almacenar.

Devoluciones

void

Comentarios

[ Conjunto de API: Buzón 1.1 ]

Nivel mínimo de permiso: restringido

Modo de Outlook aplicable: Compose o lectura

Ejemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = $("#settingName").val();
const settingValue = $("#settingValue").val();
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);