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

Aplicações: Excel, PowerPoint Word

As definições criadas com os métodos do objeto Definições são guardadas 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 definição é uma cadeia, enquanto o valor pode ser uma cadeia, número, booleano, nulo, objeto ou matriz.

O objeto Definições é carregado automaticamente como parte do objeto Documento e está disponível ao chamar a propriedade definiçõ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 processador de eventos para o evento settingsChanged. Importante: o código do suplemento pode registar um processador para o evento SettingsChanged quando o suplemento está em execução com qualquer cliente do Excel, mas o evento só será acionado quando o suplemento for carregado com uma folha de cálculo aberta no Excel na Web e mais do que um utilizador estiver a editar a folha de cálculo (cocriação). Por conseguinte, efetivamente, o evento settingsChanged só é suportado em Excel na Web em cenários de cocriação.
addHandlerAsync(eventType, handler, callback)	Adiciona um processador de eventos para o evento settingsChanged. Importante: o código do suplemento pode registar um processador para o evento SettingsChanged quando o suplemento está em execução com qualquer cliente do Excel, mas o evento só será acionado quando o suplemento for carregado com uma folha de cálculo aberta no Excel na Web e mais do que um utilizador estiver a editar a folha de cálculo (cocriação). Por conseguinte, efetivamente, o evento settingsChanged só é suportado em Excel na Web em cenários de cocriação.
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: tenha em atenção que o método Settings.remove afeta apenas a cópia dentro da memória do pacote de propriedades das definiçõ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 processador de eventos para o evento settingsChanged.
removeHandlerAsync(eventType, callback)	Remove um processador 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: tenha em atenção que o método Settings.set afeta apenas a cópia dentro da memória do saco de propriedades das definiçõ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 processador de eventos para o evento settingsChanged.

Importante: o código do suplemento pode registar um processador para o evento SettingsChanged quando o suplemento está em execução com qualquer cliente do Excel, mas o evento só será acionado quando o suplemento for carregado com uma folha de cálculo aberta no Excel na Web e mais do que um utilizador estiver a editar a folha de cálculo (cocriação). Por conseguinte, efetivamente, o evento settingsChanged só é suportado em Excel na Web em cenários de cocriação.

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 de processador de eventos a adicionar, 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 utilização numa chamada de retorno.

callback

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

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

Propriedade	Usar
AsyncResult.value	Devolve undefined sempre porque não existem dados ou objetos a obter ao adicionar um processador 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 que seja devolvido no objeto AsyncResult sem ser alterado.

Retornos

void

Comentários

Conjunto de requisitos: não está num conjunto

Pode adicionar vários processadores de eventos para o eventType especificado, desde que o nome de cada função de processador de eventos seja exclusivo.

addHandlerAsync(eventType, handler, callback)

Adiciona um processador de eventos para o evento settingsChanged.

Importante: o código do suplemento pode registar um processador para o evento SettingsChanged quando o suplemento está em execução com qualquer cliente do Excel, mas o evento só será acionado quando o suplemento for carregado com uma folha de cálculo aberta no Excel na Web e mais do que um utilizador estiver a editar a folha de cálculo (cocriação). Por conseguinte, efetivamente, o evento settingsChanged só é suportado em Excel na Web em cenários de cocriação.

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 de processador de eventos a adicionar, cujo único parâmetro é do tipo Office.SettingsChangedEventArgs. Obrigatório.

callback

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

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

Propriedade	Usar
AsyncResult.value	Devolve undefined sempre porque não existem dados ou objetos a obter ao adicionar um processador 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 que seja devolvido no objeto AsyncResult sem ser alterado.

Retornos

void

Comentários

Conjunto de requisitos: não está num conjunto

Pode adicionar vários processadores de eventos para o eventType especificado, desde que o nome de cada função de processador 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 com nomes de propriedade mapeados para valores serializados JSON.

Comentários

Conjunto de requisitos: Definiçõ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 a chamada de retorno é devolvida, 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 está num conjunto

