Fehlerbehandlung mit den anwendungsspezifischen JavaScript-APIs

Wenn Sie ein Add-In mit den anwendungsspezifischen Office JavaScript-APIs erstellen, müssen Sie eine Fehlerbehandlungslogik einschließen, um Laufzeitfehler zu berücksichtigen. Dies ist aufgrund der asynchronen Natur der APIs von entscheidender Bedeutung.

Bewährte Methoden

In unseren Codebeispielen und Script Lab-Codeausschnitten werden Sie feststellen, dass jeder Aufruf von Excel.run, PowerPoint.runoder Word.run von einer catch Anweisung begleitet wird, um Fehler abzufangen. Es wird empfohlen, beim Erstellen eines Add-Ins mithilfe der anwendungsspezifischen APIs dasselbe Muster zu verwenden.

$("#run").on("click", () => tryCatch(run));

async function run() {
  await Excel.run(async (context) => {
      // Add your Excel JavaScript API calls here.

      // Await the completion of context.sync() before continuing.
    await context.sync();
    console.log("Finished!");
  });
}

/** Default helper for invoking an action and handling errors. */
async function tryCatch(callback) {
  try {
    await callback();
  } catch (error) {
    // Note: In a production add-in, you'd want to notify the user through your add-in's UI.
    console.error(error);
  }
}

API-Fehler

Wenn eine Office JavaScript-API-Anforderung nicht erfolgreich ausgeführt wird, gibt die API ein Fehlerobjekt zurück, das die folgenden Eigenschaften enthält.

  • Code: Die code Eigenschaft einer Fehlermeldung enthält eine Zeichenfolge, die Teil von OfficeExtension.ErrorCodes oder {application}.ErrorCodes wo {application} für Excel, PowerPoint oder Word steht. Der Fehlercode "InvalidReference" gibt z. B. an, dass der Verweis für den angegebenen Vorgang ungültig ist. Die Fehlercodes sind nicht lokalisiert.

  • message: Die message-Eigenschaft einer Fehlermeldung enthält eine Zusammenfassung des Fehlers in der lokalisierten Zeichenfolge. Die Fehlermeldung ist nicht für Endbenutzer bestimmt. Sie sollten den Fehlercode und die entsprechende Geschäftslogik verwenden, um die Fehlermeldung zu ermitteln, die Ihr Add-In Endbenutzern anzeigt.

  • debugInfo: Sofern vorhanden, bietet die debugInfo-Eigenschaft der Fehlermeldung zusätzliche Informationen, die Sie verwenden können, um die Ursache des Fehlers zu verstehen.

Hinweis

Wenn Sie Fehlermeldungen an die Konsole ausgeben console.log() , sind diese Meldungen nur auf dem Server sichtbar. Endbenutzern werden diese Fehlermeldungen weder im Aufgabenbereich des Add-Ins noch irgendwo in der Office-Anwendung angezeigt. Informationen zum Melden von Fehlern an den Benutzer finden Sie unter Fehlerbenachrichtigungen.

Fehlercodes und -meldungen

In den folgenden Tabellen sind die Fehler aufgeführt, die anwendungsspezifische APIs zurückgeben können.

Hinweis

In den folgenden Tabellen sind Fehlermeldungen aufgeführt, die bei der Verwendung der anwendungsspezifischen APIs auftreten können. Wenn Sie mit der allgemeinen API arbeiten, finden Sie unter Allgemeine API-Fehlercodes für Office weitere Informationen zu relevanten Fehlermeldungen.

