Persistir estado e configurações do suplemento

Os suplementos do Office são essencialmente aplicativos Web executados no ambiente sem estado de um iframe do navegador ou de um controle de modo de exibição da Web. Para resumir, este artigo usa "controle do navegador" para significar "controle do navegador ou do modo de exibição da Web". Quando em uso, o suplemento pode precisar persistir dados para manter a continuidade de determinadas operações ou recursos entre as sessões. Por exemplo, seu suplemento pode ter configurações personalizadas ou outros valores que ele precisa salvar e recarregar na próxima vez que for inicializado, como a exibição preferida de um usuário ou o local padrão. Para persistir dados, você pode:

• Use técnicas fornecidas pelo controle do navegador subjacente.
• Use as APIs JavaScript do Office específicas do aplicativo para Excel, Word e Outlook que armazenam dados.

Se você precisar manter o estado entre documentos, como acompanhar as preferências do usuário em todos os documentos que eles abrirem, use uma abordagem diferente. Por exemplo, você pode usar o SSO para obter a identidade do usuário e, em seguida, salvar a ID do usuário e suas configurações em um banco de dados online.

Armazenamento do navegador

Persista os dados nas instâncias do suplemento usando ferramentas do controle do navegador subjacente, como cookies do navegador ou armazenamento na Web HTML5 (localStorage ou sessionStorage).

Alguns navegadores ou as configurações do navegador do usuário podem bloquear técnicas de armazenamento baseadas em navegador. Teste a disponibilidade conforme documentado em Usando a API de Armazenamento na Web.

Particionamento de armazenamento

Armazene todos os dados privados no arquivo localStorage. Use Office.context.partitionKey como uma chave para armazenamento local. Essa abordagem garante que os dados armazenados no armazenamento local estejam disponíveis apenas no mesmo contexto.

O exemplo a seguir mostra como usar a chave de partição com localStorageo .

// 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 da versão 115 dos navegadores baseados no Chromium, como Chrome e Edge, o particionamento de armazenamento é habilitado para impedir o rastreamento entre sites específico do canal lateral (consulte também as políticas do navegador Microsoft Edge). De forma semelhante ao particionamento baseado em chave do Office, os dados armazenados por APIs de armazenamento, como o armazenamento local, só estão disponíveis em contextos com a mesma origem e o mesmo site de nível superior.

Configurações e persistência específicas do aplicativo

O Excel, o Word e o Outlook fornecem APIs específicas do aplicativo para salvar configurações e outros dados. Use essas APIs em vez das APIs comuns mencionadas posteriormente neste artigo para que seu suplemento siga padrões consistentes e seja otimizado para o aplicativo de destino.

Configurações no Excel e no Word

As APIs JavaScript específicas do aplicativo para Excel e para Word também fornecem acesso às configurações personalizadas. As configurações são exclusivas para um único arquivo do Excel e emparelhamento de suplementos. Para obter mais informações, consulte Excel.SettingCollection e Word. SettingCollection.

O exemplo a seguir mostra como criar e acessar uma configuração no Excel. O processo é funcionalmente equivalente no Word, que usa Document.settings em vez 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);
});

Dados XML personalizados no Excel e no Word

Os formatos de arquivo Open XML.xlsxe .docx permitem que o suplemento insira dados XML personalizados na pasta de trabalho do Excel ou no documento Word. Esses dados persistem com o arquivo, independentemente do suplemento.

A Word. Documento e Excel.Workbook contêm um CustomXmlPartCollection, que é uma lista de CustomXmlParts. Eles oferecem acesso a cadeias de caracteres XML e a uma ID exclusiva correspondente. Armazenando essas IDs como configurações, seu suplemento pode manter as teclas para suas partes XML entre sessões.

Os exemplos a seguir mostram como usar partes XML personalizadas com uma pasta de trabalho do Excel. O primeiro bloco de código demonstra como inserir dados XML. Ele armazena uma lista de revisores e usa as configurações da pasta de trabalho para salvar a id do XML para recuperação futura. O segundo bloco mostra como acessar esse XML mais tarde. A configuração "ContosoReviewXmlPartId" é carregada e transmitida para customXmlParts da pasta de trabalho. Os dados XML são então impressos no console. O processo é funcionalmente equivalente no Word, que usa Document.customXmlParts em vez 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);
});

Propriedades personalizadas no Excel e no Word

O Excel.DocumentProperties.custom e o Word. As propriedades DocumentProperties.customProperties representam coleções de pares de chave-valor para propriedades definidas pelo usuário. O exemplo do Excel a seguir mostra como criar uma propriedade personalizada chamada Introduction com o valor "Hello" e, em seguida, recuperá-la.

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

Como salvar configurações em um suplemento do Outlook

Para obter informações sobre como salvar configurações em um suplemento do Outlook, consulte Obter e definir metadados de suplemento para um suplemento do Outlook e Obter e definir cabeçalhos da Internet em uma mensagem em um suplemento do Outlook.

Configurações e persistência comuns de API

As APIs comuns fornecem objetos para salvar o estado do suplemento entre sessões. Os valores de configurações salvos são associados à ID do suplemento que os criou. Internamente, o , CustomPropertiese RoamingSettings os Settingsobjetos armazenam dados como um objeto JavaScript Object Notation (JSON) serializado que contém pares nome/valor. O nome (chave) para cada valor deve ser um string. O valor armazenado pode ser um JavaScript string, number, date, ou object, mas não uma função.

