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

  • Статья

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

События в Excel

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

Событие Описание Поддерживаемые объекты
onActivated Возникает при активации объекта. Chart, ChartCollection, Shape, Worksheet, WorksheetCollection
onActivated Происходит при активации книги. Workbook
onAdded Возникает при добавлении объекта в коллекцию. ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onAutoSaveSettingChanged Возникает при изменении параметра autoSave для книги. Workbook
onCalculated Возникает после завершения вычислений на листе (или на всех листах коллекции). Worksheet, WorksheetCollection
onChanged Происходит при изменении данных отдельных ячеек или комментариев. CommentCollection, Table, TableCollection, Worksheet, WorksheetCollection
onColumnSorted Возникает при сортировке одного или нескольких столбцов. Происходит в результате операции сортировки слева направо. Worksheet, WorksheetCollection
onDataChanged Возникает при изменении данных или форматирования в привязке. Binding
onDeactivated Возникает при отключении объекта. Chart, ChartCollection, Shape, Worksheet, WorksheetCollection
onDeleted Возникает при удалении объекта из коллекции. ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onFormatChanged Возникает при изменении формата на листе. Worksheet, WorksheetCollection
onFormulaChanged Происходит при изменении формулы. Worksheet, WorksheetCollection
onMoved Происходит при перемещении листа внутри книги. WorksheetCollection
onNameChanged Происходит при изменении имени листа. Worksheet, WorksheetCollection
onProtectionChanged Происходит при изменении состояния защиты листа. Worksheet, WorksheetCollection
onRowHiddenChanged Возникает при изменении состояния скрытия строки на определенном листе. Worksheet, WorksheetCollection
onRowSorted Возникает при сортировке одной или нескольких строк. Происходит в результате операции сортировки сверху вниз. Worksheet, WorksheetCollection
onSelectionChanged Возникает при изменении активной ячейки или выбранного диапазона. Binding, Table, Workbook, Worksheet, WorksheetCollection
onSettingsChanged Возникает при изменении параметров в документе. SettingCollection
onSingleClicked Возникает, когда происходит щелчок левой кнопкой мыши или нажатие на листе. Worksheet, WorksheetCollection
onVisibilityChanged Происходит при изменении видимости листа. Worksheet, WorksheetCollection

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

Примечание.

Следующие события в настоящее время доступны только в общедоступной предварительной версии. Чтобы использовать эту функцию, необходимо использовать предварительную версию библиотеки API JavaScript для Office из сети доставки содержимого (CDN)Office.js. Файл определения типа для компиляции TypeScript и IntelliSense находится в сети CDN и имеет тип DefinitelyTyped. Эти типы можно установить с помощью npm install --save-dev @types/office-js-preview. Дополнительные сведения о наших планируемых API см. в статье Наборы обязательных элементов API JavaScript для Excel.

Событие Описание Поддерживаемые объекты
onFiltered Возникает при применении фильтра к объекту. Table, TableCollection, Worksheet, WorksheetCollection

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

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

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

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

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

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

Предостережение

Когда объект, для которого зарегистрированы события, удаляется (например, таблица с зарегистрированным событием onChanged), обработчик событий больше не запускается, но остается в памяти, пока сеанс надстройки или 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() {
  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();
});

См. также