Office.Settings interface

Pacote:

office

Representa configurações personalizadas para um suplemento de painel de tarefas ou conteúdo que são armazenadas no documento host como pares nome/valor.

Comentários

Aplicativos: Excel, PowerPoint, Word

As configurações criadas usando os métodos do objeto Configurações são salvas por suplemento e por documento. Ou seja, elas estão disponíveis somente para o suplemento que as criou e somente por meio do documento em que elas estão salvas.

O nome de uma configuração é uma cadeia de caracteres, enquanto o valor pode ser uma cadeia de caracteres, número, booliano, nulo, objeto ou matriz.

O objeto Configurações é carregado automaticamente como parte do objeto Document e está disponível chamando a propriedade configurações desse objeto quando o suplemento é ativado.

O desenvolvedor é responsável por chamar o método saveAsync após adicionar ou excluir configurações para salvar as configurações no documento.

Métodos

addHandlerAsync(eventType, handler, options, callback)	Adiciona um manipulador de eventos para o evento settingsChanged. Importante: o código do suplemento pode registrar um manipulador para o evento settingsChanged quando o suplemento estiver em execução com qualquer cliente do Excel, mas o evento será disparado somente quando o suplemento for carregado com uma planilha aberta no Excel na Web e mais de um usuário estiver editando a planilha (coautoria). Portanto, efetivamente, o evento settingsChanged só tem suporte em Excel na Web em cenários de coautoria.
addHandlerAsync(eventType, handler, callback)	Adiciona um manipulador de eventos para o evento settingsChanged. Importante: o código do suplemento pode registrar um manipulador para o evento settingsChanged quando o suplemento estiver em execução com qualquer cliente do Excel, mas o evento será disparado somente quando o suplemento for carregado com uma planilha aberta no Excel na Web e mais de um usuário estiver editando a planilha (coautoria). Portanto, efetivamente, o evento settingsChanged só tem suporte em Excel na Web em cenários de coautoria.
get(name)	Recupera a configuração especificada.
refreshAsync(callback)	Lê todas as configurações persistentes no documento e atualiza a cópia do suplemento de conteúdo ou painel de tarefas dessas configurações mantidas na memória.
remove(name)	Remove a configuração especificada. Importante: esteja ciente de que o método Settings.remove afeta apenas a cópia na memória do saco de propriedades de configurações. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.
removeHandlerAsync(eventType, options, callback)	Remove um manipulador de eventos para o evento settingsChanged.
removeHandlerAsync(eventType, callback)	Remove um manipulador de eventos para o evento settingsChanged.
saveAsync(options, callback)	Mantém a cópia na memória do recipiente de propriedades de configurações no documento.
saveAsync(callback)	Mantém a cópia na memória do recipiente de propriedades de configurações no documento.
set(name, value)	Define ou cria a configuração especificada. Importante: esteja ciente de que o método Settings.set afeta apenas a cópia na memória do saco de propriedades de configurações. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

Detalhes do método

addHandlerAsync(eventType, handler, options, callback)

Adiciona um manipulador de eventos para o evento settingsChanged.

Importante: o código do suplemento pode registrar um manipulador para o evento settingsChanged quando o suplemento estiver em execução com qualquer cliente do Excel, mas o evento será disparado somente quando o suplemento for carregado com uma planilha aberta no Excel na Web e mais de um usuário estiver editando a planilha (coautoria). Portanto, efetivamente, o evento settingsChanged só tem suporte em Excel na Web em cenários de coautoria.

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Parâmetros

eventType

Office.EventType

Especifica o tipo de evento a ser adicionado. Obrigatório.

handler

any

A função do manipulador de eventos a ser adicionada, cujo único parâmetro é do tipo Office.SettingsChangedEventArgs. Obrigatório.

options

Office.AsyncContextOptions

Fornece uma opção para preservar dados de contexto de qualquer tipo, inalterados, para uso em um retorno de chamada.

callback

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Propriedade	Usar
AsyncResult.value	Sempre retorna undefined porque não há dados ou objeto a ser recuperado ao adicionar um manipulador de eventos.
AsyncResult.status	Determinar o sucesso ou falha da operação.
AsyncResult.error	Acessar um objeto Error que fornecerá informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo retornado no objeto AsyncResult sem ser alterado.

Retornos

void

Comentários

Conjunto de requisitos: não em um conjunto

Você pode adicionar vários manipuladores de eventos para o eventType especificado desde que o nome de cada função do manipulador de eventos seja exclusivo.

addHandlerAsync(eventType, handler, callback)

Adiciona um manipulador de eventos para o evento settingsChanged.

Importante: o código do suplemento pode registrar um manipulador para o evento settingsChanged quando o suplemento estiver em execução com qualquer cliente do Excel, mas o evento será disparado somente quando o suplemento for carregado com uma planilha aberta no Excel na Web e mais de um usuário estiver editando a planilha (coautoria). Portanto, efetivamente, o evento settingsChanged só tem suporte em Excel na Web em cenários de coautoria.

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult<void>) => void): void;

