Conservar el estado y la configuración del complemento

Los complementos de Office son básicamente aplicaciones web que se ejecutan en el entorno sin estado de un iframe del explorador o un control de vista web. (En adelante, para mayor brevedad, en este artículo se usa "control de explorador" para significar "control de explorador o vista web"). Cuando está en uso, es posible que el complemento tenga que conservar los datos para mantener la continuidad de determinadas operaciones o características entre sesiones. Por ejemplo, es posible que su complemento tenga configuraciones personalizadas u otros valores que necesite guardar y recargar la próxima vez que se inicialice, como puede ser la vista preferida de un usuario o una ubicación predeterminada. Para hacerlo, puede:

• Use técnicas proporcionadas por el control del explorador subyacente.
• Use las API de JavaScript de Office específicas de la aplicación para Excel, Word y Outlook que almacenan datos.

Si necesita conservar el estado de los documentos, como el seguimiento de las preferencias del usuario en todos los documentos que abran, deberá usar un enfoque diferente. Por ejemplo, podría usar el inicio de sesión único para obtener la identidad del usuario y, a continuación, guardar el identificador de usuario y su configuración en una base de datos en línea.

Almacenamiento del explorador

Conservar datos en instancias de complemento con herramientas del control de explorador subyacente, como cookies de explorador o almacenamiento web HTML5 (localStorage o sessionStorage).

Algunos exploradores o la configuración del explorador del usuario pueden bloquear las técnicas de almacenamiento basadas en exploradores. Debe probar la disponibilidad como se documenta en Uso de la API de almacenamiento web.

Creación de particiones de almacenamiento

Como procedimiento recomendado, los datos privados deben almacenarse en particiones localStorage. Office.context.partitionKey proporciona una clave para su uso con el almacenamiento local. Esto garantiza que los datos almacenados en el almacenamiento local solo estén disponibles en el mismo contexto. En el ejemplo siguiente se muestra cómo usar la clave de partición con localStorage. Tenga en cuenta que la clave de partición no está definida en entornos sin particiones, como los controles del explorador para aplicaciones windows.

// Store the value "Hello" in local storage with the key "myKey1".
setInLocalStorage("myKey1", "Hello");

// ... 

// Retrieve the value stored in local storage under the key "myKey1".
const message = getFromLocalStorage("myKey1");
console.log(message);

// ...

function setInLocalStorage(key: string, value: string) {
  const myPartitionKey = Office.context.partitionKey;

  // Check if local storage is partitioned. 
  // If so, use the partition to ensure the data is only accessible by your add-in.
  if (myPartitionKey) {
    localStorage.setItem(myPartitionKey + key, value);
  } else {
    localStorage.setItem(key, value);
  }
}

function getFromLocalStorage(key: string) {
  const myPartitionKey = Office.context.partitionKey;

  // Check if local storage is partitioned.
  if (myPartitionKey) {
    return localStorage.getItem(myPartitionKey + key);
  } else {
    return localStorage.getItem(key);
  }
}

A partir de la versión 115 de los exploradores basados en Chromium, como Chrome y Edge, la creación de particiones de almacenamiento está habilitada para evitar el seguimiento entre sitios de canal lateral específico (consulte también las directivas del explorador Microsoft Edge). De forma similar a la creación de particiones basada en claves de Office, los datos almacenados por las API de almacenamiento, como el almacenamiento local, solo están disponibles para contextos con el mismo origen y el mismo sitio de nivel superior.

Configuración y persistencia específicas de la aplicación

Excel, Word y Outlook proporcionan API específicas de la aplicación para guardar la configuración y otros datos. Use estas en lugar de las API comunes mencionadas más adelante en este artículo para que el complemento siga patrones coherentes y esté optimizado para la aplicación de destino.

Configuración en Excel y Word

Las API de JavaScript específicas de la aplicación para Excel y Word también proporcionan acceso a la configuración personalizada. La configuración es única para un único emparejamiento de archivos y complementos de Excel. Para obtener más información, vea Excel.SettingCollection y Word.SettingCollection.

En el ejemplo siguiente se muestra cómo crear y acceder a una configuración en Excel. El proceso es funcionalmente equivalente en Word, que usa Document.settings en lugar de Workbook.settings.

await Excel.run(async (context) => {
    const settings = context.workbook.settings;
    settings.add("NeedsReview", true);
    const needsReview = settings.getItem("NeedsReview");
    needsReview.load("value");

    await context.sync();
    console.log("Workbook needs review : " + needsReview.value);
});

Datos XML personalizados en Excel y Word

Los formatos de archivo .xlsx y .docx de Open XML permiten que el complemento inserte datos XML personalizados en el libro de Excel o en el documento de Word. Estos datos se conservan con el archivo, independientemente del complemento.

