Office.Settings interface

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, 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

Devoluciones

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.

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, 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

Devoluciones

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; 
}

Recupera la configuración especificada.

get(name: string): any;

Parámetros

Devoluciones

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; 
}

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

Devoluciones

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.

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; 
}

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

Devoluciones

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');
}

Quita un controlador de eventos para el evento settingsChanged.

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

Parámetros

Devoluciones

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.

Quita un controlador de eventos para el evento settingsChanged.

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

Parámetros

Devoluciones

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.

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; 
}

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

Devoluciones

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.

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

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

Parámetros

Devoluciones

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.

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; 
}

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

Devoluciones

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');
}