Manter o estado e as definições do suplemento

Os Suplementos do Office são essencialmente aplicações Web em execução no ambiente sem estado de um iframe do browser ou de um controlo webview. Por questões de brevidade, este artigo utiliza o "controlo do browser" para significar "controlo de browser ou webview". Quando estiver a ser utilizado, o suplemento poderá ter de manter os dados para manter a continuidade de determinadas operações ou funcionalidades nas sessões. Por exemplo, o suplemento pode ter definições personalizadas ou outros valores que precisa de guardar e recarregar da próxima vez que for inicializado, como a vista preferida de um utilizador ou a localização predefinida. Para manter os dados, pode:

• Utilize técnicas fornecidas pelo controlo do browser subjacente.
• Utilize as APIs de JavaScript do Office específicas da aplicação para Excel, Word e Outlook que armazenam dados.

Se precisar de manter o estado em todos os documentos, como controlar as preferências dos utilizadores em todos os documentos abertos, utilize uma abordagem diferente. Por exemplo, pode utilizar o SSO para obter a identidade do utilizador e, em seguida, guardar o ID de utilizador e as respetivas definições numa base de dados online.

Armazenamento do browser

Mantenha os dados entre instâncias de suplementos através de ferramentas do controlo do browser subjacente, como cookies do browser ou armazenamento Web HTML5 (localStorage ou sessionStorage).

Alguns browsers ou as definições do browser do utilizador podem bloquear técnicas de armazenamento baseadas no browser. Teste a disponibilidade conforme documentado em Utilizar a API de Armazenamento Web.

Criação de partições de armazenamento

Armazene quaisquer dados privados na partição localStorage. Utilize Office.context.partitionKey como uma chave para o armazenamento local. Esta abordagem garante que os dados armazenados no armazenamento local só estão disponíveis no mesmo contexto.

O exemplo seguinte mostra como utilizar a chave de partição com 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 da versão 115 de browsers baseados em Chromium, como o Chrome e o Edge, a criação de partições de armazenamento está ativada para impedir o controlo de canais laterais específicos entre sites (consulte também políticas do browser Microsoft Edge). À semelhança da criação de partições baseada em chaves 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.

Definições e persistência específicas da aplicação

O Excel, o Word e o Outlook fornecem APIs específicas da aplicação para guardar definições e outros dados. Utilize estas APIs em vez das APIs Comuns mencionadas mais adiante neste artigo para que o suplemento siga padrões consistentes e esteja otimizado para a aplicação de destino.

Definições no Excel e Word

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

O exemplo seguinte mostra como criar e aceder a uma definição no Excel. O processo é funcionalmente equivalente no Word, que utiliza 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 ficheiro Open XML .xlsx e .docx permitem que o seu suplemento incorpore dados XML personalizados no livro do Excel ou Word documento. Estes dados persistem com o ficheiro, independentemente do suplemento.

Um Word. O Documento e o 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 seguintes mostram como utilizar peças XML personalizadas com um livro do Excel. O primeiro bloco de código demonstra como incorporar 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 utiliza 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 Word

O Excel.DocumentProperties.custom e Word. As propriedades DocumentProperties.customProperties representam coleções de pares chave-valor para propriedades definidas pelo utilizador. O exemplo seguinte do Excel mostra como criar uma propriedade personalizada denominada Introdução com o valor "Olá" e, em seguida, obtê-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 guardar definições num suplemento do Outlook

Para obter informações sobre como guardar definições num suplemento do Outlook, consulte Obter e definir metadados de suplementos para um suplemento do Outlook e Obter e definir cabeçalhos da Internet numa mensagem num suplemento do Outlook.

Definições e persistência comuns da API

As APIs Comuns fornecem objetos para guardar o estado do suplemento nas sessões. Os valores das definições guardadas estão associados ao ID do suplemento que os criou. Internamente, os Settingsobjetos , CustomPropertiese RoamingSettings armazenam dados como um objeto Serializado JavaScript Object Notation (JSON) que contém pares nome/valor. O nome (chave) para cada valor tem de ser um string. O valor armazenado pode ser um JavaScript string, number, , dateou object, mas não uma função.

