Arbeiten mit Ereignissen mithilfe der Excel-JavaScript-API

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.

Ereignisse in Vorschau

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 die entsprechenden Ereignisse 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.

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

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

• JavaScript-Objektmodell für Excel in Office-Add-Ins