Word.Document y Excel.Workbook contienen , CustomXmlPartCollectionque es una lista de CustomXmlParts. Estos dan acceso a las cadenas XML y a un único identificador correspondiente. Al almacenar estos identificadores como configuración, el complemento puede mantener las claves de los elementos XML entre sesiones.

En los ejemplos siguientes se muestra cómo usar elementos XML personalizados con un libro de Excel. El primer bloque de código muestra cómo insertar datos XML. Almacena una lista de revisores y luego, usa la configuración del libro para guardar el id del XML para una recuperación futura. El segundo bloque muestra cómo acceder a ese XML más adelante. La configuración de "ContosoReviewXmlPartId" se carga y se pasa al customXmlParts del libro. Luego, los datos XML se imprimen en la consola. El proceso es funcionalmente equivalente en Word, que usa Document.customXmlParts en lugar de Workbook.customXmlParts.

await Excel.run(async (context) => {
    // Add reviewer data to the document as XML
    const originalXml = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
    const customXmlPart = context.workbook.customXmlParts.add(originalXml);
    customXmlPart.load("id");
    await context.sync();

    // Store the XML part's ID in a setting
    const settings = context.workbook.settings;
    settings.add("ContosoReviewXmlPartId", customXmlPart.id);
});

Propiedades personalizadas en Excel y Word

Las propiedades Excel.DocumentProperties.custom y Word.DocumentProperties.customProperties representan colecciones de pares clave-valor para propiedades definidas por el usuario. En el siguiente ejemplo de Excel se muestra cómo crear una propiedad personalizada denominada Introduction con el valor "Hello" y, a continuación, recuperarla.

await Excel.run(async (context) => {
    const customDocProperties = context.workbook.properties.custom;
    customDocProperties.add("Introduction", "Hello");
    await context.sync();
});

// ...

await Excel.run(async (context) => {
    const customDocProperties = context.workbook.properties.custom;
    const customProperty = customDocProperties.getItem("Introduction");
    customProperty.load(["key", "value"]);
    await context.sync();

    console.log("Custom key  : " + customProperty.key); // "Introduction"
    console.log("Custom value : " + customProperty.value); // "Hello"
});

Cómo guardar la configuración en un complemento de Outlook

Para obtener información sobre cómo guardar la configuración en un complemento de Outlook, vea Obtener y establecer metadatos de complemento para un complemento de Outlook y Obtener y establecer encabezados de Internet en un mensaje en un complemento de Outlook.

Configuración y persistencia de API comunes

Las API comunes proporcionan objetos para guardar el estado del complemento entre sesiones. Los valores de configuración guardados están asociados con el identificador del complemento que los creó. Internamente, los datos a los que se accede con los Settingsobjetos , CustomPropertieso RoamingSettings se almacenan como un objeto de notación de objetos JavaScript serializado (JSON) que contiene pares nombre-valor. El nombre (clave) de cada valor debe ser , stringy el valor almacenado puede ser una función de JavaScript string, number, dateo , pero objectno una función.

Este ejemplo de la estructura del contenedor de propiedades contiene tres valores de cadena definidos denominados firstName, locationy defaultView.

{
    "firstName":"Erik",
    "location":"98052",
    "defaultView":"basic"
}

Después de que se haya guardado el contenedor de propiedades de configuración durante la sesión anterior del complemento, puede cargarse al iniciar la aplicación o en cualquier momento posterior, durante la sesión actual del complemento. Durante la sesión, la configuración se administra completamente en la memoria mediante los getmétodos , sety remove del objeto que corresponde al tipo de configuración que se va a crear (Configuración, CustomProperties o RoamingSettings).

Procedimiento para guardar la configuración y el estado de los complementos por cada documento de los complementos de panel de tareas y de contenido

Para conservar la configuración personalizada o de estado de un complemento de contenido o panel de tareas para Word, Excel o PowerPoint, use el objeto Settings y sus métodos. El contenedor de propiedades creado con los métodos del Settings objeto solo está disponible para la instancia del complemento de contenido o panel de tareas que lo creó y solo desde el documento en el que se guarda.

El Settings objeto se carga automáticamente como parte del objeto Document y está disponible cuando se activa el panel de tareas o el complemento de contenido. Después de crear una instancia del Document objeto, puede acceder al Settings objeto con la propiedad settings del Document objeto. Durante la duración de la sesión, puede usar los Settings.getmétodos , Settings.sety Settings.remove para leer, escribir o quitar la configuración persistente y el estado del complemento de la copia en memoria del contenedor de propiedades.

Dado que los métodos set y remove solo funcionan con la copia en memoria del contenedor de propiedades de configuración, para guardar la configuración nueva o modificada en el documento al que está asociado el complemento, debe llamar al método Settings.saveAsync .

Creación o actualización de un valor de configuración

