Office.Settings interface

Adiciona um manipulador de eventos para o settingsChanged evento.

Importante: o código do suplemento pode registrar um manipulador para o settingsChanged evento quando o suplemento estiver em execução com qualquer cliente do Excel, mas o evento será acionado 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 settingsChanged evento tem suporte apenas no 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

Retornos

Comentários

Conjunto de requisitos: não em um conjunto

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

Adiciona um manipulador de eventos para o settingsChanged evento.

Importante: o código do suplemento pode registrar um manipulador para o settingsChanged evento quando o suplemento estiver em execução com qualquer cliente do Excel, mas o evento será acionado 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 settingsChanged evento tem suporte apenas no Excel na Web em cenários de coautoria.

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

Parâmetros

Retornos

Comentários

Conjunto de requisitos: não em um conjunto

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

Exemplos

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

function MyHandler(eventArgs: Office.SettingsChangedEventArgs) {
    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;
}

Recupera a configuração especificada.

get(name: string): any;

Parâmetros

Retornos

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;
}

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

Retornos

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 trabalhando no mesmo documento. Como cada suplemento está trabalhando 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 ficar fora de sincronia. Isso pode acontecer sempre que uma instância do suplemento chama o Settings.saveAsync método para manter todas as configurações desse usuário no documento. Chamar o refreshAsync método do manipulador de eventos para o settingsChanged evento do suplemento atualizará os valores de configurações para todos os usuários.

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

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 a configuração especificada.

Importante: Lembre-se de que o Settings.remove método afeta apenas a cópia na memória do recipiente de propriedades de configurações. Para manter a remoção da configuração especificada no documento, em algum momento após chamar o Settings.remove método e antes que o suplemento seja fechado, você deve chamar o Settings.saveAsync método.

remove(name: string): void;

Parâmetros

Retornos

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 de configurações.

Exemplos

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

Remove um manipulador de eventos para o settingsChanged evento.

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

Parâmetros

Retornos

Comentários

Conjunto de requisitos: não em um conjunto

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

Quando a função que você passou para o parâmetro de retorno de chamada é executada, ela recebe um AsyncResult objeto 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 removeHandlerAsync método, você pode usar as propriedades do objeto para retornar as informações a AsyncResult seguir.

Remove um manipulador de eventos para o settingsChanged evento.

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

Parâmetros

Retornos

Comentários

Conjunto de requisitos: não em um conjunto

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

Quando a função que você passou para o parâmetro de retorno de chamada é executada, ela recebe um AsyncResult objeto 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 removeHandlerAsync método, você pode usar as propriedades do objeto para retornar as informações a AsyncResult seguir.

Exemplos

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

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

Retornos

Comentários

Conjunto de requisitos: Configuraçõ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 persiste o recipiente de propriedades de configurações na memória no arquivo do documento. No entanto, as alterações no próprio arquivo de documento são salvas somente quando o usuário (ou a configuração de AutoRecuperação) salva o documento no sistema de arquivos. O refreshAsync método 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.

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

Retornos

Comentários

Conjunto de requisitos: Configuraçõ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 persiste o recipiente de propriedades de configurações na memória no arquivo do documento. No entanto, as alterações no próprio arquivo de documento são salvas somente quando o usuário (ou a configuração de AutoRecuperação) salva o documento no sistema de arquivos. O refreshAsync método 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.

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;
}

Define ou cria a configuração especificada.

Importante: Lembre-se de que o Settings.set método afeta apenas a cópia na memória do recipiente de propriedades de configurações. Para garantir que as adições ou alterações nas configurações estarão disponíveis para o suplemento na próxima vez que o documento for aberto, em algum momento depois de chamar o Settings.set método e antes de o suplemento ser fechado, você deve chamar o método para manter as Settings.saveAsync configurações no documento.

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

Parâmetros

Retornos

Comentários

Conjunto de requisitos: Configurações

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

Exemplos

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