Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Los complementos de Office son básicamente aplicaciones web que se ejecutan en el entorno sin estado de un explorador, iframe o un control webview. Para abreviar, en este artículo se usa "control de explorador" para referirse a "control de explorador o vista web". Cuando está en uso, es posible que el complemento necesite conservar datos para mantener la continuidad de determinadas operaciones o características en todas las sesiones. Por ejemplo, el complemento podría tener una configuración personalizada u otros valores que necesita guardar y volver a cargar la próxima vez que se inicialice, como la vista preferida de un usuario o la ubicación predeterminada. Para conservar los datos, puede:
- Utilice las técnicas proporcionadas por el control de explorador subyacente.
- Use las API de JavaScript de Office específicas de la aplicación para Excel, Word y Outlook que almacenan datos.
Si el complemento necesita conservar datos de nivel de usuario, como preferencias o historial de conversaciones, use una base de datos en línea asociada a la identidad del usuario en lugar de depender únicamente del almacenamiento del explorador. Este enfoque mantiene los datos disponibles en todas las sesiones y documentos, incluso si el almacenamiento del explorador local se borra o deja de estar disponible. Por ejemplo, podría usar SSO para obtener la identidad del usuario y asociar sus datos guardados a esa identidad en una base de datos.
Nota:
Este artículo solo se aplica al estado persistente en la misma aplicación de Office. No use cookies ni localStorage conserve o comparta estados entre aplicaciones de Office (por ejemplo, no guarde datos en Word e intente leerlos en Excel). No se admite la persistencia entre aplicaciones y no se garantiza que funcione en ninguna plataforma.
Almacenamiento del explorador
Conservar los datos en las instancias del complemento mediante herramientas del control de explorador subyacente, como las cookies del explorador o el almacenamiento web HTML5 (localStorage o sessionStorage).
Nota:
El almacenamiento del explorador está vinculado al explorador o al perfil de vista web y el usuario puede borrarlo, incluso a través de las operaciones de borrado de caché del complemento de Office. Úselo para datos temporales o recuperables, o como una memoria caché local, en lugar de la única copia conservada de datos de usuario importantes.
Algunos exploradores o la configuración del explorador del usuario pueden bloquear las técnicas de almacenamiento basadas en el explorador. Compruebe la disponibilidad como se documenta en Uso de la API de almacenamiento web.
Creación de particiones de almacenamiento
Almacene los datos privados en archivos localStoragecon particiones. Use Office.context.partitionKey como una clave para el almacenamiento local. Este enfoque garantiza que los datos almacenados en el almacenamiento local solo estén disponibles en el mismo contexto.
Nota:
La clave de partición no está definida en entornos sin particiones, como los controles webview de Office en Windows. Donde se define, la clave de partición es un hash de los dos dominios siguientes.
- El dominio en el que se encuentra la ventana superior del explorador, como
excel.cloud.microsoften el caso de Excel en la Web. - El dominio del complemento, como
myAddin.contoso.com.
Por lo tanto, cada una de las siguientes combinaciones crea una partición diferente:
excel.cloud.microsoft+myAddin.contoso.comword.cloud.microsoft+myAddin.contoso.comword.cloud.microsoft+myOtherAddin.contoso.com
En el ejemplo siguiente se muestra cómo utilizar la clave de partición con localStorage.
// 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 directivas de explorador Microsoft Edge). De forma similar a la partición basada en claves de Office, los datos almacenados por las API de almacenamiento, como el almacenamiento local, solo están disponibles en contextos con el mismo origen y el mismo sitio de nivel superior.
Configuración específica de la aplicación y persistencia
Excel, Word y Outlook proporcionan API específicas de la aplicación para guardar la configuración y otros datos. Use estas API en lugar de las API comunes que se mencionan más adelante en este artículo , de modo 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 para Word también proporcionan acceso a la configuración personalizada. La configuración es exclusiva de un único emparejamiento de archivos y complementos de Excel. Para obtener más información, vea Excel.SettingCollection y Word. SettingCollection.
El siguiente ejemplo muestra cómo crear y obtener acceso 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 Open XML .xlsx y .docx permiten al complemento incrustar datos XML personalizados en el libro de Excel o en Word documento. Estos datos se conservan con el archivo, independientemente del complemento.
A Word. Document y Excel.Workbook contienen un CustomXmlPartCollection, que 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 incrustar 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);
});
Nota:
CustomXMLPart.namespaceUri solo se rellena si el elemento XML personalizado en el nivel superior contiene el atributo xmlns.
Propiedades personalizadas en Excel y Word
Excel.DocumentProperties.custom y Word. Las propiedades 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 "Hola" y 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"
});
Sugerencia
En Excel, las propiedades personalizadas también se pueden establecer en el nivel de hoja de cálculo con la propiedad Worksheet.customProperties . Estas propiedades son similares a las personalizadas de nivel de documento, excepto que la misma clave se puede repetir en diferentes hojas de cálculo.
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 comunes de API
Las API comunes proporcionan objetos para guardar el estado del complemento entre sesiones. Los valores de configuración guardados están asociados al identificador del complemento que los creó. Internamente, los Settingsobjetos , CustomPropertiesy RoamingSettings almacenan datos como un objeto de notación de objetos JavaScript (JSON) serializado que contiene pares nombre-valor. El nombre (clave) de cada valor debe ser un string. El valor almacenado puede ser un JavaScript string, number, dateo object, pero no una función.
Este ejemplo de la estructura de bolsa de propiedades contiene tres valores de cadena definidos denominados firstName, location, y defaultView.
{
"firstName":"Erik",
"location":"98052",
"defaultView":"basic"
}
Una vez guardada la bolsa de propiedades de configuración durante una sesión de complemento anterior, el complemento puede cargar la configuración cuando se inicializa el complemento o en cualquier momento posterior durante la sesión actual del complemento. Durante la sesión, el complemento administra la configuración completamente en memoria mediante el get, sety remove los métodos del objeto que corresponde al tipo de configuración que está creando (Settings, CustomProperties o RoamingSettings).
Importante
Para conservar en la ubicación de almacenamiento las adiciones, actualizaciones o eliminaciones realizadas durante la sesión actual del complemento, llame saveAsync al método del objeto correspondiente que se usa para trabajar con ese tipo de configuración. El get, sety remove los métodos solo funcionan en la copia en memoria del saco de propiedades de configuración. Si el complemento se cierra sin llamar saveAsynca , los cambios realizados en la configuración durante esa sesión se perderán.
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 el estado o la configuración personalizada de un complemento de panel de tareas o contenido para Word, Excel o PowerPoint, use el objeto Settings y sus métodos. El contenedor de propiedades que cree mediante los métodos del Settings objeto solo estará disponible para la instancia del complemento de contenido o del panel de tareas que lo creó, y solo para el documento en el que lo guarde.
El Settings objeto se carga automáticamente como parte del objeto Documento 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 tener acceso al Settings objeto mediante la propiedad settings del Document objeto. Durante la duración de la sesión, use los métodos , Settings.set, y Settings.remove para leer, escribir o quitar la Settings.getconfiguración persistente y el estado de complemento de la copia en memoria del contenedor de propiedades.
Dado que los métodos Establecer y Quitar solo funcionan con la copia en memoria de la bolsa de propiedades de configuración, para volver a guardar la configuración nueva o modificada en el documento al que está asociado el complemento, debe llamar al método Settings.saveAsync .
Crear o actualizar 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');
La configuración con el nombre especificado se crea si no existe o su valor se actualiza si existe. Use el Settings.saveAsync método para conservar la configuración nueva o actualizada del 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 de la configuración que distingue mayúsculas de minúsculas.
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 guardado 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 de la configuración que distingue mayúsculas de minúsculas.
Office.context.document.settings.remove('themeColor');
No ocurre nada si la configuración no existe. Use el método para conservar la Settings.saveAsync eliminación de la configuración del documento.
Guardar la configuración
Para guardar las adiciones, cambios o eliminaciones que el complemento realice en la copia en memoria de la bolsa de propiedades de configuración durante la sesión actual, llame al método Settings.saveAsync para almacenarlas 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 solo 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 cuando se ejecuta el parámetro de devolución de llamada 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 siguiente, la función comprueba la AsyncResult.status propiedad para ver si la operación de guardado se ha realizado correctamente o no y, a continuación, muestra el resultado en la página del complemento.
Cómo guardar XML personalizado en el documento
Use un elemento XML personalizado para almacenar información que tenga un carácter estructurado o cuando necesite que los datos sean accesibles entre instancias del complemento. Otros complementos también pueden acceder a los datos almacenados de esta manera. Puede conservar el marcado XML personalizado en un complemento del 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 utilizar 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. La cadena XML debe incluir un xmlns atributo.
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, utilice el método getByIdAsync . El identificador es un GUID que se genera al crear la parte XML, por lo que no conoce el identificador al codificar. Por ese motivo, almacene el identificador del elemento XML como una configuración y asígnele una clave fácil de recordar al crear un elemento XML. 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);
}
);
}
);
}