En el ejemplo de código siguiente se muestra cómo usar el método Settings.set para crear una configuración llamada 'themeColor' con el valor 'green'. El primer parámetro del método set es el nombre (Id) que distingue mayúsculas de minúsculas de la configuración que se va a establecer o crear. El segundo parámetro es el valor (value) de la configuración.

Office.context.document.settings.set('themeColor', 'green');

Si la configuración no existe aún, se crea una con el nombre especificado o, si ya existe, se actualiza su valor. Use el Settings.saveAsync método para conservar la configuración nueva o actualizada en el documento.

Obtener el valor de una configuración

En el ejemplo siguiente se muestra cómo usar el método Settings.get para obtener el valor de una configuración llamada "themeColor". El único parámetro del get método es el nombre que distingue mayúsculas de minúsculas de la configuración.

write('Current value for mySetting: ' + Office.context.document.settings.get('themeColor'));

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

El get método devuelve el valor que se guardó anteriormente para el nombre de configuración que se pasó. Si la configuración no existe, el método devuelve null.

Quitar una configuración

En el ejemplo siguiente se muestra cómo usar el método Settings.remove para quitar una configuración llamada "themeColor". El único parámetro del remove método es el nombre que distingue mayúsculas de minúsculas de la configuración.

Office.context.document.settings.remove('themeColor');

No ocurrirá nada si la configuración no existe. Use el Settings.saveAsync método para conservar la eliminación de la configuración del documento.

Guardar la configuración

Para guardar las adiciones, cambios o eliminaciones que realice el complemento en la copia en memoria del contenedor de propiedades de la configuración durante la sesión actual, es necesario llamar al método Settings.saveAsync para almacenarlos en el documento. El único parámetro del método es la saveAsyncdevolución de llamada, que es una función de devolución de llamada con un único parámetro.

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

La función anónima que se pasa al saveAsync método como parámetro de devolución de llamada se ejecuta cuando se completa la operación. El parámetro asyncResult de la devolución de llamada proporciona acceso a un AsyncResult objeto que contiene el estado de la operación. En el ejemplo, la función comprueba la AsyncResult.status propiedad para ver si la operación de guardado se realizó correctamente o no y, a continuación, muestra el resultado en la página del complemento.

Cómo guardar XML personalizado en el documento

Un elemento XML personalizado es una opción de almacenamiento disponible para cuando quiera almacenar información que tenga un carácter estructurado o necesite que los datos sean accesibles entre las instancias del complemento. Tenga en cuenta que otros complementos también pueden acceder a los datos almacenados de esta manera. Puede conservar el marcado XML personalizado en un complemento de panel de tareas para Word (y para Excel y Word mediante la API específica de la aplicación, como se mencionó en el párrafo anterior). En Word, puede usar el objeto CustomXmlPart y sus métodos. El código siguiente crea un elemento XML personalizado y muestra su identificador y, a continuación, su contenido en divs en la página. Tenga en cuenta que debe haber un xmlns atributo en la cadena XML.

function createCustomXmlPart() {
    const xmlString = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
    Office.context.document.customXmlParts.addAsync(xmlString,
        (asyncResult) => {
            $("#xml-id").text("Your new XML part's ID: " + asyncResult.value.id);
            asyncResult.value.getXmlAsync(
                (asyncResult) => {
                    $("#xml-blob").text(asyncResult.value);
                }
            );
        }
    );
}

Para recuperar un elemento XML personalizado, use el método getByIdAsync , pero el identificador es un GUID que se genera cuando se crea el elemento XML, por lo que no puede saber cuándo codificar cuál es el identificador. Por ese motivo, se recomienda crear un elemento XML para almacenar inmediatamente el identificador del elemento XML como una configuración y darle una clave memorable. En el siguiente método se indica cómo hacerlo.

function createCustomXmlPartAndStoreId() {
   const xmlString = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
   Office.context.document.customXmlParts.addAsync(xmlString,
       (asyncResult) => {
           Office.context.document.settings.set('ReviewersID', asyncResult.value.id);
           Office.context.document.settings.saveAsync();
       }
   );
}

El código siguiente muestra cómo recuperar el elemento XML obteniendo en primer lugar su identificador de una configuración.

function getReviewers() {
   const reviewersXmlId = Office.context.document.settings.get('ReviewersID');
   Office.context.document.customXmlParts.getByIdAsync(reviewersXmlId,
       (asyncResult) => {
           asyncResult.value.getXmlAsync(
               (asyncResult) => {
                   $("#xml-blob").text(asyncResult.value);
               }
           );
       }
   );
}

Vea también

• Información sobre la API de JavaScript para Office
• Complementos de Outlook
• Obtener y establecer metadatos de un complemento de Outlook
• Obtener y establecer encabezados de Internet en un mensaje en un complemento de Outlook
• Excel-Add-in-JavaScript-PersistCustomSettings