Trabalhar com eventos usando a API JavaScript do Excel

Este artigo descreve conceitos importantes relacionados ao trabalho com eventos no Excel e fornece exemplos de código que mostram como registrar manipuladores de eventos, lidar com eventos e remover manipuladores de eventos usando as APIs JavaScript do Excel.

Eventos no Excel

Sempre que ocorrerem certos tipos de alterações em uma pasta de trabalho do Excel, uma notificação do evento será ativada. Ao usar as APIs JavaScript do Excel, você pode registrar manipuladores de eventos que permitem que o suplemento execute automaticamente uma função designada quando ocorre um evento específico. Os eventos a seguir têm suporte no momento:

Evento	Descrição	Objetos com suporte
onActivated	Ocorre quando um objeto está ativado.	Gráfico, ChartCollection, Shape, Planilha, WorksheetCollection
onActivated	Ocorre quando um livro é ativado.	Workbook
onAdded	Ocorre quando um objeto é adicionado à coleção.	ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onAutoSaveSettingChanged	Ocorre quando a autoSave configuração é alterada na pasta de trabalho.	Workbook
onCalculated	Ocorre quando uma planilha terminou um cálculo (ou todas as planilhas do conjunto terminaram).	WorksheetCollection, Planilha
onChanged	Ocorre quando os dados de células ou comentários individuais são alterados.	CommentCollection, Table, TableCollection, Worksheet, WorksheetCollection
onColumnSorted	Ocorre quando uma ou mais colunas são classificadas. Isso acontece como resultado de uma operação de classificação da esquerda para a direita.	Planilha, WorksheetCollection
onDataChanged	Ocorre quando os dados ou a formatação dentro da associação são alterados.	Associação
onDeactivated	Ocorre quando um objeto é desativado.	Gráfico, ChartCollection, Shape, Planilha, WorksheetCollection
onDeleted	Ocorre quando um objeto é excluído da coleção.	ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onFormatChanged	Ocorre quando o formato é alterado em uma planilha.	Planilha, WorksheetCollection
onFormulaChanged	Ocorre quando uma fórmula é alterada.	Planilha, WorksheetCollection
onMoved	Ocorre quando uma folha de cálculo é movida dentro de um livro.	WorksheetCollection
onNameChanged	Ocorre quando o nome da folha de cálculo é alterado.	Planilha, WorksheetCollection
onProtectionChanged	Ocorre quando o estado de proteção da folha de cálculo é alterado.	Planilha, WorksheetCollection
onRowHiddenChanged	Ocorre quando o estado de linha oculta é alterado em uma planilha específica.	Planilha, WorksheetCollection
onRowSorted	Ocorre quando uma ou mais linhas são classificadas. Isso ocorre como resultado de uma operação de classificação de cima para baixo.	Planilha, WorksheetCollection
onSelectionChanged	Ocorre quando uma célula ativa ou um intervalo selecionado são alterados.	Enlace, Tabela, Livro, Folha de Cálculo, Recolha de Folhas de Cálculo
onSettingsChanged	Ocorre quando as Configurações no documento são alteradas.	SettingCollection
onSingleClicked	Acontece quando a operação é clicada/pressionada com o botão esquerdo do mouse ocorre na planilha.	Planilha, WorksheetCollection
onVisibilityChanged	Ocorre quando a visibilidade da folha de cálculo é alterada.	Planilha, WorksheetCollection

Eventos no modo de visualização

Observação

Os seguintes eventos estão disponíveis atualmente apenas na visualização pública. Para utilizar esta funcionalidade, tem de utilizar a versão de pré-visualização da biblioteca da API JavaScript do Office a partir da rede de entrega de conteúdos (CDN)Office.js. O arquivo de definição de tipo da compilação TypeScript e IntelliSense pode ser encontrado na CDN e DefinitelyTyped. Você pode instalar esses tipos com npm install --save-dev @types/office-js-preview. Para mais informações sobre as nossas futuras APIs, visite Conjuntos de requisitos da API JavaScript do Excel.

Evento	Descrição	Objetos com suporte
onFiltered	Ocorre quando um filtro é aplicado a um objeto.	Tabela, TableCollection, Planilha, WorksheetCollection

Gatilhos de eventos

Os eventos em uma pasta de trabalho do Excel podem ser acionados por:

