Arbeiten mit Ereignissen mithilfe der Excel-JavaScript-API

  • Artikel

Dieser Artikel beschreibt wichtige Konzepte im Zusammenhang mit der Verarbeitung von Ereignissen in Excel und zeigt in Codebeispielen, wie Sie mithilfe der Excel-JavaScript-API Ereignishandler registrieren, Ereignisse behandeln und Ereignishandler entfernen.

Ereignisse in Excel

Jedes Mal, wenn bestimmte Arten von Änderungen in einer Excel-Arbeitsmappe vorgenommen werden, wird eine Ereignisbenachrichtigung ausgelöst. Mithilfe der Excel-JavaScript-API können Sie Ereignishandler registrieren, mit denen das Add-In automatisch eine bestimmte Funktion ausführt, wenn ein bestimmtes Ereignis eintritt. Die folgenden Ereignisse werden derzeit unterstützt.

Ereignis Beschreibung Unterstützte Objekte
onActivated Tritt ein, wenn ein Objekt aktiviert wird. Chart, ChartCollection, Shape, Worksheet, WorksheetCollection
onActivated Tritt auf, wenn eine Arbeitsmappe aktiviert wird. Workbook
onAdded Tritt ein, wenn der Auflistung ein Objekt hinzugefügt wird. ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onAutoSaveSettingChanged Tritt ein, wenn die autoSave-Einstellung für die Arbeitsmappe geändert wird. Workbook
onCalculated Tritt ein, wenn ein Arbeitsblatt die Berechnung abgeschlossen hat (oder alle Arbeitsblätter der Sammlung abgeschlossen haben). Worksheet, WorksheetCollection
onChanged Tritt auf, wenn sich die Daten einzelner Zellen oder Kommentare geändert haben. CommentCollection, Table, TableCollection, Worksheet, WorksheetCollection
onColumnSorted Tritt auf, wenn eine oder mehrere Spalten sortiert wurden. Dies geschieht, wenn Spalten von links nach rechts sortiert werden. Worksheet, WorksheetCollection
onDataChanged Tritt ein, wenn die Daten oder die Formatierung in der Datenbindung geändert werden. Binding
onDeactivated Tritt ein, wenn ein Objekt deaktiviert wird. Chart, ChartCollection, Shape, Worksheet, WorksheetCollection
onDeleted Tritt ein, wenn aus der Auflistung ein Objekt gelöscht wird. ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onFormatChanged Tritt ein, wenn das Format in einem Arbeitsblatt geändert wird. Worksheet, WorksheetCollection
onFormulaChanged Tritt auf, wenn eine Formel geändert wird. Worksheet, WorksheetCollection
onMoved Tritt auf, wenn ein Arbeitsblatt innerhalb einer Arbeitsmappe verschoben wird. WorksheetCollection
onNameChanged Tritt ein, wenn der Name des Arbeitsblatts geändert wird. Worksheet, WorksheetCollection
onProtectionChanged Tritt auf, wenn der Schutzstatus des Arbeitsblatts geändert wird. Worksheet, WorksheetCollection
onRowHiddenChanged Tritt auf, wenn der Status "Zeilen verborgen" in einem bestimmten Arbeitsblatt geändert wird. Worksheet, WorksheetCollection
onRowSorted Tritt auf, wenn eine oder mehrere Zeilen sortiert wurden. Dies geschieht, wenn Zeilen von oben nach unten sortiert werden. Worksheet, WorksheetCollection
onSelectionChanged Tritt ein, wenn die aktive Zelle oder der markierte Bereich geändert wird. Bindung, Tabelle, Arbeitsmappe, Arbeitsblatt, WorksheetCollection
onSettingsChanged Tritt ein, wenn die Einstellungen im Dokument geändert werden. SettingCollection
onSingleClicked Tritt auf, wenn im Arbeitsblatt mit der linken Maustaste geklickt/getippt wird. Worksheet, WorksheetCollection
onVisibilityChanged Tritt auf, wenn die Sichtbarkeit des Arbeitsblatts geändert wird. Worksheet, WorksheetCollection

Ereignisse in Vorschau

Hinweis

Die folgenden Ereignisse sind derzeit nur in der öffentlichen Vorschau verfügbar. Um dieses Feature verwenden zu können, müssen Sie die Vorschauversion der Office JavaScript-API-Bibliothek aus dem Office.js Content Delivery Network (CDN) verwenden. Die Typdefinitionsdatei für die TypeScript-Kompilierung und IntelliSense finden Sie unter CDN und DefinitelyTyped. Sie können diese Typen mit npm install --save-dev @types/office-js-preview installieren. Weitere Informationen zu unseren bevorstehenden APIs finden Sie unter JavaScript-API-Anforderungssätze für Excel.

