Office.Settings interface

Paquete:

office

Representa la configuración personalizada de un complemento de panel de tareas o de contenido que se almacena en el documento host como pares de nombre y valor.

Comentarios

Aplicaciones: Excel, PowerPoint, Word

La configuración creada mediante los métodos del objeto Settings se guarda por complemento y por documento. Es decir, solo está disponible para el complemento que la creó y solo desde el documento en el que se guarda.

El nombre de una configuración es una cadena, mientras que el valor puede ser una cadena, un número, un booleano, un valor NULL, un objeto o una matriz.

El objeto Settings se carga automáticamente como parte del objeto Document y está disponible llamando a la propiedad settings de ese objeto cuando se activa el complemento.

El desarrollador es responsable de llamar al método saveAsync después de agregar o suprimir la configuración para guardar la configuración en el documento.

Métodos

addHandlerAsync(eventType, handler, options, callback)	Agrega un controlador de eventos para el evento settingsChanged. Importante: El código del complemento puede registrar un controlador para el evento settingsChanged cuando el complemento se ejecuta con cualquier cliente de Excel, pero el evento se desencadenará solo cuando el complemento se cargue con una hoja de cálculo que se abra en Excel en la Web y más de un usuario edite la hoja de cálculo (coautoría). Por lo tanto, de forma eficaz, el evento settingsChanged solo se admite en Excel en la Web en escenarios de coautoría.
addHandlerAsync(eventType, handler, callback)	Agrega un controlador de eventos para el evento settingsChanged. Importante: El código del complemento puede registrar un controlador para el evento settingsChanged cuando el complemento se ejecuta con cualquier cliente de Excel, pero el evento se desencadenará solo cuando el complemento se cargue con una hoja de cálculo que se abra en Excel en la Web y más de un usuario edite la hoja de cálculo (coautoría). Por lo tanto, de forma eficaz, el evento settingsChanged solo se admite en Excel en la Web en escenarios de coautoría.
get(name)	Recupera la configuración especificada.
refreshAsync(callback)	Lee toda la configuración que se conserva en el documento y actualiza la copia de dicha configuración del complemento de contenido o del panel de tareas, que se conserva en la memoria.
remove(name)	Elimina la configuración especificada. Importante: Tenga en cuenta que el método Settings.remove solo afecta a la copia en memoria del contenedor de propiedades de configuración. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.
removeHandlerAsync(eventType, options, callback)	Quita un controlador de eventos para el evento settingsChanged.
removeHandlerAsync(eventType, callback)	Quita un controlador de eventos para el evento settingsChanged.
saveAsync(options, callback)	Mantiene la copia en memoria del contenedor de propiedades de configuración en el documento.
saveAsync(callback)	Mantiene la copia en memoria del contenedor de propiedades de configuración en el documento.
set(name, value)	Define o crea la configuración especificada. Importante: Tenga en cuenta que el método Settings.set solo afecta a la copia en memoria del contenedor de propiedades de configuración. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

Detalles del método

addHandlerAsync(eventType, handler, options, callback)

Agrega un controlador de eventos para el evento settingsChanged.

Importante: El código del complemento puede registrar un controlador para el evento settingsChanged cuando el complemento se ejecuta con cualquier cliente de Excel, pero el evento se desencadenará solo cuando el complemento se cargue con una hoja de cálculo que se abra en Excel en la Web y más de un usuario edite la hoja de cálculo (coautoría). Por lo tanto, de forma eficaz, el evento settingsChanged solo se admite en Excel en la Web en escenarios de coautoría.

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Parámetros

eventType

Office.EventType

Especifica el tipo de evento que se debe agregar. Obligatorio.

handler

any

Función del controlador de eventos que se va a agregar, cuyo único parámetro es de tipo Office.SettingsChangedEventArgs. Obligatorio.

options

Office.AsyncContextOptions

Proporciona una opción para conservar los datos de contexto de cualquier tipo, sin cambios, para su uso en una devolución de llamada.

callback

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

Opcional. Función que se invoca cuando se devuelve la devolución de llamada, cuyo único parámetro es de tipo Office.AsyncResult.

