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 Settings objeto 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 Settings objeto é carregado automaticamente como parte do Document objeto e está disponível ao chamar a propriedade de definições desse objeto quando o suplemento é ativado.

O programador é responsável por chamar o saveAsync método depois de adicionar ou eliminar as definições para guardar as definições no documento.

Métodos

addHandlerAsync(eventType, handler, options, callback)	Adiciona um processador de eventos para o settingsChanged evento. Importante: o código do suplemento pode registar um processador para o settingsChanged evento 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 settingsChanged evento só é suportado em Excel na Web em cenários de cocriação.
addHandlerAsync(eventType, handler, callback)	Adiciona um processador de eventos para o settingsChanged evento. Importante: o código do suplemento pode registar um processador para o settingsChanged evento 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 settingsChanged evento 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 Settings.remove método afeta apenas a cópia dentro da memória do saco de propriedades das definições. Para manter a remoção da definição especificada no documento, em algum momento após chamar o Settings.remove método e antes de o suplemento ser fechado, tem de chamar o Settings.saveAsync método .
removeHandlerAsync(eventType, options, callback)	Remove um processador de eventos para o settingsChanged evento.
removeHandlerAsync(eventType, callback)	Remove um processador de eventos para o settingsChanged evento.
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 Settings.set método afeta apenas a cópia dentro da memória do saco de propriedades das definições. Para se certificar de que as adições ou alterações às definições estarão disponíveis para o seu suplemento da próxima vez que o documento for aberto, em algum momento após chamar o Settings.set método e antes de o suplemento ser fechado, tem de chamar o Settings.saveAsync método para manter as definições no documento.

Detalhes do método

addHandlerAsync(eventType, handler, options, callback)

Adiciona um processador de eventos para o settingsChanged evento.

Importante: o código do suplemento pode registar um processador para o settingsChanged evento 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 settingsChanged evento 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	Aceda a um Error objeto que forneça informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo que seja devolvido no AsyncResult objeto sem ser alterado.

Retornos

void

Comentários

Conjunto de requisitos: não está num conjunto

Pode adicionar vários processadores de eventos para o especificado eventType , 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 settingsChanged evento.

Importante: o código do suplemento pode registar um processador para o settingsChanged evento 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 settingsChanged evento 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	Aceda a um Error objeto que forneça informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo que seja devolvido no AsyncResult objeto sem ser alterado.

Retornos

void

Comentários

Conjunto de requisitos: não está num conjunto

Pode adicionar vários processadores de eventos para o especificado eventType , 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 Settings.saveAsync método para manter todas as definições desse utilizador no documento. Chamar o refreshAsync método do processador de eventos para o settingsChanged evento do suplemento irá atualizar os valores de definições para todos os utilizadores.

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

Propriedade	Usar
AsyncResult.value	Aceda a um Settings objeto com os valores atualizados.
AsyncResult.status	Determinar o sucesso ou falha da operação.
AsyncResult.error	Aceda a um Error objeto que forneça informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo que seja devolvido no AsyncResult objeto 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 Settings.remove método afeta apenas a cópia dentro da memória do saco de propriedades das definições. Para manter a remoção da definição especificada no documento, em algum momento após chamar o Settings.remove método e antes de o suplemento ser fechado, tem de chamar o Settings.saveAsync método .

remove(name: string): void;

Parâmetros

name

string

Retornos

void

Comentários

Conjunto de requisitos: Definições

null é um valor válido para uma definição. Por conseguinte, atribuir null à definição não irá removê-la do saco de propriedades de definições.

Exemplos

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

removeHandlerAsync(eventType, options, callback)

Remove um processador de eventos para o settingsChanged evento.

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 removeHandlerAsync método , todos os processadores de eventos para o especificado eventType serão removidos.

Quando a função que passou para o parâmetro de chamada de retorno é executada, recebe um AsyncResult objeto 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 ao removeHandlerAsync método , pode utilizar as propriedades do AsyncResult objeto 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	Aceda a um Error objeto que forneça informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo que seja devolvido no AsyncResult objeto sem ser alterado.

removeHandlerAsync(eventType, callback)

Remove um processador de eventos para o settingsChanged evento.

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 removeHandlerAsync método , todos os processadores de eventos para o especificado eventType serão removidos.

Quando a função que passou para o parâmetro de chamada de retorno é executada, recebe um AsyncResult objeto 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 ao removeHandlerAsync método , pode utilizar as propriedades do AsyncResult objeto 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	Aceda a um Error objeto que forneça informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo que seja devolvido no AsyncResult objeto 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 é iniciado, portanto, durante a 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ê deseja manter as configurações para que elas fiquem disponíveis na próxima vez em que o suplemento for usado, use o método saveAsync.

Nota: o saveAsync método 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 refreshAsync método 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	Aceda a um Error objeto que forneça informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo que seja devolvido no AsyncResult objeto 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 é iniciado, portanto, durante a 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ê deseja manter as configurações para que elas fiquem disponíveis na próxima vez em que o suplemento for usado, use o método saveAsync.

Nota: o saveAsync método 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 refreshAsync método 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	Aceda a um Error objeto que forneça informações de erro se a operação tiver falhado.
AsyncResult.asyncContext	Defina um item de qualquer tipo que seja devolvido no AsyncResult objeto 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 Settings.set método afeta apenas a cópia dentro da memória do saco de propriedades das definições. Para se certificar de que as adições ou alterações às definições estarão disponíveis para o seu suplemento da próxima vez que o documento for aberto, em algum momento após chamar o Settings.set método e antes de o suplemento ser fechado, tem de chamar o Settings.saveAsync método para manter as definições no documento.

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 set método 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. Depois de chamar o Settings.saveAsync método , o valor é armazenado no documento como a representação JSON serializada do respetivo tipo de dados.

Exemplos

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