Ereignis Beschreibung Unterstützte Objekte
onFiltered Tritt auf, wenn ein Filter auf ein Objekt angewendet wird. Table, TableCollection, Worksheet, WorksheetCollection

Ereignisauslöser

Ereignisse in einer Excel-Arbeitsmappe können ausgelöst werden durch:

  • Benutzerinteraktion über die Excel-Benutzeroberfläche (UI), die die Arbeitsmappe ändert
  • Office-Add-In-Code (JavaScript), der die Arbeitsmappe ändert
  • VBA-Add-In-Code (Makro), der die Arbeitsmappe ändert

Jede Änderung, die dem Standardverhalten von Excel entspricht, löst das/die entsprechende(n) Ereignis(se) in einer Arbeitsmappe aus.

Lebenszyklus eines Ereignishandlers

Ein Ereignishandler wird erstellt, wenn ein Add-In den Ereignishandler registriert. Er wird zerstört, wenn das Add-In die Registrierung des Ereignishandlers aufhebt oder wenn das Add-In aktualisiert, neu geladen oder geschlossen wird. Ereignishandler werden nicht im Rahmen der Excel-Datei oder über mehrere Sitzungen mit Excel im Web beibehalten.

Achtung

Wenn ein Objekt, in dem Ereignisse registriert werden, gelöscht wird (z. B. eine Tabelle mit einem registrierten onChanged-Ereignis), wird der Ereignishandler nicht mehr ausgelöst, er verbleibt jedoch im Arbeitsspeicher, bis das Add-In oder die Excel-Sitzung aktualisiert oder geschlossen wurde.

Ereignisse und gemeinsame Dokumentenerstellung

Bei gemeinsamer Dokumenterstellung können mehrere Personen zusammenarbeiten und dieselbe Excel-Arbeitsmappe gleichzeitig bearbeiten. Für Ereignisse, die von einem Mitautor ausgelöst werden können, z onChanged. B. , enthält das entsprechende Event-Objekt eine Quelleigenschaft , die angibt, ob das Ereignis vom aktuellen Benutzer (event.source = Local) lokal ausgelöst wurde oder vom Remote-Mitautorevent.source = Remote () ausgelöst wurde.

Registrieren eines Ereignishandlers

Das folgende Codebeispiel registriert einen Ereignishandler für das onChanged-Ereignis im Arbeitsblatt mit dem Namen Beispiel. Der Code gibt an, dass bei der Änderung von Daten in diesem Arbeitsblatt die handleChange-Funktion ausgeführt werden soll.

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

Behandeln eines Ereignisses

Wie im vorherigen Beispiel gezeigt, geben Sie bei der Registrierung eines Ereignishandlers die Funktion an, die ausgeführt werden soll, wenn das angegebene Ereignis eintritt. Sie können diese Funktion so anpassen, dass die für Ihr Szenario erforderlichen Aktionen ausgeführt werden. Das folgende Codebeispiel zeigt eine Ereignishandlerfunktion, die lediglich Informationen über das Ereignis in die Konsole schreibt.

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

Entfernen eines Ereignishandlers

Das folgende Codebeispiel registriert einen Ereignishandler für das onSelectionChanged-Ereignis im Arbeitsblatt mit dem Namen Beispiel und definiert die handleSelectionChange-Funktion, die ausgeführt wird, wenn das Ereignis auftritt. Darüber hinaus definiert es die remove()-Funktion, die anschließend aufgerufen werden kann, um den Ereignishandler zu entfernen. Beachten Sie, dass die RequestContext zum Erstellen des Ereignishandlers verwendete benötigt wird, um ihn zu entfernen.

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

Aktivieren und Deaktivieren von Ereignissen

Die Leistung eines Add-Ins kann durch Deaktivieren von Ereignissen verbessert werden. Beispielsweise muss Ihre App möglicherweise nie Ereignisse empfangen oder sie kann Ereignisse ignorieren, während Batch-Änderungen mehrerer Entitäten ausgeführt werden.

Ereignisse werden auf der runtime-Ebene aktiviert und deaktiviert. Die enableEvents-Eigenschaft bestimmt, ob Ereignisse ausgelöst und ihre Handler aktiviert werden.

Das folgende Codebeispiel zeigt, wie Ereignisse ein- und ausgeschaltet werden.

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

Siehe auch