Excel-Add-in mit Office.js entwickeln: Einstieg

Ein Excel-Add-in mit Office.js ist eine Webseite aus HTML, CSS und JavaScript oder TypeScript, die Excel in einer Seitenleiste oder hinter einer Schaltfläche im Menüband anzeigt. Über die Bibliothek Office.js liest und verändert sie Zellen, Tabellen, Diagramme und Arbeitsblätter. Den schnellsten Einstieg bietet der Yeoman-Generator yo office: Er legt ein lauffähiges Projekt an, das Sie mit einem Befehl in Excel laden.

Voraussetzungen

• Node.js in einer aktuellen LTS-Version mit npm.
• Excel, entweder als Desktop-Version unter Windows oder Mac oder Excel im Web mit einem Microsoft-Konto.
• Ein Code-Editor, etwa VS Code.
• Grundkenntnisse in JavaScript und asynchroner Programmierung mit async und await. Wer hier Lücken hat, findet sie in den Programmiergrundlagen.

Schritt 1: Projekt anlegen

npm install -g yo generator-office
yo office

Der Generator fragt nacheinander ab, was Sie bauen möchten. Für den Einstieg wählen Sie ein Projekt mit Aufgabenbereich (Task Pane), TypeScript oder JavaScript, einen Projektnamen und als Anwendung Excel. Danach liegen im Ordner unter anderem:

Je nach Generator-Version und Auswahl entsteht ein klassisches XML-Manifest oder das neuere einheitliche JSON-Manifest für Microsoft 365. Für Excel ist das XML-Manifest der bewährte Weg; welche Variante wo unterstützt wird, entwickelt sich noch weiter.

Schritt 2: Starten und Sideloading

cd mein-excel-add-in
npm start

Der Befehl baut das Projekt, startet einen Entwicklungsserver unter https://localhost:3000 und installiert beim ersten Mal ein lokales Entwicklungszertifikat, damit Excel der Adresse vertraut. Unter Windows öffnet sich Excel anschließend mit geladenem Add-in. Dieses Laden ohne Store heißt Sideloading.

In Excel im Web laden Sie das Add-in von Hand: Über den Bereich für Add-ins im Menüband wählen Sie die Option zum Hochladen und geben die Manifestdatei an. Der Entwicklungsserver muss dabei weiterlaufen. Beendet wird die Sitzung mit npm stop.

Schritt 3: Der Code im Aufgabenbereich

Jedes Add-in wartet zuerst, bis Office bereit ist. Danach verbinden Sie Schaltflächen mit Funktionen:

Office.onReady((info) => {
  if (info.host === Office.HostType.Excel) {
    document.getElementById("markieren")!.onclick = negativeMarkieren;
  }
});

async function negativeMarkieren() {
  try {
    await Excel.run(async (context) => {
      const bereich = context.workbook.getSelectedRange();
      bereich.load(["values", "rowCount", "columnCount"]);
      await context.sync();

      for (let z = 0; z < bereich.rowCount; z++) {
        for (let s = 0; s < bereich.columnCount; s++) {
          const wert = bereich.values[z][s];
          if (typeof wert === "number" && wert < 0) {
            bereich.getCell(z, s).format.font.color = "#B42318";
          }
        }
      }
      await context.sync();
    });
  } catch (fehler) {
    console.error(fehler);
  }
}

Das Prinzip von load und sync

Office.js arbeitet mit Stellvertreter-Objekten (Proxys). getSelectedRange() liefert nicht sofort die Daten, sondern ein Objekt, das auf den Bereich zeigt. Befehle wie das Setzen einer Farbe werden zunächst gesammelt. Erst context.sync() überträgt sie gebündelt an Excel und holt angeforderte Werte zurück.

Daraus folgen drei Regeln:

1. Vor dem Lesen laden: Eigenschaften wie values müssen per load() angefordert und per sync() geholt werden. Wer sie vorher liest, erhält einen Fehler.
2. Wenig synchronisieren: Jeder sync()-Aufruf ist ein Umlauf zwischen Add-in und Excel. Ein sync() innerhalb einer Schleife über tausend Zeilen macht das Add-in spürbar langsam. Sammeln Sie Änderungen und synchronisieren Sie einmal.
3. Große Bereiche am Stück schreiben: Statt Zelle für Zelle zu setzen, schreiben Sie ein zweidimensionales Array auf einmal in range.values.

await Excel.run(async (context) => {
  const blatt = context.workbook.worksheets.getActiveWorksheet();
  const daten = [
    ["Monat", "Umsatz"],
    ["Januar", 1200],
    ["Februar", 1350],
  ];
  const ziel = blatt.getRange("A1:B3");
  ziel.values = daten;
  blatt.tables.add("A1:B3", true).name = "Umsaetze";
  await context.sync();
});

Eigene Formeln: benutzerdefinierte Funktionen

Excel-Add-ins können eigene Funktionen bereitstellen, die wie eingebaute Formeln in Zellen stehen. Wählen Sie dafür beim Generator den passenden Projekttyp. Die Funktionen werden in JavaScript oder TypeScript geschrieben und über einen JSDoc-Kommentar gekennzeichnet:

/**
 * Rechnet einen Nettobetrag in einen Bruttobetrag um.
 * @customfunction
 * @param netto Nettobetrag
 * @param satz Steuersatz als Dezimalzahl, z. B. 0.19
 * @returns Bruttobetrag
 */
export function brutto(netto: number, satz: number): number {
  return netto * (1 + satz);
}

Beim Build entsteht daraus automatisch eine Metadatendatei. In der Zelle rufen Sie die Funktion mit einem Namensraum auf, den das Manifest festlegt, etwa =BEISPIEL.BRUTTO(100;0,19). Funktionen können auch asynchron sein und Werte aus dem Netz laden; Excel zeigt bis zum Ergebnis einen Platzhalter an.

Unterstützung prüfen: Requirement Sets

Nicht jede Excel-Version kennt jede Funktion von Office.js. Microsoft gruppiert die Schnittstellen deshalb in nummerierte Requirement Sets wie ExcelApi 1.x. Im Manifest legen Sie fest, welche Mindestversion Ihr Add-in braucht. Im Code prüfen Sie optionale Funktionen zur Laufzeit:

if (Office.context.requirements.isSetSupported("ExcelApi", "1.9")) {
  // neuere Funktion nutzen
} else {
  // einfachere Alternative anbieten
}

So bleibt Ihr Add-in auch in älteren Installationen nutzbar, statt mit einem Fehler abzubrechen.

Auf Änderungen reagieren und Einstellungen speichern

Ein Add-in kann nicht nur auf Klicks reagieren, sondern auch auf Ereignisse in der Arbeitsmappe. So lässt sich etwa eine Prüfung starten, sobald jemand Werte in einem Blatt ändert:

await Excel.run(async (context) => {
  const blatt = context.workbook.worksheets.getActiveWorksheet();
  blatt.onChanged.add(async (ereignis) => {
    console.log("Geändert:", ereignis.address);
  });
  await context.sync();
});

Ereignis-Handler sollten wenig Arbeit verrichten und keine neuen Änderungen auslösen, die wiederum dasselbe Ereignis feuern. Sonst entsteht eine Schleife, die Excel spürbar ausbremst.

Für Einstellungen gibt es zwei übliche Orte. Was zu einer bestimmten Datei gehört, etwa eine gewählte Spalte, speichern Sie in den Dokumenteinstellungen des Add-ins, die mit der Arbeitsmappe gespeichert werden. Was zur Person gehört, etwa eine bevorzugte Sprache, kann im Speicher des Browsers liegen. Zugangsdaten gehören an keinen der beiden Orte, sondern hinter eine Anmeldung.

Debuggen und testen

• Entwicklerwerkzeuge: Unter Windows läuft der Aufgabenbereich in einer eingebetteten Edge-Engine. Über das Kontextmenü des Aufgabenbereichs oder ein separates Werkzeug öffnen Sie die gewohnten Browser-Entwicklerwerkzeuge. In Excel im Web nutzen Sie einfach die Entwicklerwerkzeuge Ihres Browsers.
• Manifest prüfen: npm run validate prüft das Manifest auf formale Fehler. Viele Probleme beim Laden gehen auf ein fehlerhaftes Manifest zurück.
• Ausprobieren ohne Projekt: Microsofts Add-in Script Lab erlaubt es, Office.js-Schnipsel direkt in Excel zu testen, bevor Sie sie in Ihr Projekt übernehmen.
• Auf mehreren Plattformen testen: Mindestens Excel für Windows und Excel im Web, wenn möglich auch Mac. Layout und verfügbare Requirement Sets können sich unterscheiden.

Häufige Fehler

• Zertifikatsfehler: Wird das Entwicklungszertifikat nicht akzeptiert, bleibt der Aufgabenbereich leer. Das Paket office-addin-dev-certs kann Zertifikate neu installieren.
• Zwischengespeicherte Versionen: Office speichert Add-in-Dateien zwischen. Ändert sich nach einem Build nichts, hilft das Leeren des Office-Caches.
• Fehlendes await context.sync(): Änderungen erscheinen nicht, weil sie nie übertragen wurden.
• Zu viele Synchronisierungen: führen zu trägen Add-ins, besonders in Excel im Web.

Verteilen

Für den Einsatz im eigenen Unternehmen genügt die zentrale Bereitstellung durch die Microsoft-365-Administration: Das Manifest wird hochgeladen, die Dateien liegen auf einem beliebigen HTTPS-Webspace. Für eine öffentliche Verbreitung reichen Sie das Add-in über das Partner Center bei Microsofts Marktplatz ein, wo es eine Prüfung durchläuft. Allgemeine Hinweise zu Stores, Prüfungen und Beschreibungstexten finden Sie im Bereich Add-ons veröffentlichen.

Wer statt Excel mit Google Sheets arbeitet, folgt einem ähnlichen Muster mit anderer Technik: Google Apps Script: eigenes Add-on für Google Sheets bauen.