Propiedad	Utilice
AsyncResult.value	Siempre devuelve undefined porque no hay datos ni objetos que recuperar al agregar un controlador de eventos.
AsyncResult.status	Determinar si la operación se ha completado correctamente o no.
AsyncResult.error	Tener acceso a un objeto Error que proporcione información sobre el error si la operación no se ha llevado a cabo correctamente.
AsyncResult.asyncContext	Defina un elemento de cualquier tipo que se devuelva en el objeto AsyncResult sin modificarse.

Devoluciones

void

Comentarios

Conjunto de requisitos: no en un conjunto

Puede agregar varios controladores de eventos para el eventType especificado siempre y cuando el nombre de cada función de controlador de eventos sea único.

addHandlerAsync(eventType, handler, callback)

Agrega un controlador de eventos para el evento settingsChanged.

Importante: El código del complemento puede registrar un controlador para el evento settingsChanged cuando el complemento se ejecuta con cualquier cliente de Excel, pero el evento se desencadenará solo cuando el complemento se cargue con una hoja de cálculo que se abra en Excel en la Web y más de un usuario edite la hoja de cálculo (coautoría). Por lo tanto, de forma eficaz, el evento settingsChanged solo se admite en Excel en la Web en escenarios de coautoría.

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult<void>) => void): void;

Parámetros

eventType

Office.EventType

Especifica el tipo de evento que se debe agregar. Obligatorio.

handler

any

Función del controlador de eventos que se va a agregar, cuyo único parámetro es de tipo Office.SettingsChangedEventArgs. Obligatorio.

callback

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

Opcional. Función que se invoca cuando se devuelve la devolución de llamada, cuyo único parámetro es de tipo Office.AsyncResult.

Propiedad	Utilice
AsyncResult.value	Siempre devuelve undefined porque no hay datos ni objetos que recuperar al agregar un controlador de eventos.
AsyncResult.status	Determinar si la operación se ha completado correctamente o no.
AsyncResult.error	Tener acceso a un objeto Error que proporcione información sobre el error si la operación no se ha llevado a cabo correctamente.
AsyncResult.asyncContext	Defina un elemento de cualquier tipo que se devuelva en el objeto AsyncResult sin modificarse.

Devoluciones

void

Comentarios

Conjunto de requisitos: no en un conjunto

Puede agregar varios controladores de eventos para el eventType especificado siempre y cuando el nombre de cada función de controlador de eventos sea único.

Ejemplos

