Сохранение состояния и параметров надстройки

Надстройки Office — это, по сути, веб-приложения, работающие в среде без отслеживания состояния в iframe браузера или элементе управления webview. (Для краткости далее в этой статье используется "элемент управления браузером" для обозначения "элемент управления браузером или веб-представлением".) При использовании надстройке может потребоваться сохранить данные, чтобы обеспечить непрерывность определенных операций или функций в сеансах. Например, у надстройки есть настраиваемые параметры или иные значения, которые должны быть сохранены и перезагружены при следующей инициализации, такие как выбранное пользователем представление или расположение по умолчанию. Для этого воспользуйтесь

• Используйте методы, предоставляемые базовым элементом управления браузера.
• Используйте api JavaScript для Приложений Office для Excel, Word и Outlook, которые хранят данные.

Если необходимо сохранять состояние в документах, например отслеживать предпочтения пользователей в открытых документах, необходимо использовать другой подход. Например, вы можете использовать единый вход для получения удостоверения пользователя, а затем сохранить идентификатор пользователя и его параметры в оперативной базе данных.

Хранилище браузера

Сохраняйте данные между экземплярами надстроек с помощью средств из базового элемента управления браузера, таких как файлы cookie браузера или веб-хранилище HTML5 (localStorage или sessionStorage).

Некоторые браузеры или параметры браузера пользователя могут блокировать методы хранения на основе браузера. Необходимо протестировать доступность, как описано в статье Использование API веб-хранилища.

Секционирование хранилища

Как правило, все личные данные должны храниться в секционированных localStorage. Office.context.partitionKey предоставляет ключ для использования с локальным хранилищем. Это гарантирует, что данные, хранящиеся в локальном хранилище, будут доступны только в том же контексте. В следующем примере показано, как использовать ключ секции с localStorage. Обратите внимание, что ключ секции не определен в средах без секционирования, таких как элементы управления браузера для приложений 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);
  }
}

Начиная с версии 115 для браузеров на основе Chromium, таких как Chrome и Edge, секционирование хранилища включено, чтобы предотвратить отслеживание между сайтами по боковому каналу (см. также политики браузера Microsoft Edge). Как и в случае с секционированием на основе ключей Office, данные, хранящиеся API хранилища, например локальным хранилищем, доступны только для контекстов с тем же источником и тем же сайтом верхнего уровня.

Параметры приложения и сохраняемость

Excel, Word и Outlook предоставляют API-интерфейсы приложений для сохранения параметров и других данных. Используйте их вместо общих API, упомянутых далее в этой статье , чтобы надстройка придерживалась согласованных шаблонов и была оптимизирована для целевого приложения.

Параметры в Excel и Word

Api JavaScript для приложений для Excel и Word также предоставляют доступ к пользовательским параметрам. Параметры уникальны для одного файла Excel и связывания надстроек. Дополнительные сведения см. в разделах Excel.SettingCollection и Word.SettingCollection.

В следующем примере показано, как создать параметр и получить доступ к параметру в Excel. Этот процесс функционально эквивалентен в Word, который использует Document.settings вместо 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);
});

Пользовательские XML-данные в Excel и Word

Форматы файлов Open XML.xlsx и .docx позволяют надстройке внедрять пользовательские XML-данные в книгу Excel или документ Word. Эти данные сохраняются вместе с файлом независимо от надстройки.

Книги Word.Document и Excel.Work содержат CustomXmlPartCollection, который является списком CustomXmlParts. Они предоставляют доступ к строкам XML и соответствующему уникальному идентификатору. Сохраняя эти идентификаторы как параметры, надстройка может сохранять ключи к частям XML между сеансами.

В следующих примерах показано, как использовать пользовательские XML-части с книгой Excel. Первый блок кода демонстрирует внедрение XML-данных. Выполняется сохранение списка проверяющих, а затем используются параметры книги, чтобы сохранить параметр id XML для будущих извлечений. Во втором блоке показано, как получить доступ к этим XML-данным позднее. Параметр "ContosoReviewXmlPartId" загружается и передается объекту customXmlParts книги. Данные XML затем печатаются в консоль. Процесс функционально эквивалентен в Word, где вместо Document.customXmlParts используется Document.customXmlPartsWorkbook.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);
});

Примечание.

CustomXMLPart.namespaceUri заполняется только в том случае, если настраиваемый XML-элемент верхнего уровня содержит атрибут xmlns.

Пользовательские свойства в Excel и Word

Свойства Excel.DocumentProperties.custom и Word.DocumentProperties.customProperties представляют коллекции пар "ключ-значение" для определяемых пользователем свойств. В следующем примере Excel показано, как создать пользовательское свойство с именем Introduction со значением "Hello", а затем получить его.

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

Совет

В Excel настраиваемые свойства также можно задать на уровне листа с помощью свойства Worksheet.customProperties . Они похожи на пользовательские свойства уровня документа, за исключением того, что один и тот же ключ может повторяться на разных листах.

Сохранение параметров в надстройке Outlook

Сведения о сохранении параметров в надстройке Outlook см. в разделах Получение и настройка метаданных надстройки для надстройки Outlook и Получение и настройка заголовков в Интернете для сообщения в надстройке Outlook.

Общие параметры API и сохраняемость

Общие API предоставляют объекты для сохранения состояния надстройки в сеансах. Сохраненные значения параметров связаны с идентификатором надстройки, которая их создала. Внутренние данные, к которым осуществляется доступ с помощью Settingsобъектов , CustomPropertiesили RoamingSettings , хранятся в виде сериализованного объекта нотации объектов JavaScript (JSON), содержащего пары "имя-значение". Имя (ключ) для каждого значения должно быть string, а хранимое значение может быть JavaScript string, number, date, или object, но не функцией.

