Manter o estado de suplemento e as configurações

  • Artigo

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

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

Armazenamento do navegador

Persista dados em instâncias de suplemento com ferramentas do controle subjacente do navegador, como cookies de navegador ou armazenamento web HTML5 (localStorage ou sessionStorage).

Alguns navegadores ou as configurações do navegador do usuário podem bloquear técnicas de armazenamento baseadas no navegador. Você deve testar a disponibilidade conforme documentado em Usar a API de Armazenamento Da Web.

Particionamento de armazenamento

Como prática recomendada, todos os dados privados devem ser armazenados em particionados localStorage. Office.context.partitionKey fornece uma chave para uso com armazenamento local. Isso garante que os dados armazenados no armazenamento local só estão disponíveis no mesmo contexto. O exemplo a seguir mostra como usar a chave de partição com localStorage. Observe que a chave de partição é indefinida em ambientes sem partição, como os controles do navegador para aplicativos 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 da versão 115 de navegadores baseados em Chromium, como Chrome e Edge, a partição de armazenamento está habilitada para impedir o rastreamento entre sites de canal lateral específico (consulte também políticas de navegador do Microsoft Edge). Semelhante à partição baseada em chave do Office, os dados armazenados por APIs de armazenamento, como o armazenamento local, só estão disponíveis para contextos com a mesma origem e o mesmo site de nível superior.

Dica

Para contornar isso, no navegador, vá para chrome://flags ou edge://flags e defina o sinalizador Experimental de partição de armazenamento de terceiros (#third-armazenamento-particionamento) como Desabilitado.

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

Excel, Word e Outlook fornecem APIs específicas do aplicativo para salvar configurações e outros dados. Use-os 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 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 em 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 Word

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

Um 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 peças 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 em 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);
});

Observação

CustomXMLPart.namespaceUri só será preenchido se o elemento XML personalizado de nível superior contiver o atributo xmlns.

Propriedades personalizadas no Excel e Word

O Excel.DocumentProperties.custom e Word. As propriedades DocumentProperties.customProperties representam coleções de pares de valor-chave para propriedades definidas pelo usuário. O exemplo do Excel a seguir mostra como criar uma propriedade personalizada chamada Introdução com o valor "Olá" e 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"
});

Dica

No Excel, as propriedades personalizadas também podem ser definidas no nível da planilha com a propriedade Worksheet.customProperties . Elas são semelhantes às propriedades personalizadas no nível do documento, exceto que a mesma chave pode ser repetida em planilhas diferentes.

Como salvar configurações em um suplemento do Outlook

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

Configurações de API comuns e persistência

As APIs comuns fornecem objetos para salvar o estado de suplemento entre sessões. Os valores de configurações salvas estão associados à Id do suplemento que os criou. Internamente, os dados acessados com os Settingsobjetos , CustomPropertiesou são RoamingSettings armazenados como um objeto JSON (Notação de Objeto JavaScript) serializado que contém pares de nome/valor. O nome (chave) para cada valor deve ser um string, e o valor armazenado pode ser um JavaScript string, number, dateou , ou object, mas não uma função.

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

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

Depois que o conjunto de propriedades de configurações é salvo durante a sessão anterior do suplemento, ele pode ser carregado quando o suplemento é inicializado ou a qualquer momento depois disso durante a sessão atual do suplemento. Durante a sessão, as configurações são gerenciadas inteiramente na memória usando os getmétodos , sete remove do objeto que correspondem ao tipo de configurações que você está criando (Configurações, CustomProperties ou RoamingSettings).

Importante

Para persistir quaisquer adições, atualizações ou exclusões feitas durante a sessão atual do suplemento ao local de armazenamento, você deve chamar o saveAsync método do objeto correspondente usado para trabalhar com esse tipo de configurações. Os getmétodos , sete remove operam apenas na cópia na memória do saco de propriedades de configurações. Se o suplemento estiver fechado sem chamar saveAsync, quaisquer alterações feitas nas configurações durante essa sessão serão perdidas.

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

Para persistir 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 saco de propriedades criado com os métodos do Settings objeto está disponível apenas para a instância do conteúdo ou suplemento do painel de tarefas que o criou e somente do documento no qual ele é salvo.

O Settings objeto é carregado automaticamente como parte do objeto Document e está disponível quando o painel de tarefas ou o suplemento de conteúdo é ativado. Depois que o Document objeto for instanciado, você poderá acessar o Settings objeto com a propriedade configurações do Document objeto. Durante o tempo de vida da sessão, você pode usar os Settings.getmétodos , Settings.sete Settings.remove para ler, gravar ou remover as configurações persistentes e o estado de suplemento da cópia na memória do saco de propriedades.

Como os métodos set e remove operam apenas na cópia na memória do saco de propriedades de configurações, para salvar configurações novas ou alteradas de volta para o 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 definido é o nome confidencial de caso (Id) 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 é criada se ainda não existir, ou seu valor é atualizado se já existir. Use o Settings.saveAsync método para persistir 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 get método é o nome sensível a casos da configuração.

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 de 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 remove método é o nome sensível a casos da configuração.

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

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

Salvar suas configurações

Para salvar adições, alterações ou exclusões que o suplemento fez na cópia na memória do conjunto de propriedades de configurações durante a sessão atual, você deve chamar o método Settings.saveAsync para armazená-lo 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 saveAsync método à medida que o parâmetro de retorno de chamada é executado 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 exibe o resultado na página do suplemento.

Como salvar XML personalizado no documento

Uma parte XML personalizada é uma opção de armazenamento disponível para quando você deseja armazenar informações que têm um caractere estruturado ou precisam que os dados sejam acessíveis entre instâncias do seu suplemento. Observe que os dados armazenados dessa forma também podem ser acessados por outros suplementos. Você pode persistir a marcação XML personalizada em um suplemento de painel de tarefas para Word (e para Excel e Word usando a API específica do aplicativo, conforme mencionado no parágrafo anterior). Em 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. Observe que deverá haver um atributo xmlns na cadeia de caracteres de 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 uma parte XML personalizada, use o método getByIdAsync , mas a ID é um GUID gerado quando a parte XML é criada, portanto, você não pode saber ao codificar qual é a ID. Por esse motivo, é uma boa prática ao criar uma parte XML para armazenar imediatamente a ID da parte XML como uma configuração e dar-lhe uma chave memorável. 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