• Interação do usuário por meio da interface (IU) do Excel que altera a pasta de trabalho
• Código de suplemento do Office (JavaScript) que altera a pasta de trabalho
• Código de suplemento VBA (macro) que altera a pasta de trabalho

Qualquer alteração que cumpra o comportamento predefinido do Excel acionará os eventos correspondentes num livro.

Ciclo de vida de um manipulador de eventos

Um manipulador de eventos é criado quando um suplemento registra o manipulador de eventos. Ele é destruído quando o suplemento cancela o registro de manipulador de evento ou quando o suplemento é atualizado, recarregado ou fechado. Manipuladores de eventos não são mantidos como parte do arquivo do Excel ou em sessões do Excel Online.

Cuidado

Quando um objeto ao qual os eventos são registrados é excluído (por exemplo, uma tabela com um onChanged evento registrado), o manipulador de eventos não disparará mais, mas permanecerá na memória até que o suplemento ou sessão do Excel atualize ou feche.

Eventos e coautoria

Com a coautoria, várias pessoas podem trabalhar em conjunto e editar a mesma pasta de trabalho do Excel simultaneamente. Em eventos que podem ser disparados por um coautor, como onChanged, o objeto de evento respectivo conterá a propriedade fonte que indica se o evento foi acionado localmente pelo usuário atual (event.source == Local) ou pelo coautor remoto (event.source == Remote).

Registrar um manipulador de eventos.

O exemplo de código a seguir registra um manipulador de eventos para o evento onChanged na planilha Sample. O código especifica que, quando os dados forem alterados na planilha, a função handleChange deve ser executada.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getItem("Sample");
    worksheet.onChanged.add(handleChange);

    await context.sync();
    console.log("Event handler successfully registered for onChanged event in the worksheet.");
}).catch(errorHandlerFunction);

Manipular um evento

Como mostrado no exemplo anterior, quando você registrar um manipulador de eventos, indica a função a ser executada quando o evento especificado ocorre. Você pode criar essa função para executar as ações que seu cenário exige. O exemplo de código a seguir mostra uma função de manipulador de eventos que simplesmente grava informações sobre o evento no console.

async function handleChange(event) {
    await Excel.run(async (context) => {
        await context.sync();        
        console.log("Change type of event: " + event.changeType);
        console.log("Address of event: " + event.address);
        console.log("Source of event: " + event.source);       
    }).catch(errorHandlerFunction);
}

Remover um manipulador de eventos

O exemplo de código a seguir registra um manipulador de eventos para o evento onSelectionChanged na planilha Sample e define a função handleSelectionChange a executar quando o evento ocorrer. Também define a função remove() que pode ser chamada posteriormente para remover aquele manipulador de eventos. Tenha em atenção que o RequestContext utilizado para criar o processador de eventos é necessário para removê-lo.

let eventResult;

async function run() {
  await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getItem("Sample");
    eventResult = worksheet.onSelectionChanged.add(handleSelectionChange);

    await context.sync();
    console.log("Event handler successfully registered for onSelectionChanged event in the worksheet.");
  });
}

async function handleSelectionChange(event) {
  await Excel.run(async (context) => {
    await context.sync();
    console.log("Address of current selection: " + event.address);
  });
}

async function remove() {
  // The `RequestContext` used to create the event handler is needed to remove it.
  // In this example, `eventContext` is being used to keep track of that context.
  await Excel.run(eventResult.context, async (context) => {
    eventResult.remove();
    await context.sync();
    
    eventResult = null;
    console.log("Event handler successfully removed.");
  });
}

Habilitar e desabilitar eventos

O desempenho de um suplemento pode ser melhorado desabilitando eventos. Por exemplo, seu aplicativo pode não precisar receber eventos ou ele pode ignorar eventos durante a edições de lotes de várias entidades.

Os eventos são habilitados ou desabilitados no nível runtime. A enableEvents propriedade determina se os eventos são disparados e se seus manipuladores são ativados.

O código a seguir mostra como ativar ou desativar os eventos.

await Excel.run(async (context) => {
    context.runtime.load("enableEvents");
    await context.sync();

    let eventBoolean = !context.runtime.enableEvents;
    context.runtime.enableEvents = eventBoolean;
    if (eventBoolean) {
        console.log("Events are currently on.");
    } else {
        console.log("Events are currently off.");
    }
    
    await context.sync();
});

Confira também

• Modelo de objeto JavaScript do Excel em Suplementos do Office