Этот пример структуры контейнера свойств содержит три определенных строковых значения с именами firstName, locationи defaultView.

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

После сохранения контейнера свойств параметров во время предыдущего сеанса надстройки он может быть загружен при инициализации надстройки или в любое время после этого в течение текущего сеанса надстройки. Во время сеанса управление параметрами осуществляется полностью в памяти с помощью getметодов , setи remove объекта , соответствующего типу создаваемых параметров (Settings, CustomProperties или RoamingSettings).

Важно!

Чтобы сохранить все добавления, обновления или удаления, сделанные во время текущего сеанса надстройки, в хранилище, необходимо вызвать saveAsync метод соответствующего объекта, используемого для работы с параметрами такого типа. Методы get, setи remove работают только с копией в памяти контейнера свойств settings. Если надстройка закрыта без вызова saveAsync, все изменения, внесенные в параметры во время этого сеанса, будут потеряны.

Сохранение состояния надстройки и параметров документа для надстроек области задач и контентных надстроек

Чтобы сохранить состояние или пользовательские параметры контентной надстройки или надстройки области задач для Word, Excel или PowerPoint, используйте объект Settings и его методы. Контейнер свойств, созданный с помощью методов Settings объекта, доступен только экземпляру создавшего его содержимого или надстройки области задач и только из документа, в котором он сохранен.

Объект Settings автоматически загружается как часть объекта Document и становится доступным при активации области задач или контентной надстройки. После создания экземпляра Document объекта можно получить доступ к объекту Settings с помощью свойства Documentsettings объекта . Во время существования сеанса можно использовать Settings.getметоды , Settings.setи Settings.remove для чтения, записи или удаления сохраненных параметров и состояния надстройки из копии контейнера свойств в памяти.

Так как методы set и remove работают только с копией в памяти контейнера свойств settings, чтобы сохранить новые или измененные параметры обратно в документ, с которым связана надстройка, необходимо вызвать метод Settings.saveAsync .

Создание или обновление значения параметра

Следующий пример кода демонстрирует использование метода Settings.set для создания параметра с именем 'themeColor', имеющий значение 'green'. Первым параметром метода set является имя с учетом регистра (Id) параметра, который необходимо задать или создать. Второй параметр — это value параметра.

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

Создается параметр с указанным именем, если таковой еще не существует или обновляется значение, если параметр существует. Используйте метод для Settings.saveAsync сохранения новых или обновленных параметров в документе.

Получение значения параметра

В следующем примере показано, как использовать метод Settings.get для получения значения параметра "themeColor". Единственным параметром get метода является имя параметра с учетом регистра.

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

Метод get возвращает значение, которое было ранее сохранено для переданного имени параметра. Если параметр не существует, метод возвращает null.

Удаление параметра

В следующем примере показано, как использовать метод Settings.remove для удаления параметра с именем "themeColor". Единственным параметром remove метода является имя параметра с учетом регистра.

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

Ничего не произойдет, если параметр не существует. Используйте метод для Settings.saveAsync сохранения удаления параметра из документа.

Сохранение параметров

Чтобы сохранить любые добавления, изменения или удаления, внесенные надстройкой в копию контейнера свойств параметров, хранящуюся в памяти, во время текущего сеанса надстройки, необходимо вызвать метод Settings.saveAsync для их сохранения в документе. Единственным параметром saveAsync метода является обратный вызов, который является функцией обратного вызова с одним параметром.

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

Анонимная функция, передаваемая в saveAsync метод в качестве параметра обратного вызова , выполняется по завершении операции. Параметр asyncResult обратного вызова предоставляет доступ к объекту AsyncResult , который содержит состояние операции. В этом примере функция проверяет AsyncResult.status свойство, чтобы узнать, была ли операция сохранения успешной или неудачной, а затем отображает результат на странице надстройки.

Сохранение пользовательского кода XML в документе

Настраиваемая XML-часть — это доступный вариант хранения данных, имеющих структурированный характер или необходимый доступ к данным между экземплярами надстройки. Обратите внимание, что к данным, хранящимся таким образом, также можно получить доступ к другим надстройкам. Вы можете сохранить настраиваемую разметку XML в надстройке области задач для Word (а также для Excel и Word с помощью API для конкретного приложения, как упоминалось в предыдущем абзаце). В Word можно использовать объект CustomXmlPart и его методы. В приведенном ниже коде создается пользовательская часть XML, после чего в разделителях на странице отображается сначала ее ИД, а затем ее содержимое. Обратите внимание, что в строке XML должен быть указан атрибут xmlns.

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

Чтобы получить пользовательскую XML-часть, используйте метод getByIdAsync , но идентификатор является ИДЕНТИФИКАТОРом GUID, который создается при создании XML-части, поэтому вы не можете знать, что это за идентификатор. По этой причине при создании XML-части рекомендуется немедленно сохранить идентификатор XML-части в качестве параметра и присвоить ей запоминающийся ключ. Ниже показано, как это сделать.

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

В приведенном ниже коде показано, как получить часть XML, сначала получив ее ИД из параметра.

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

См. также

• Общие сведения об API JavaScript для Office
• Надстройки Outlook
• Просмотр и изменение метаданных для надстройки Outlook
• Получение и настройка заголовков в Интернете для сообщения в надстройке Outlook
• Excel-Add-in-JavaScript-PersistCustomSettings