Este método é útil no Excel, Word e cenários de cocriação do PowerPoint quando várias instâncias do mesmo suplemento estão a funcionar no mesmo documento. Uma vez que cada suplemento está a trabalhar numa cópia dentro da memória das definições carregadas do documento no momento em que o utilizador o abriu, os valores de definições utilizados por cada utilizador podem ficar dessincronizados. Isto pode acontecer sempre que uma instância do suplemento chamar o método Settings.saveAsync para manter todas as definições desse utilizador no documento. Chamar o método refreshAsync do processador de eventos para o evento settingsChanged do suplemento irá atualizar os valores de definições para todos os utilizadores.

Na função de chamada de retorno transmitida para o método refreshAsync, pode utilizar as propriedades do objeto AsyncResult para devolver as seguintes informações.

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 que seja devolvido 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: tenha em atenção que o método Settings.remove afeta apenas a cópia dentro da memória do pacote de propriedades das definiçõ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: Definiçõ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 processador 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 que processadores ou processadores de eventos são removidos.

callback

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

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

Retornos

void

Comentários

Conjunto de requisitos: não está num conjunto

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

Quando a função que passou para o parâmetro de chamada de retorno é executada, recebe um objeto AsyncResult ao qual pode aceder a partir do único parâmetro da função de chamada de retorno.

Na função de chamada de retorno transmitida para o método removeHandlerAsync, pode utilizar as propriedades do objeto AsyncResult para devolver as seguintes informações.

Propriedade	Usar
AsyncResult.value	Devolve undefined sempre porque não existem dados ou objetos a obter 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 que seja devolvido no objeto AsyncResult sem ser alterado.

removeHandlerAsync(eventType, callback)

Remove um processador 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 a chamada de retorno é devolvida, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: não está num conjunto

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

Quando a função que passou para o parâmetro de chamada de retorno é executada, recebe um objeto AsyncResult ao qual pode aceder a partir do único parâmetro da função de chamada de retorno.

Na função de chamada de retorno transmitida para o método removeHandlerAsync, pode utilizar as propriedades do objeto AsyncResult para devolver as seguintes informações.

Propriedade	Usar
AsyncResult.value	Devolve undefined sempre porque não existem dados ou objetos a obter 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 que seja devolvido 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 guardar definições.

callback

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

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

Retornos

void

Comentários

Conjunto de requisitos: Definiçõ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.

Nota: o método saveAsync mantém o conjunto de propriedades das definições dentro da memória no ficheiro de documento. No entanto, as alterações ao próprio ficheiro de documento só são guardadas quando o utilizador (ou a definição de Recuperação Automática) guarda o documento no sistema de ficheiros. O método refreshAsync só é útil em cenários de cocriação quando outras instâncias do mesmo suplemento podem alterar as definições e essas alterações devem ser disponibilizadas para todas as instâncias.

Propriedade	Usar
AsyncResult.value	Devolve undefined sempre porque não existe nenhum objeto ou dados a obter.
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 que seja devolvido 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 a chamada de retorno é devolvida, cujo único parâmetro é do tipo Office.AsyncResult.

Retornos

void

Comentários

Conjunto de requisitos: Definiçõ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.

Nota: o método saveAsync mantém o conjunto de propriedades das definições dentro da memória no ficheiro de documento. No entanto, as alterações ao próprio ficheiro de documento só são guardadas quando o utilizador (ou a definição de Recuperação Automática) guarda o documento no sistema de ficheiros. O método refreshAsync só é útil em cenários de cocriação quando outras instâncias do mesmo suplemento podem alterar as definições e essas alterações devem ser disponibilizadas para todas as instâncias.

Propriedade	Usar
AsyncResult.value	Devolve undefined sempre porque não existe nenhum objeto ou dados a obter.
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 que seja devolvido 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: tenha em atenção que o método Settings.set afeta apenas a cópia dentro da memória do saco de propriedades das definiçõ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: Definições

O método set cria uma nova definição do nome especificado se ainda não existir ou define uma definição existente do nome especificado na cópia dentro da memória do saco de propriedades das definiçõ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');
}