function addSelectionChangedEventHandler() {
    Office.context.document.settings.addHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

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

get(name)

Recupera la configuración especificada.

get(name: string): any;

Parámetros

name

string

Devoluciones

any

Objeto que tiene nombres de propiedad asignados a valores serializados JSON.

Comentarios

Conjunto de requisitos: Configuración

Ejemplos

function displayMySetting() {
    write('Current value for mySetting: ' + Office.context.document.settings.get('mySetting'));
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

refreshAsync(callback)

Lee toda la configuración que se conserva en el documento y actualiza la copia de dicha configuración del complemento de contenido o del panel de tareas, que se conserva en la memoria.

refreshAsync(callback?: (result: AsyncResult<Office.Settings>) => void): void;

Parámetros

callback

(result: Office.AsyncResult<Office.Settings>) => void

Opcional. Función que se invoca cuando se devuelve la devolución de llamada, cuyo único parámetro es de tipo Office.AsyncResult. La value propiedad del resultado es un objeto Office.Settings con los valores actualizados.

Devoluciones

void

Comentarios

Conjunto de requisitos: no en un conjunto

Este método es útil en escenarios de coautoría de Excel, Word y PowerPoint cuando varias instancias del mismo complemento funcionan en el mismo documento. Dado que cada complemento funciona con una copia en memoria de la configuración cargada desde el documento en el momento en que el usuario lo abrió, los valores de configuración utilizados por cada usuario pueden salir de la sincronización. Esto puede ocurrir siempre que una instancia del complemento llame al método Settings.saveAsync para conservar toda la configuración de ese usuario en el documento. Al llamar al método refreshAsync desde el controlador de eventos para el evento settingsChanged del complemento, se actualizarán los valores de configuración de todos los usuarios.

In the callback function passed to the refreshAsync method, you can use the properties of the AsyncResult object to return the following information.

Propiedad	Utilice
AsyncResult.value	Tener acceso a un objeto Settings con los valores actualizados.
AsyncResult.status	Determinar si la operación se ha completado correctamente o no.
AsyncResult.error	Tener acceso a un objeto Error que proporcione información sobre el error si la operación no se ha llevado a cabo correctamente.
AsyncResult.asyncContext	Defina un elemento de cualquier tipo que se devuelva en el objeto AsyncResult sin modificarse.

Ejemplos

function refreshSettings() {
    Office.context.document.settings.refreshAsync(function (asyncResult) {
        write('Settings refreshed with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

remove(name)

Elimina la configuración especificada.

Importante: Tenga en cuenta que el método Settings.remove solo afecta a la copia en memoria del contenedor de propiedades de configuración. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.

remove(name: string): void;

Parámetros

name

string

Devoluciones

void

Comentarios

Conjunto de requisitos: Configuración

null es un valor válido para una configuración. Por lo tanto, si se asigna null a la configuración, no se eliminará del contenedor de propiedades de la configuración.

Ejemplos

function removeMySetting() {
    Office.context.document.settings.remove('mySetting');
}

removeHandlerAsync(eventType, options, callback)

Quita un controlador de eventos para el evento settingsChanged.

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

Parámetros

eventType

Office.EventType

Especifica el tipo de evento que se debe quitar. Obligatorio.

options

Office.RemoveHandlerOptions

Proporciona opciones para determinar qué controladores o controladores de eventos se quitan.

callback

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

Opcional. Función que se invoca cuando se devuelve la devolución de llamada, cuyo único parámetro es de tipo Office.AsyncResult.

Devoluciones

void

Comentarios

Conjunto de requisitos: no en un conjunto

Si se omite el parámetro de controlador opcional al llamar al método removeHandlerAsync, se quitarán todos los controladores de eventos para el eventType especificado.

Cuando se ejecuta la función que pasó al parámetro callback, recibe un objeto AsyncResult al que puede acceder desde el único parámetro de la función de devolución de llamada.

En la función de devolución de llamada que se ha remitido al método removeHandlerAsync, puede usar las propiedades del objeto AsyncResult para devolver la información siguiente.

Propiedad	Utilice
AsyncResult.value	Siempre devuelve undefined porque no hay datos ni objetos que recuperar al establecer formatos.
AsyncResult.status	Determinar si la operación se ha completado correctamente o no.
AsyncResult.error	Tener acceso a un objeto Error que proporcione información sobre el error si la operación no se ha llevado a cabo correctamente.
AsyncResult.asyncContext	Defina un elemento de cualquier tipo que se devuelva en el objeto AsyncResult sin modificarse.

removeHandlerAsync(eventType, callback)

Quita un controlador de eventos para el evento settingsChanged.

removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult<void>) => void): void;

Parámetros

eventType

Office.EventType

Especifica el tipo de evento que se debe quitar. Obligatorio.

callback

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

Opcional. Función que se invoca cuando se devuelve la devolución de llamada, cuyo único parámetro es de tipo Office.AsyncResult.

Devoluciones

void

Comentarios

Conjunto de requisitos: no en un conjunto

Si se omite el parámetro de controlador opcional al llamar al método removeHandlerAsync, se quitarán todos los controladores de eventos para el eventType especificado.

Cuando se ejecuta la función que pasó al parámetro callback, recibe un objeto AsyncResult al que puede acceder desde el único parámetro de la función de devolución de llamada.

En la función de devolución de llamada que se ha remitido al método removeHandlerAsync, puede usar las propiedades del objeto AsyncResult para devolver la información siguiente.

Propiedad	Utilice
AsyncResult.value	Siempre devuelve undefined porque no hay datos ni objetos que recuperar al establecer formatos.
AsyncResult.status	Determinar si la operación se ha completado correctamente o no.
AsyncResult.error	Tener acceso a un objeto Error que proporcione información sobre el error si la operación no se ha llevado a cabo correctamente.
AsyncResult.asyncContext	Defina un elemento de cualquier tipo que se devuelva en el objeto AsyncResult sin modificarse.

Ejemplos

function removeSettingsChangedEventHandler() {
    Office.context.document.settings.removeHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

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

saveAsync(options, callback)

Mantiene la copia en memoria del contenedor de propiedades de configuración en el documento.

saveAsync(options?: SaveSettingsOptions, callback?: (result: AsyncResult<void>) => void): void;

Parámetros

options

Office.SaveSettingsOptions

Proporciona opciones para guardar la configuración.

callback

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

Opcional. Función que se invoca cuando se devuelve la devolución de llamada, cuyo único parámetro es de tipo Office.AsyncResult.

Devoluciones

void

Comentarios

Conjunto de requisitos: 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 los métodos set y get para trabajar con la copia en memoria del contenedor de propiedades de configuración. Cuando quieras conservar la configuración para que estén disponibles la próxima vez que se use el complemento, usa el método saveAsync.

Nota: El método saveAsync conserva el contenedor de propiedades de configuración en memoria en el archivo de documento. Sin embargo, los cambios en el propio archivo de documento solo se guardan cuando el usuario (o la configuración de Autorrecuperación) guarda el documento en el sistema de archivos. El método refreshAsync solo es útil en escenarios de coautoría cuando otras instancias del mismo complemento pueden cambiar la configuración y esos cambios deben estar disponibles para todas las instancias.

Propiedad	Utilice
AsyncResult.value	Siempre devuelve undefined porque no hay ningún objeto o datos que recuperar.
AsyncResult.status	Determinar si la operación se ha completado correctamente o no.
AsyncResult.error	Tener acceso a un objeto Error que proporcione información sobre el error si la operación no se ha llevado a cabo correctamente.
AsyncResult.asyncContext	Defina un elemento de cualquier tipo que se devuelva en el objeto AsyncResult sin modificarse.

saveAsync(callback)

Mantiene la copia en memoria del contenedor de propiedades de configuración en el documento.

saveAsync(callback?: (result: AsyncResult<void>) => void): void;

Parámetros

callback

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

Opcional. Función que se invoca cuando se devuelve la devolución de llamada, cuyo único parámetro es de tipo Office.AsyncResult.

Devoluciones

void

Comentarios

Conjunto de requisitos: 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 los métodos set y get para trabajar con la copia en memoria del contenedor de propiedades de configuración. Cuando quieras conservar la configuración para que estén disponibles la próxima vez que se use el complemento, usa el método saveAsync.

Nota: El método saveAsync conserva el contenedor de propiedades de configuración en memoria en el archivo de documento. Sin embargo, los cambios en el propio archivo de documento solo se guardan cuando el usuario (o la configuración de Autorrecuperación) guarda el documento en el sistema de archivos. El método refreshAsync solo es útil en escenarios de coautoría cuando otras instancias del mismo complemento pueden cambiar la configuración y esos cambios deben estar disponibles para todas las instancias.

Propiedad	Utilice
AsyncResult.value	Siempre devuelve undefined porque no hay ningún objeto o datos que recuperar.
AsyncResult.status	Determinar si la operación se ha completado correctamente o no.
AsyncResult.error	Tener acceso a un objeto Error que proporcione información sobre el error si la operación no se ha llevado a cabo correctamente.
AsyncResult.asyncContext	Defina un elemento de cualquier tipo que se devuelva en el objeto AsyncResult sin modificarse.

Ejemplos

function persistSettings() {
    Office.context.document.settings.saveAsync(function (asyncResult) {
        write('Settings saved with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

set(name, value)

Define o crea la configuración especificada.

Importante: Tenga en cuenta que el método Settings.set solo afecta a la copia en memoria del contenedor de propiedades de configuración. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

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

Parámetros

name

string

value

any

Especifica el valor que se debe almacenar.

Devoluciones

void

Comentarios

Conjunto de requisitos: Configuración

El método set crea una nueva configuración del nombre especificado si aún no existe, o establece una configuración existente del nombre especificado en la copia en memoria del contenedor de propiedades de configuración. Tras llamar al método Settings.saveAsync, el valor se almacena en el documento como la representación JSON en serie del tipo de datos correspondiente.

Ejemplos

function setMySetting() {
    Office.context.document.settings.set('mySetting', 'mySetting value');
}