Este exemplo da estrutura do recipiente de propriedades contém três valores de cadeia de caracteres definidos chamados firstName, location, e defaultView.

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

Depois que o recipiente de propriedades de configurações é salvo durante uma sessão anterior do suplemento, o suplemento pode carregar as configurações quando o suplemento é inicializado ou a qualquer momento depois disso durante a sessão atual do suplemento. Durante a sessão, o suplemento gerencia as configurações inteiramente na memória usando o get, sete remove métodos do objeto que corresponde ao tipo de configuração que você está criando (Settings, CustomProperties ou RoamingSettings).

Como salvar o estado e as configurações do suplemento por documento para suplementos de conteúdo e de painel de tarefas

Para manter o estado ou as configurações personalizadas de um suplemento de conteúdo ou painel de tarefas para Word, Excel ou PowerPoint, use o objeto Configurações e seus métodos. O recipiente de propriedades que você cria usando os métodos do Settings objeto está disponível somente para a instância do conteúdo ou do suplemento do painel de tarefas que o criou e somente a partir do documento no qual você o salva.

O Settings objeto é carregado automaticamente como parte do objeto Documento e fica disponível quando o painel de tarefas ou o suplemento de conteúdo é ativado. Depois de instanciar o Document objeto, você pode acessá-lo Settingsusando a propriedade settings do Document objeto. Durante o tempo de vida da sessão, use os Settings.getmétodos , Settings.sete Settings.remove para ler, gravar ou remover configurações persistentes e o estado do suplemento da cópia na memória do recipiente de propriedades.

Como os métodos set e remove operam apenas na cópia na memória do recipiente de propriedades settings, para salvar configurações novas ou alteradas de volta no documento ao qual o suplemento está associado, você deve chamar o método Settings.saveAsync .

Criar ou atualizar um valor de configuração

O exemplo de código a seguir mostra como usar o método Settings.set para criar uma configuração chamada 'themeColor' com um valor 'green'. O primeiro parâmetro do método set é o nome (Id) que diferencia maiúsculas de minúsculas da configuração a ser definida ou criada. O segundo parâmetro é o value da configuração.

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

A configuração com o nome especificado será criada se ainda não existir ou seu valor será atualizado se existir. Use o Settings.saveAsync método para manter as configurações novas ou atualizadas no documento.

Obter o valor de uma configuração

O exemplo a seguir mostra como usar o método Settings.get para obter o valor de uma configuração chamada "themeColor". O único parâmetro do método é o getnome da configuração que diferencia maiú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;
}

O get método retorna o valor que foi salvo anteriormente para o nome da configuração que foi passado. Se a configuração não existir, o método retornará null.

Remover uma configuração

O exemplo a seguir mostra como usar o método Settings.remove para remover uma configuração com o nome "themeColor". O único parâmetro do método é o removenome da configuração que diferencia maiúsculas de minúsculas.

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

Nada acontece se a configuração não existir. Use o Settings.saveAsync método para manter a remoção da configuração do documento.

Salve suas configurações

Para salvar quaisquer adições, alterações ou exclusões que seu suplemento fez na cópia na memória do recipiente de propriedades de configurações durante a sessão atual, chame o método Settings.saveAsync para armazená-las no documento. O único parâmetro do método é o saveAsyncretorno de chamada, que é uma função de retorno de chamada com um ú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;
}

A função anônima passada para o método como o parâmetro de retorno de chamada é executada saveAsync quando a operação é concluída. O parâmetro asyncResult do retorno de chamada fornece acesso a um AsyncResult objeto que contém o status da operação. No exemplo, a função verifica a AsyncResult.status propriedade para ver se a operação de salvamento foi bem-sucedida ou falhou e, em seguida, exibe o resultado na página do suplemento.

Como salvar XML personalizado no documento

Use uma parte XML personalizada para armazenar informações que tenham um caractere estruturado ou quando precisar que os dados sejam acessíveis entre instâncias do suplemento. Outros suplementos também podem acessar dados armazenados dessa maneira. Você pode persistir a marcação XML personalizada em um suplemento do painel de tarefas para o Word (e para o Excel e o Word usando a API específica do aplicativo, conforme mencionado no parágrafo anterior). No Word, você pode usar o objeto CustomXmlPart e seus métodos. O código a seguir cria um componente XML personalizado e exibe sua ID e seu conteúdo no divs na página. A cadeia de caracteres XML deve incluir um 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 uma parte XML personalizada, use o método getByIdAsync . A ID é um GUID gerado quando você cria a parte XML, portanto, você não sabe a ID ao codificar. Por esse motivo, armazene a ID da parte XML como uma configuração e dê a ela uma chave memorável ao criar uma parte XML. O método a seguir mostra como fazer isso.

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

O código a seguir mostra como recuperar parte do XML obtendo primeiro a sua ID em uma configuração.

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

Confira também

• Entendendo a API de JavaScript do Office
• Suplementos do Outlook
• Obter e definir metadados de suplemento para um suplemento do Outlook
• Obter e definir cabeçalhos da Internet em uma mensagem em um suplemento do Outlook
• Salvar configurações personalizadas no seu Suplemento do Office