Este exemplo da estrutura do pacote de propriedades contém três valores de cadeia definidos com o nome firstName, locatione defaultView.

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

Depois de o pacote de propriedades das definições ser guardado durante uma sessão de suplemento anterior, o suplemento pode carregar as definições quando o suplemento inicializar ou em qualquer ponto depois durante a sessão atual do suplemento. Durante a sessão, o suplemento gere as definições inteiramente na memória com os getmétodos , sete remove do objeto que corresponde ao tipo de definições que está a criar (Definições, PropriedadesPersonalizadas 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 definições personalizadas de um suplemento de conteúdo ou painel de tarefas para Word, Excel ou PowerPoint, utilize o objeto Definições e os respetivos métodos. O conjunto de propriedades que criar com os métodos do Settings objeto só está disponível para a instância do suplemento de conteúdo ou painel de tarefas que o criou e apenas a partir do documento no qual o guarda.

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, pode aceder ao Settings objeto com a propriedade settings do Document objeto. Durante a duração da sessão, utilize os Settings.getmétodos , Settings.sete Settings.remove para ler, escrever ou remover definições persistentes e o estado do suplemento da cópia dentro da memória do saco de propriedades.

Uma vez que os métodos definir e remover funcionam apenas na cópia dentro da memória do saco de propriedades das definições, para guardar as definições novas ou alteradas no documento ao qual o suplemento está associado, tem de chamar o método Settings.saveAsync .

Criar ou atualizar um valor de definiçã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 sensível às maiúsculas e minúsculas (ID) da definição a definir ou criar. O segundo parâmetro é o value da configuração.

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

A definição com o nome especificado é criada se ainda não existir ou se o respetivo valor for atualizado se existir. Utilize o Settings.saveAsync método para manter as definições novas ou atualizadas do documento.

Obter o valor de uma definiçã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 às maiúsculas e minúsculas da definiçã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 devolve o valor que foi guardado anteriormente para o nome da definição que foi transmitido. Se a configuração não existir, o método retornará null.

Remover uma definiçã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 às maiúsculas e minúsculas da definição.

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

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

Guardar as suas definições

Para guardar quaisquer adições, alterações ou eliminações do suplemento efetuado na cópia dentro da memória do conjunto de propriedades das definições durante a sessão atual, chame o método Settings.saveAsync para armazená-los no documento. O único parâmetro do método é a saveAsyncchamada de retorno, que é uma função de chamada de retorno 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 passou para o saveAsync método à medida que o parâmetro de chamada de retorno é executado quando a operação é concluída. O parâmetro asyncResult da chamada de retorno fornece acesso a um AsyncResult objeto que contém a status da operação. No exemplo, a função verifica a AsyncResult.status propriedade para ver se a operação de guardar foi bem-sucedida ou falhou e, em seguida, apresenta o resultado na página do suplemento.

Como salvar XML personalizado no documento

Utilize uma peça XML personalizada para armazenar informações que têm um caráter estruturado ou quando precisar que os dados sejam acessíveis em instâncias do seu suplemento. Outros suplementos também podem aceder aos dados armazenados desta forma. Pode manter a marcação XML personalizada num suplemento do painel de tarefas para Word (e para o Excel e Word através da API específica da aplicação, conforme mencionado no parágrafo anterior). No Word, pode utilizar o objeto CustomXmlPart e os respetivos 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 XML tem de 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 obter uma peça XML personalizada, utilize o método getByIdAsync . O ID é um GUID que é gerado quando cria a peça XML, pelo que não sabe o ID ao programar. Por esse motivo, armazene o ID da peça XML como uma definição e dê-lhe uma chave memorável ao criar uma peça 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 numa mensagem num suplemento do Outlook
• Guardar definições personalizadas no seu Suplemento do Office