Fehlercode Fehlermeldung Hinweise
AccessDenied Sie können den angeforderten Vorgang nicht durchzuführen. Dies kann dadurch verursacht werden, dass die Antivirensoftware eines Benutzers Teile von Office blockiert. Weitere Informationen finden Sie in den Abschnitten Häufige Fehler und Schritte zur Problembehandlung für "Fehler: Zugriff verweigert".
ActivityLimitReached Der Aktivitätsgrenzwert wurde erreicht. Keine
ApiNotAvailable Die angeforderte API ist nicht verfügbar. Keine
ApiNotFound Die API, die Sie verwenden möchten, wurde nicht gefunden. Sie ist möglicherweise in einer neueren Version der Office-Anwendung verfügbar. Weitere Informationen finden Sie unter Verfügbarkeit von Office-Clientanwendungen und -plattformen für Office-Add-Ins . Keine
BadPassword Das von Ihnen angegebene Kennwort ist falsch. Keine
Conflict Anforderung konnte aufgrund eines Konflikts nicht verarbeitet werden. Keine
ContentLengthRequired Ein Content-length HTTP-Header fehlt. Keine
GeneralException Beim Verarbeiten der Anforderung ist ein interner Fehler aufgetreten. Keine
HostRestartNeeded Die Office-Anwendung muss neu gestartet werden. Dieser Fehler wird von der Office.ribbon.requestUpdate()- Methode ausgelöst, wenn das Add-In, das die Methode aufruft, seit dem Start der Office-Anwendung aktualisiert wurde.
InsertDeleteConflict Der Einfüge- oder Löschvorgang führte zu einem Konflikt. Keine
InvalidArgument Das Argument ist ungültig oder fehlt oder weist ein falsches Format auf. Keine
InvalidBinding Die Objektbindung ist aufgrund von früheren Updates nicht mehr gültig. Keine
InvalidOperation Dieser Vorgang ist für das Objekt ungültig. Keine
InvalidReference Dieser Verweis ist für den aktuellen Vorgang nicht gültig. Keine
InvalidRequest Die Anforderung kann nicht verarbeitet werden. Keine
InvalidRibbonDefinition Office wurde eine ungültige Menübanddefinition zugewiesen. Dieser Fehler wird ausgelöst, wenn ein ungültiges RibbonUpdateObject an die Office.ribbon.requestUpdate()- Methode übergeben wird.
InvalidSelection Die aktuelle Auswahl ist für diesen Vorgang nicht gültig. Keine
ItemAlreadyExists Die erstellte Ressource ist bereits vorhanden. Keine
ItemNotFound Die angeforderte Ressource ist nicht vorhanden. Keine
MemoryLimitReached Das Speicherlimit wurde erreicht. Ihre Aktion konnte nicht abgeschlossen werden. Keine
NotImplemented Das angeforderte Feature ist nicht implementiert. Dies kann bedeuten, dass sich die API in der Vorschau befindet oder nur auf einer bestimmten Plattform unterstützt wird (z. B. nur online verfügbar). Weitere Informationen finden Sie unter Verfügbarkeit von Office-Clientanwendungen und -plattformen für Office-Add-Ins .
RequestAborted Die Anforderung wurde während der Laufzeit abgebrochen. Keine
RequestPayloadSizeLimitExceeded Die Größe der Anforderungsnutzlast hat das Limit überschritten. Weitere Informationen finden Sie im Artikel Ressourcenlimits und Leistungsoptimierung für Office-Add-Ins . Dieser Fehler tritt nur in Office im Web auf.
ResponsePayloadSizeLimitExceeded Die Größe der Antwortnutzlast hat das Limit überschritten. Weitere Informationen finden Sie im Artikel Ressourcenlimits und Leistungsoptimierung für Office-Add-Ins . Dieser Fehler tritt nur in Office im Web auf.
ServiceNotAvailable Der Dienst ist nicht verfügbar. Keine
Unauthenticated Erforderliche Authentifizierungsinformationen fehlen oder sind ungültig. Keine
UnsupportedFeature Der Vorgang ist fehlgeschlagen, da das Quellarbeitsblatt ein oder mehrere nicht unterstützte Features enthält. Keine
UnsupportedOperation Dieser Vorgang wird nicht unterstützt. Keine

Excel-spezifische Fehlercodes und -meldungen

