Fehlerbehandlung mit den anwendungsspezifischen JavaScript-APIs

  • Artikel

Wenn Sie ein Add-In mit den anwendungsspezifischen Office JavaScript-APIs erstellen, müssen Sie 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 zum Abfangen von Fehlern begleitet wird. Es wird empfohlen, dasselbe Muster zu verwenden, wenn Sie ein Add-In mithilfe der anwendungsspezifischen APIs erstellen.

$("#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 ist, wobei {application} Excel, PowerPoint oder Word darstellt. 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 die Nutzung durch Endbenutzer vorgesehen. Sie sollten den Fehlercode und die entsprechende Geschäftslogik verwenden, um die Fehlermeldung zu ermitteln, die Ihr Add-In den 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 zum Ausgeben von Fehlermeldungen in der Konsole verwenden console.log() , sind diese Meldungen nur auf dem Server sichtbar. Endbenutzern werden diese Fehlermeldungen nicht im Add-In-Aufgabenbereich oder an einer beliebigen Stelle 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 möglicherweise zurückgeben.

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 informationen zu relevanten Fehlermeldungen unter Allgemeine Office-API-Fehlercodes .

Fehlercode Fehlermeldung Anmerkungen
AccessDenied Sie können den angeforderten Vorgang nicht durchzuführen. Nichts.
ActivityLimitReached Der Aktivitätsgrenzwert wurde erreicht. Nichts.
ApiNotAvailable Die angeforderte API ist nicht verfügbar. Nichts.
ApiNotFound Die API, die Sie verwenden möchten, wurde nicht gefunden. Es kann in einer neueren Version der Office-Anwendung verfügbar sein. Weitere Informationen finden Sie unter Office-Clientanwendung und Plattformverfügbarkeit für Office-Add-Ins . Nichts.
BadPassword Das von Ihnen angegebene Kennwort ist falsch. Nichts.
Conflict Anforderung konnte aufgrund eines Konflikts nicht verarbeitet werden. Nichts.
ContentLengthRequired Ein Content-length HTTP-Header fehlt. Nichts.
GeneralException Beim Verarbeiten der Anforderung ist ein interner Fehler aufgetreten. Nichts.
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. Nichts.
InvalidArgument Das Argument ist ungültig oder fehlt oder weist ein falsches Format auf. Nichts.
InvalidBinding Die Objektbindung ist aufgrund von früheren Updates nicht mehr gültig. Nichts.
InvalidOperation Dieser Vorgang ist für das Objekt ungültig. Nichts.
InvalidReference Dieser Verweis ist für den aktuellen Vorgang nicht gültig. Nichts.
InvalidRequest Die Anforderung kann nicht verarbeitet werden. Nichts.
InvalidRibbonDefinition Office hat eine ungültige Menübanddefinition erhalten. 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. Nichts.
ItemAlreadyExists Die erstellte Ressource ist bereits vorhanden. Nichts.
ItemNotFound Die angeforderte Ressource ist nicht vorhanden. Nichts.
MemoryLimitReached Das Arbeitsspeicherlimit wurde erreicht. Ihre Aktion konnte nicht abgeschlossen werden. Nichts.
NotImplemented Das angeforderte Feature ist nicht implementiert. Dies kann bedeuten, dass sich die API in der Vorschau befindet oder nur auf einer bestimmten Plattform (z. B. nur online) unterstützt wird. Weitere Informationen finden Sie unter Office-Clientanwendung und Plattformverfügbarkeit für Office-Add-Ins .
RequestAborted Die Anforderung wurde während der Laufzeit abgebrochen. Nichts.
RequestPayloadSizeLimitExceeded Die Größe der Anforderungsnutzlast hat den Grenzwert ü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 den Grenzwert ü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. Nichts.
Unauthenticated Erforderliche Authentifizierungsinformationen fehlen oder sind ungültig. Nichts.
UnsupportedFeature Fehler beim Vorgang, da das Quellarbeitsblatt mindestens ein nicht unterstütztes Feature enthält. Nichts.
UnsupportedOperation Dieser Vorgang wird nicht unterstützt. Nichts.

Excel-spezifische Fehlercodes und -meldungen

Fehlercode Fehlermeldung Anmerkungen
EmptyChartSeries Bei dem versuchten Vorgang ist ein Fehler aufgetreten, da die Diagrammreihe leer ist. Nichts.
FilteredRangeConflict Der versuchte Vorgang verursacht einen Konflikt mit einem gefilterten Bereich. Nichts.
FormulaLengthExceedsLimit Der Bytecode der angewendeten Formel überschreitet die maximale Längengrenze. 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 Verschiedenen. Die Datentyp-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, z. B.: "Zelle A1 fehlt die erforderliche Eigenschaft type."
InactiveWorkbook Der Vorgang ist fehlgeschlagen, weil mehrere Arbeitsmappen geöffnet sind und die von dieser API aufgerufene Arbeitsmappe den Fokus verloren hat. Nichts.
InvalidOperationInCellEditMode Der Vorgang ist nicht verfügbar, während Excel sich im Zellenbearbeitungsmodus befindet. Beenden Sie den Bearbeitungsmodus, indem Sie die EINGABETASTE oder TAB-TASTE verwenden oder eine andere Zelle auswählen, und versuchen Sie es dann erneut. Nichts.
MergedRangeConflict Der Vorgang kann nicht abgeschlossen werden. Eine Tabelle darf sich nicht mit einer anderen Tabelle, einem PivotTable-Bericht, Abfrageergebnissen, zusammengeführten Zellen oder einer XML-Zuordnung überschneiden. Nichts.
NonBlankCellOffSheet Microsoft Excel kann keine neuen Zellen einfügen, da es nicht leere Zellen vom Ende des Arbeitsblatts verschiebt. Diese nicht leeren Zellen werden möglicherweise leer angezeigt, weisen jedoch leere Werte, eine formatierung oder eine Formel auf. Löschen Sie genügend Zeilen oder Spalten, um Platz für das zu schaffen, was Sie einfügen möchten, und versuchen Sie es dann erneut. Nichts.
OperationCellsExceedLimit Der versuchte Vorgang betrifft mehr als den Grenzwert von 33554000 Zellen. Wenn dieser TableColumnCollection.add API Fehler ausgelöst wird, vergewissern Sie sich, dass keine unbeabsichtigten Daten innerhalb des Arbeitsblatts, aber außerhalb der Tabelle vorhanden sind. Überprüfen Sie insbesondere, ob Daten in den Spalten ganz rechts des Arbeitsblatts enthalten sind. Entfernen Sie die unbeabsichtigten Daten, um diesen Fehler zu beheben. Eine Möglichkeit zum Überprüfen der Anzahl von Zellen, die 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. Nichts.
RangeExceedsLimit Die Zellanzahl im Bereich hat die maximal unterstützte Anzahl überschritten. Weitere Informationen finden Sie im Artikel Ressourcenlimits und Leistungsoptimierung für Office-Add-Ins . Nichts.
RefreshWorkbookLinksBlocked Fehler beim Vorgang, weil der Benutzer keine Berechtigung zum Aktualisieren externer Arbeitsmappenlinks erteilt hat. Nichts.
UnsupportedSheet Dieser Blatttyp unterstützt diesen Vorgang nicht, da es sich um ein Makro- oder Diagrammblatt handelt. Nichts.

Word-spezifische Fehlercodes und -meldungen

Fehlercode Fehlermeldung Anmerkungen
SearchDialogIsOpen Das Suchdialogfeld ist geöffnet. Nichts.
SearchStringInvalidOrTooLong Die Suchzeichenfolge ist ungültig oder zu lang. Die maximale Suchzeichenfolge beträgt 255 Zeichen.

Fehlerbenachrichtigungen

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

Siehe auch