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. (Posteriormente, este artigo utiliza "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 em todas as 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:

• 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, terá de utilizar 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 em instâncias de suplementos com 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. Deve testar a disponibilidade conforme documentado em Utilizar a API de Armazenamento Web.

Criação de partições de armazenamento

Como melhor prática, todos os dados privados devem ser armazenados na partição localStorage. Office.context.partitionKey fornece uma chave para utilização com o armazenamento local. Isto 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. Tenha em atenção que a chave de partição não está definida em ambientes sem criação de partições, como os controlos do browser para aplicações do 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 dos browsers baseados no 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-as 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 no Word

Os formatos de ficheiro Open XML .xlsx e .docx permitem que o seu suplemento incorpore dados XML personalizados no livro do Excel ou no documento do Word. Estes dados persistem com o ficheiro, independentemente do suplemento.

Um Word.Document 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 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

As propriedades Excel.DocumentProperties.custom e Word.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 dados acedidos com os Settingsobjetos , CustomPropertiesou RoamingSettings são armazenados 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, e o valor armazenado pode ser um JavaScript string, number, date, ou 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 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 definições são geridas 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 o Word, Excel ou PowerPoint, utilize o objeto Definições e os respetivos métodos. O conjunto de propriedades criado 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 é guardado.

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 está 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, pode utilizar 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 configuração com o nome especificado é criada se ainda não existir, ou seu valor é atualizado se já 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 acontecerá 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 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 é 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 o estado 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

Uma peça XML personalizada é uma opção de armazenamento disponível para quando pretende armazenar informações que têm um caráter estruturado ou precisam que os dados sejam acessíveis em várias instâncias do seu suplemento. Tenha em atenção que os dados armazenados desta forma também podem ser acedidos por outros suplementos. Pode manter a marcação XML personalizada num suplemento do painel de tarefas para o Word (e para o Excel e Word com a 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. 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 obter uma peça XML personalizada, utilize o método getByIdAsync , mas o ID é um GUID que é gerado quando a peça XML é criada, pelo que não pode saber quando codifica o ID. Por esse motivo, é uma boa prática ao criar uma parte XML para armazenar imediatamente o ID da parte XML como uma definiçã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

• 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
• Excel-Add-in-JavaScript-PersistCustomSettings