Fehlercode Fehlermeldung Hinweise
EmptyChartSeries Der versuchte Vorgang ist fehlgeschlagen, da die Diagrammreihe leer ist. Keine
FilteredRangeConflict Der versuchte Vorgang verursacht einen Konflikt mit einem gefilterten Bereich. Keine
FormulaLengthExceedsLimit Der Bytecode der angewendeten Formel überschreitet die maximale Länge. Für Office auf 32-Bit-Computern beträgt die Bytecodelängenbeschränkung 16384 Zeichen. Auf 64-Bit-Computern beträgt die Bytecodelängenbeschränkung 32768 Zeichen. Dieser Fehler tritt sowohl in Excel im Web als auch auf dem Desktop auf.
GeneralException Verschiedenes. Die Datentypen-APIs geben Fehler mit dynamischen Fehlermeldungen zurück GeneralException . Diese Meldungen verweisen auf die Zelle, die die Fehlerquelle ist, und auf das Problem, das den Fehler verursacht, wie etwa: "Zelle A1 fehlt die erforderliche Eigenschaft type."
InactiveWorkbook Der Vorgang ist fehlgeschlagen, da mehrere Arbeitsmappen geöffnet sind und die Arbeitsmappe, die von dieser API aufgerufen wird, den Fokus verloren hat. Keine
InvalidOperationInCellEditMode Der Vorgang ist nicht verfügbar, während Excel sich im Modus "Zelle bearbeiten" befindet. Beenden Sie den Bearbeitungsmodus, indem Sie die Eingabetaste oder die Tabulatortaste verwenden oder eine andere Zelle auswählen, und versuchen Sie es dann erneut. Keine
MergedRangeConflict Der Vorgang kann nicht abgeschlossen werden. Eine Tabelle darf sich nicht mit einer anderen Tabelle, einem PivotTable-Bericht, Abfrageergebnissen, verbundenen Zellen oder einer XML-Zuordnung überlappen. Keine
NonBlankCellOffSheet Microsoft Excel kann keine neuen Zellen einfügen, da nicht leere Zellen am Ende des Arbeitsblatts verschoben würden. Diese nicht leeren Zellen werden möglicherweise leer angezeigt, weisen aber leere Werte, eine Formatierung oder eine Formel auf. Löschen Sie genügend Zeilen oder Spalten, um Platz für das einzufügende Element zu schaffen, und versuchen Sie es dann erneut. Keine
OperationCellsExceedLimit Der versuchte Vorgang betrifft mehr als das Limit von 33554000 Zellen. Wenn dieser TableColumnCollection.add API Fehler dadurch ausgelöst wird, vergewissern Sie sich, dass sich keine unbeabsichtigten Daten innerhalb des Arbeitsblatts, sondern außerhalb der Tabelle befinden. Suchen Sie insbesondere in den Spalten ganz rechts des Arbeitsblatts nach Daten. Entfernen Sie die unbeabsichtigten Daten, um diesen Fehler zu beheben. Eine Möglichkeit, um zu überprüfen, wie viele Zellen ein Vorgang verarbeitet, besteht darin, die folgende Berechnung auszuführen: (number of table rows) x (16383 - (number of table columns)). Die Zahl 16383 ist die maximale Anzahl von Spalten, die Excel unterstützt.

Dieser Fehler tritt nur in Excel im Web auf.
PivotTableRangeConflict Der versuchte Vorgang verursacht einen Konflikt mit einem PivotTable-Bereich. Keine
RangeExceedsLimit Die Zellanzahl in dem Bereich hat die maximal unterstützte Anzahl überschritten. Weitere Informationen finden Sie im Artikel Ressourcenlimits und Leistungsoptimierung für Office-Add-Ins . Keine
RefreshWorkbookLinksBlocked Der Vorgang ist fehlgeschlagen, da der Benutzer keine Berechtigung zum Aktualisieren externer Arbeitsmappenverknüpfungen erteilt hat. Keine
UndoNotSupported Fehler bei der JavaScript-API-Anforderung aufgrund fehlender Unterstützung für den Rückgängig-Vorgang. Keine
UnsupportedSheet Dieser Arbeitsblatttyp unterstützt diesen Vorgang nicht, da es sich um ein Makro- oder Diagrammblatt handelt. Keine

Word-spezifische Fehlercodes und -meldungen

Fehlercode Fehlermeldung Hinweise
SearchDialogIsOpen Der Suchdialog ist geöffnet. Keine
SearchStringInvalidOrTooLong Der Suchstring ist ungültig oder zu lang. Die maximale Länge der Suchzeichenfolge beträgt 255 Zeichen.

Fehlerbenachrichtigungen

Wie Sie Fehler an Benutzer melden, hängt vom verwendeten Benutzeroberflächensystem ab.

  • Wenn Sie React als UI-System verwenden, verwenden Sie die Fluent UI-Komponenten und Designelemente. Wir empfehlen, Fehlermeldungen mit einer Dialogkomponente zu übermitteln. Wenn der Fehler in der Eingabe des Benutzers liegt, konfigurieren Sie die Eingabekomponente so, dass der Fehler als fett formatierter roter Text angezeigt wird.

    Hinweis

    Die Warnungskomponente kann auch zum Melden von Fehlern an Benutzer verwendet werden, aber sie befindet sich derzeit in der Vorschauphase und sollte nicht in einem Produktions-Add-In verwendet werden. Informationen zum Veröffentlichungsstatus finden Sie in der Fluent UI React v9 Komponenten-Roadmap.

  • Wenn Sie React nicht für die Benutzeroberfläche verwenden, sollten Sie die älteren Fabric-UI-Komponenten verwenden, die direkt in HTML und JavaScript implementiert sind.

Siehe auch

  • Zuletzt aktualisiert um