Parâmetros

eventType

Office.EventType

Especifica o tipo de evento a ser adicionado. Obrigatório.

handler

any

A função do manipulador de eventos a ser adicionada, cujo único parâmetro é do tipo Office.SettingsChangedEventArgs. Obrigatório.

callback

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Propriedade	Usar
AsyncResult.value	Sempre retorna undefined porque não há dados ou objeto a ser recuperado ao adicionar um manipulador de eventos.
AsyncResult.status	Determinar o sucesso ou falha da operação.
AsyncResult.error	Acessar um objeto Error que fornecerá informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo retornado no objeto AsyncResult sem ser alterado.

Retornos

void

Comentários

Conjunto de requisitos: não em um conjunto

Você pode adicionar vários manipuladores de eventos para o eventType especificado desde que o nome de cada função do manipulador de eventos seja exclusivo.

Exemplos

function addSelectionChangedEventHandler() {
    Office.context.document.settings.addHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

get(name)

Recupera a configuração especificada.

get(name: string): any;

Parâmetros

name

string

Retornos

any

Um objeto que tem nomes de propriedade mapeados para valores serializados JSON.

Comentários

Conjunto de requisitos: Configurações

Exemplos

function displayMySetting() {
    write('Current value for mySetting: ' + Office.context.document.settings.get('mySetting'));
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

refreshAsync(callback)

Lê todas as configurações persistentes no documento e atualiza a cópia do suplemento de conteúdo ou painel de tarefas dessas configurações mantidas na memória.

refreshAsync(callback?: (result: AsyncResult<Office.Settings>) => void): void;

Parâmetros

callback

(result: Office.AsyncResult<Office.Settings>) => void

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult. A value propriedade do resultado é um objeto Office.Settings com os valores atualizados.

Retornos

void

Comentários

Conjunto de requisitos: não em um conjunto

Esse método é útil em cenários de coautoria do Excel, Word e PowerPoint quando várias instâncias do mesmo suplemento estão funcionando no mesmo documento. Como cada suplemento está funcionando em uma cópia na memória das configurações carregadas do documento no momento em que o usuário o abriu, os valores de configurações usados por cada usuário podem sair da sincronização. Isso pode acontecer sempre que uma instância do suplemento chama o método Settings.saveAsync para persistir todas as configurações desse usuário no documento. Chamar o método refreshAsync do manipulador de eventos para o evento settingsChanged do suplemento atualizará os valores de configurações para todos os usuários.

Na função de retorno de chamada passada para o método refreshAsync, você pode usar as propriedades do objeto AsyncResult para retornar as informações a seguir.

Propriedade	Usar
AsyncResult.value	Acessar um objeto Settings com os valores atualizados.
AsyncResult.status	Determinar o sucesso ou falha da operação.
AsyncResult.error	Acessar um objeto Error que fornecerá informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo retornado no objeto AsyncResult sem ser alterado.

Exemplos

function refreshSettings() {
    Office.context.document.settings.refreshAsync(function (asyncResult) {
        write('Settings refreshed with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

remove(name)

Remove a configuração especificada.

Importante: esteja ciente de que o método Settings.remove afeta apenas a cópia na memória do saco de propriedades de configurações. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.

remove(name: string): void;

Parâmetros

name

string

Retornos

void

Comentários

Conjunto de requisitos: Configurações

null é um valor válido para uma configuração. Portanto, atribuir null à configuração não a removerá do recipiente de propriedades das configurações.

Exemplos

function removeMySetting() {
    Office.context.document.settings.remove('mySetting');
}

removeHandlerAsync(eventType, options, callback)

Remove um manipulador de eventos para o evento settingsChanged.

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

Parâmetros

eventType

Office.EventType

Especifica o tipo de evento a ser removido. Obrigatório.

options

Office.RemoveHandlerOptions

Fornece opções para determinar quais manipuladores ou manipuladores de eventos são removidos.

callback

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: não em um conjunto

Se o parâmetro de manipulador opcional for omitido ao chamar o método removeHandlerAsync, todos os manipuladores de eventos para o eventType especificado serão removidos.

Quando a função que você passou para o parâmetro de retorno de chamada é executada, ela recebe um objeto AsyncResult que você pode acessar do único parâmetro da função de retorno de chamada.

Na função de retorno de chamada passada para o método removeHandlerAsync, você pode usar as propriedades do objeto AsyncResult para retornar as informações a seguir.

Propriedade	Usar
AsyncResult.value	Sempre retorna undefined porque não há dados ou objeto a ser recuperado ao definir formatos.
AsyncResult.status	Determinar o sucesso ou falha da operação.
AsyncResult.error	Acessar um objeto Error que fornecerá informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo retornado no objeto AsyncResult sem ser alterado.

removeHandlerAsync(eventType, callback)

Remove um manipulador de eventos para o evento settingsChanged.

removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult<void>) => void): void;

Parâmetros

eventType

Office.EventType

Especifica o tipo de evento a ser removido. Obrigatório.

callback

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: não em um conjunto

Se o parâmetro de manipulador opcional for omitido ao chamar o método removeHandlerAsync, todos os manipuladores de eventos para o eventType especificado serão removidos.

Quando a função que você passou para o parâmetro de retorno de chamada é executada, ela recebe um objeto AsyncResult que você pode acessar do único parâmetro da função de retorno de chamada.

Na função de retorno de chamada passada para o método removeHandlerAsync, você pode usar as propriedades do objeto AsyncResult para retornar as informações a seguir.

Propriedade	Usar
AsyncResult.value	Sempre retorna undefined porque não há dados ou objeto a ser recuperado ao definir formatos.
AsyncResult.status	Determinar o sucesso ou falha da operação.
AsyncResult.error	Acessar um objeto Error que fornecerá informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo retornado no objeto AsyncResult sem ser alterado.

Exemplos

function removeSettingsChangedEventHandler() {
    Office.context.document.settings.removeHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

saveAsync(options, callback)

Mantém a cópia na memória do recipiente de propriedades de configurações no documento.

saveAsync(options?: SaveSettingsOptions, callback?: (result: AsyncResult<void>) => void): void;

Parâmetros

options

Office.SaveSettingsOptions

Fornece opções para salvar configurações.

callback

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: Configurações

Quaisquer configurações previamente salvas por um suplemento são carregadas quando ele for inicializado, portanto, durante o tempo de vida da sessão, você pode simplesmente usar os métodos set e get para trabalhar com a cópia na memória do recipiente de propriedades de configurações. Quando você desejar manter as configurações para que elas fiquem disponíveis na próxima vez que o suplemento for usado, use o método saveAsync.

Observação: o método saveAsync persiste o saco de propriedades de configurações na memória no arquivo do documento. No entanto, as alterações no arquivo de documento em si são salvas somente quando o usuário (ou configuração AutoRecover) salva o documento no sistema de arquivos. O método refreshAsync só é útil em cenários de coautoria quando outras instâncias do mesmo suplemento podem alterar as configurações e essas alterações devem ser disponibilizadas para todas as instâncias.

Propriedade	Usar
AsyncResult.value	Sempre retorna undefined porque não há nenhum objeto ou dados para recuperar.
AsyncResult.status	Determinar o sucesso ou falha da operação.
AsyncResult.error	Acessar um objeto Error que fornecerá informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo retornado no objeto AsyncResult sem ser alterado.

saveAsync(callback)

Mantém a cópia na memória do recipiente de propriedades de configurações no documento.

saveAsync(callback?: (result: AsyncResult<void>) => void): void;

Parâmetros

callback

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

Opcional. Uma função que é invocada quando o retorno de chamada retorna, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: Configurações

Quaisquer configurações previamente salvas por um suplemento são carregadas quando ele for inicializado, portanto, durante o tempo de vida da sessão, você pode simplesmente usar os métodos set e get para trabalhar com a cópia na memória do recipiente de propriedades de configurações. Quando você desejar manter as configurações para que elas fiquem disponíveis na próxima vez que o suplemento for usado, use o método saveAsync.

Observação: o método saveAsync persiste o saco de propriedades de configurações na memória no arquivo do documento. No entanto, as alterações no arquivo de documento em si são salvas somente quando o usuário (ou configuração AutoRecover) salva o documento no sistema de arquivos. O método refreshAsync só é útil em cenários de coautoria quando outras instâncias do mesmo suplemento podem alterar as configurações e essas alterações devem ser disponibilizadas para todas as instâncias.

Propriedade	Usar
AsyncResult.value	Sempre retorna undefined porque não há nenhum objeto ou dados para recuperar.
AsyncResult.status	Determinar o sucesso ou falha da operação.
AsyncResult.error	Acessar um objeto Error que fornecerá informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo retornado no objeto AsyncResult sem ser alterado.

Exemplos

function persistSettings() {
    Office.context.document.settings.saveAsync(function (asyncResult) {
        write('Settings saved with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

set(name, value)

Define ou cria a configuração especificada.

Importante: esteja ciente de que o método Settings.set afeta apenas a cópia na memória do saco de propriedades de configurações. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

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

Parâmetros

name

string

value

any

Specifies the value to be stored.

Retornos

void

Comentários

Conjunto de requisitos: Configurações

O método set cria uma nova configuração do nome especificado se ele ainda não existir ou definir uma configuração existente do nome especificado na cópia na memória do saco de propriedades de configurações. Após chamar o método Settings.saveAsync, o valor é armazenado no documento como a representação JSON serializada do seu tipo de dados.

Exemplos

function setMySetting() {
    Office.context.document.settings.set('mySetting', 'mySetting value');
}