Работа с событиями при помощи 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() {
  // 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