Trabalhar com eventos usando a API JavaScript do Excel

  • Artigo

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 uma pasta de trabalho é ativada. 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 planilha é movida dentro de uma pasta de trabalho. WorksheetCollection
onNameChanged Ocorre quando o nome da planilha é alterado. Planilha, WorksheetCollection
onProtectionChanged Ocorre quando o estado de proteção de planilha é 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. Associação, Tabela, Pasta de Trabalho, Planilha, Pasta de TrabalhoCollection
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 planilha é 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 usar esse recurso, você deve usar a versão prévia da biblioteca de API JavaScript do Office da CDN (rede de distribuição de conteúdo)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

Todas as alterações que sejam compatíveis com o comportamento padrão do Excel acionarão eventos correspondentes em uma pasta de trabalho.

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. Observe que o RequestContext usado para criar o manipulador 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() {
  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