Работа с событиями при помощи API JavaScript для Excel

В этой статье описываются важные понятия, относящиеся к работе с событиями в Excel, а также представлены образцы кода, иллюстрирующие регистрацию, использование и удаление обработчиков событий при помощи API JavaScript для Excel.

События в Excel

Каждый раз, когда в книге Excel происходят изменения определенного типа, срабатывает уведомление о событии. С помощью API JavaScript для Excel можно регистрировать обработчики событий, позволяющие надстройке автоматически выполнять специальную функцию при возникновении определенного события. Ниже перечислены поддерживаемые в настоящее время события.

События в предварительной версии

Триггеры событий

События в книге Excel могут вызываться:

• при взаимодействии пользователя с интерфейсом Excel, вносящим изменения в книгу;
• из кода (JavaScript) надстройки Office, вносящего изменения в книгу;
• из кода (макроса) надстройки VBA, вносящего изменения в книгу.

Любое изменение, соответствующее поведению Excel по умолчанию, активирует соответствующие события в книге.

Жизненный цикл обработчика событий

Обработчик событий создается при его регистрации надстройкой. Он удаляется при отмене его регистрации надстройкой или при обновлении, перезагрузке или закрытии надстройки. Обработчики событий не остаются в составе файла Excel или между сеансами с интернет-версией Excel.

События и совместное редактирование

Несколько человек могут работать вместе и одновременно редактировать одну книгу Excel. Для событий, которые может вызвать соавтор, в частности onChanged, соответствующий объект Event будет содержать свойство source, указывающее, кем было вызвано событие: локальным пользователем (event.source == Local) или удаленным соавтором (event.source == Remote).

Регистрация обработчика событий

В приведенном ниже примере кода регистрируется обработчик события onChanged на листе под названием Sample. В этом коде указано, что при изменении данных на этом листе должна выполняться функция handleChange.

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

Обработка событий

Как показано в предыдущем примере, при регистрации обработчика событий вы задаете функцию, которая должна выполняться при возникновении указанного события. Вы можете настроить эту функцию на выполнение любых действий, необходимых для вашего сценария. В приведенном ниже примере кода показана функция обработчика событий, которая просто записывает сведения о событии в консоль.

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

Удаление обработчика события

В приведенном ниже примере кода регистрируется обработчик событий onSelectionChanged на листе под названием Sample и определяется функция handleSelectionChange, которая будет выполняться при возникновении события. В нем также определяется функция remove(), которую можно впоследствии вызвать для удаления обработчика событий. Обратите внимание, что RequestContext для его удаления требуется объект , используемый для создания обработчика событий.

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.");
  });
}

Включение и отключение событий

Производительность надстройки можно повысить с помощью отключения событий. Например, вашему приложению, возможно, никогда не потребуется получать события, или оно может игнорировать события при выполнении пакетных изменений нескольких сущностей.

События включаются и отключаются на уровне среды выполнения. Свойство enableEvents определяет, будут ли запускаться события и будут ли активироваться их обработчики.

В приведенном ниже примере кода показано, как включать и отключать события.

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

См. также

• Объектная модель JavaScript для Excel в надстройках Office