Office.RoamingSettings interface

Pacote:

outlook

As configurações criadas com os métodos do objeto RoamingSettings são salvas de acordo de acordo com o suplemento e o usuário. Ou seja, eles estão disponíveis apenas para o suplemento que os criou e somente da caixa de correio do usuário na qual eles são salvos.

Embora a API de suplemento do Outlook limite o acesso a essas configurações apenas para o suplemento que as criou, essas configurações não devem ser consideradas armazenamento seguro. Elas podem ser acessadas pelos Serviços Web do Exchange ou por MAPI estendido. Eles não devem ser usados para armazenar informações confidenciais, como credenciais de usuário ou tokens de segurança.

O nome de uma configuração é uma String, enquanto o valor pode ser uma String, um Number, um Boolean, nulo, um Object ou uma Array.

O objeto RoamingSettings pode ser acessado por meio da propriedade roamingSettings no namespace Office.context.

Para saber mais sobre RoamingSettings, confira Obter e definir metadados de suplemento para um suplemento do Outlook.

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Importante:

• O RoamingSettings objeto é inicializado do armazenamento persistente somente quando o suplemento é carregado pela primeira vez. Para painéis de tarefas, isso significa que ele só é inicializado quando o painel de tarefas é aberto pela primeira vez. Se o painel de tarefas navegar até outra página ou recarregar a página atual, o objeto na memória será redefinido para seus valores iniciais, mesmo que o suplemento tenha persistente alterações. As alterações persistentes não estarão disponíveis até que o painel de tarefas (ou item no caso de suplementos sem interface do usuário) seja fechado e reaberto.

• Quando definidas e salvas pelo Outlook no Windows ou no Mac, essas configurações são refletidas em Outlook na Web somente após uma atualização do navegador.

Nível mínimo de permissão: restrito

Modo outlook aplicável: compor ou ler

Métodos

get(name)	Recupera a configuração especificada.
remove(name)	Remove a configuração especificada.
saveAsync(callback)	Salva as configurações. Todas as configurações salvas anteriormente por um suplemento são carregadas quando elas são inicializadas, portanto, durante o tempo de vida da sessão, você pode apenas usar o conjunto e obter métodos para trabalhar com a cópia na memória do saco de propriedades de configurações. Quando você quiser persistir as configurações para que elas estejam disponíveis na próxima vez que o suplemento for usado, use o saveAsync método.
set(name, value)	Define ou cria a configuração especificada. O set método cria uma nova configuração do nome especificado se ele ainda não existir ou definir uma configuração existente do nome especificado. O valor é armazenado no documento como a representação JSON serializada do seu tipo de dados. Um máximo de 32KB está disponível para as configurações de cada suplemento. Um erro com o código 9057 é gerado quando esse limite de tamanho é excedido. Quaisquer alterações feitas nas configurações usando o set método não serão salvas no servidor até que o saveAsync método seja chamado.

Detalhes do método

get(name)

Recupera a configuração especificada.

get(name: string): any;

Parâmetros

name

string

O nome da configuração a ser recuperado diferencia maiúsculas de minúsculas.

Retornos

any

Tipo: Cadeia de caracteres | Número | Booliano | Objeto | Matriz

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Nível mínimo de permissão: restrito

Modo outlook aplicável: compor ou ler

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = $("#settingName").val();
const settingValue = Office.context.roamingSettings.get(settingName);
$("#settingValue").val(settingValue);
console.log(`The value of setting "${settingName}" is "${settingValue}".`);

remove(name)

Remove a configuração especificada.

remove(name: string): void;

Parâmetros

name

string

O nome da configuração a ser removida diferencia maiúsculas de minúsculas.

Retornos

void

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Nível mínimo de permissão: restrito

Modo outlook aplicável: compor ou ler

saveAsync(callback)

Salva as configurações.

Todas as configurações salvas anteriormente por um suplemento são carregadas quando elas são inicializadas, portanto, durante o tempo de vida da sessão, você pode apenas usar o conjunto e obter métodos para trabalhar com a cópia na memória do saco de propriedades de configurações. Quando você quiser persistir as configurações para que elas estejam disponíveis na próxima vez que o suplemento for usado, use o saveAsync método.

saveAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parâmetros

callback

(asyncResult: Office.AsyncResult<void>) => void

Opcional. Quando o método é concluído, a função passada no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult.

Retornos

void

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Nível mínimo de permissão: restrito

Modo outlook aplicável: compor ou ler

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

// Save settings in the mailbox to make it available in future sessions.
Office.context.roamingSettings.saveAsync(function(result) {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
  } else {
    console.log(`Settings saved with status: ${result.status}`);
  }
});

set(name, value)

Define ou cria a configuração especificada.

O set método cria uma nova configuração do nome especificado se ele ainda não existir ou definir uma configuração existente do nome especificado. O valor é armazenado no documento como a representação JSON serializada do seu tipo de dados.

Um máximo de 32KB está disponível para as configurações de cada suplemento. Um erro com o código 9057 é gerado quando esse limite de tamanho é excedido.

Quaisquer alterações feitas nas configurações usando o set método não serão salvas no servidor até que o saveAsync método seja chamado.

set(name: string, value: any): void;

Parâmetros

name

string

O nome da configuração a ser definido ou criado; diferencia maiúsculas de minúsculas.

value

any

Specifies the value to be stored.

Retornos

void

Comentários

[ Conjunto de API: Caixa de correio 1.1 ]

Nível mínimo de permissão: restrito

Modo outlook aplicável: compor ou ler

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = $("#settingName").val();
const settingValue = $("#settingValue").val();
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);