Gestion des erreurs avec les API JavaScript spécifiques à l’application

Lorsque vous créez un complément à l’aide des API JavaScript Office spécifiques à l’application, veillez à inclure une logique de gestion des erreurs pour prendre en compte les erreurs d’exécution. Cela est essentiel, en raison de la nature asynchrone des API.

Meilleures pratiques

Dans nos exemples de code et nos extraits de code Script Lab, vous remarquerez que chaque appel à Excel.run, PowerPoint.runou Word.run est accompagné d’une catch instruction pour intercepter les erreurs. Nous vous recommandons d’utiliser le même modèle lorsque vous créez un complément à l’aide des API spécifiques à l’application.

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

Erreurs API

Lorsqu’une demande d’API JavaScript Office ne s’exécute pas correctement, l’API renvoie un objet d’erreur contenant les propriétés suivantes.

  • code : la code propriété d’un message d’erreur contient une chaîne qui fait partie de OfficeExtension.ErrorCodes ou {application}.ErrorCodes où {application} représente Excel, PowerPoint ou Word. Par exemple, le code d’erreur « InvalidReference » indique que la référence n’est pas valide pour l’opération spécifiée. Les codes d’erreur ne sont pas traduits.

  • message : la propriété message d’un message d’erreur contient un résumé de l’erreur dans la chaîne localisée. Le message d’erreur n’est pas destiné à être consommé par les utilisateurs finaux ; Vous devez utiliser le code d’erreur et la logique métier appropriée pour déterminer le message d’erreur que votre complément affiche aux utilisateurs finaux.

  • debugInfo : le cas échéant, la propriété debugInfo du message d’erreur fournit des informations supplémentaires que vous pouvez utiliser pour comprendre la cause principale de l’erreur.

Remarque

Si vous avez l’habitude console.log() d’imprimer des messages d’erreur sur la console, ces messages ne sont visibles que sur le serveur. Les utilisateurs finaux ne voient pas ces messages d’erreur dans le volet Office du complément ou n’importe où dans l’application Office. Pour signaler des erreurs à l’utilisateur, consultez Notifications d’erreur.

Codes et messages d’erreur

Les tableaux suivants répertorient les erreurs que les API spécifiques à l’application peuvent renvoyer.

Remarque

Les tableaux suivants répertorient les messages d’erreur que vous pouvez rencontrer lors de l’utilisation des API spécifiques à l’application. Si vous utilisez l’API commune, consultez Codes d’erreur de l’API commune Office pour en savoir plus sur les messages d’erreur pertinents.

Code d’erreur Message d’erreur Notes
AccessDenied Vous ne pouvez pas effectuer l’opération demandée. Cela peut être dû au fait que l’antivirus d’un utilisateur bloque certaines parties d’Office. Pour plus d’informations, consultez Erreurs courantes et étapes de dépannage pour « Erreur : accès refusé ».
ActivityLimitReached La limite d’activité a été atteinte. Aucune
ApiNotAvailable L’API demandée n’est pas disponible. Aucune
ApiNotFound L’API que vous essayez d’utiliser est introuvable. Il est possible qu’il soit disponible dans une version plus récente de l’application Office. Pour plus d’informations, voir Disponibilité de l’application cliente Office et de la plateforme pour les compléments Office . Aucune
BadPassword Le mot de passe que vous avez fourni est incorrect. Aucune
Conflict La demande n’a pas pu être traitée en raison d’un conflit. Aucune
ContentLengthRequired Un Content-length en-tête HTTP est manquant. Aucune
GeneralException Une erreur interne s’est produite lors du traitement de la demande. Aucune
HostRestartNeeded L’application Office doit être redémarrée. Cette erreur est générée par la méthode Office.ribbon.requestUpdate() si le complément qui appelle la méthode a été mis à jour depuis le démarrage de l’application Office.
InsertDeleteConflict L’opération d’insertion ou de suppression tentée a créé un conflit. Aucune
InvalidArgument L’argument est manquant ou non valide, ou a un format incorrect. Aucune
InvalidBinding Cette liaison d’objets n’est plus valide en raison de mises à jour précédentes. Aucune
InvalidOperation L’opération tentée n’est pas valide sur l’objet. Aucune
InvalidReference Cette référence n’est pas valide pour l’opération en cours. Aucune
InvalidRequest Impossible de traiter la demande. Aucune
InvalidRibbonDefinition Office a reçu une définition de ruban non valide. Cette erreur est générée si un RibbonUpdateObject non valide est transmis à la méthode Office.ribbon.requestUpdate().
InvalidSelection La sélection en cours est incorrecte pour cette action. Aucune
ItemAlreadyExists La ressource en cours de création existe déjà. Aucune
ItemNotFound La ressource demandée n’existe pas. Aucune
MemoryLimitReached La limite de mémoire a été atteinte. Votre action n’a pas pu aboutir. Aucune
NotImplemented La fonctionnalité demandée n’est pas implémentée Cela peut signifier que l’API est en préversion ou qu’elle est uniquement prise en charge sur une plateforme particulière (par exemple, en ligne uniquement). Pour plus d’informations, voir Disponibilité de l’application cliente Office et de la plateforme pour les compléments Office .
RequestAborted La demande a été interrompue pendant l’exécution. Aucune
RequestPayloadSizeLimitExceeded La taille de la charge utile de la requête a dépassé la limite. Pour plus d’informations, consultez l’article Limites de ressources et optimisation des performances pour les compléments Office . Cette erreur se produit uniquement dans Office sur le Web.
ResponsePayloadSizeLimitExceeded La taille de la charge utile de réponse a dépassé la limite. Pour plus d’informations, consultez l’article Limites de ressources et optimisation des performances pour les compléments Office . Cette erreur se produit uniquement dans Office sur le Web.
ServiceNotAvailable Le service n’est pas disponible. Aucune
Unauthenticated Les informations d’authentification requises sont manquantes ou incorrectes. Aucune
UnsupportedFeature L’opération a échoué car la feuille de calcul source contient une ou plusieurs fonctionnalités non prises en charge. Aucune
UnsupportedOperation L’opération tentée n’est pas prise en charge. Aucune

Codes d’erreur et messages spécifiques à Excel

Code d’erreur Message d’erreur Notes
EmptyChartSeries Échec de l’opération tentée car la série de graphiques est vide. Aucune
FilteredRangeConflict L’opération tentée provoque un conflit avec une plage filtrée. Aucune
FormulaLengthExceedsLimit Le bytecode de la formule appliquée dépasse la limite de longueur maximale. Pour Office sur des machines 32 bits, la longueur maximale du bytecode est de 16 384 caractères. Sur les machines 64 bits, la longueur maximale du bytecode est de 32 768 caractères. Cette erreur se produit à la fois dans Excel sur le Web et sur le bureau.
GeneralException Divers. Les API des types de données renvoient GeneralException des erreurs avec des messages d’erreur dynamiques. Ces messages font référence à la cellule qui est la source de l’erreur et au problème à l’origine de l’erreur, par exemple : « Il manque la propriété typerequise dans la cellule A1 ».
InactiveWorkbook L’opération a échoué car plusieurs classeurs sont ouverts et le classeur appelé par cette API a perdu le focus. Aucune
InvalidOperationInCellEditMode L’opération n’est pas disponible lorsqu’Excel est en mode Modifier la cellule. Quittez le mode Édition à l’aide des touches Entrée ou Tab , ou en sélectionnant une autre cellule, puis réessayez. Aucune
MergedRangeConflict Impossible de terminer l’opération. Un tableau ne peut pas se chevaucher avec un autre tableau, un rapport de tableau croisé dynamique, des résultats de requête, des cellules fusionnées ou une carte XML. Aucune
NonBlankCellOffSheet Microsoft Excel ne peut pas insérer de nouvelles cellules, car les cellules non vides seraient repoussées à la fin de la feuille de calcul. Ces cellules non vides peuvent sembler vides, mais comportent des valeurs vides, une mise en forme ou une formule. Supprimez suffisamment de lignes ou de colonnes pour faire de la place pour ce que vous souhaitez insérer, puis réessayez. Aucune
OperationCellsExceedLimit L’opération tentée affecte plus que la limite de 33554000 cellules. Si le déclenche cette erreur, confirmez qu’il TableColumnCollection.add API n’y a pas de données involontaires dans la feuille de calcul, mais en dehors de la table. En particulier, case activée pour les données dans les colonnes les plus à droite de la feuille de calcul. Supprimez les données non souhaitées pour résoudre cette erreur. Une façon de vérifier le nombre de cellules traitées par une opération consiste à exécuter le calcul suivant : (number of table rows) x (16383 - (number of table columns)). Le nombre 16383 est le nombre maximal de colonnes qu’Excel prend en charge.

Cette erreur se produit uniquement dans Excel sur le Web.
PivotTableRangeConflict L’opération tentée provoque un conflit avec une plage de tableau croisé dynamique. Aucune
RangeExceedsLimit Le nombre de cellules de la plage a dépassé le nombre maximal pris en charge. Pour plus d’informations, consultez l’article Limites de ressources et optimisation des performances pour les compléments Office . Aucune
RefreshWorkbookLinksBlocked L’opération a échoué, car l’utilisateur n’a pas accordé l’autorisation d’actualiser les liens de classeur externes. Aucune
UndoNotSupported La requête de l’API JavaScript a échoué en raison d’un manque de prise en charge de l’opération d’annulation. Aucune
UnsupportedSheet Ce type de feuille ne prend pas en charge cette opération, car il s’agit d’une feuille de graphique ou de macro. Aucune

Messages et codes d’erreur spécifiques à Word

Code d’erreur Message d’erreur Notes
SearchDialogIsOpen La boîte de dialogue de recherche est ouverte. Aucune
SearchStringInvalidOrTooLong La chaîne de recherche n’est pas valide ou trop longue. La chaîne de recherche maximale est de 255 caractères.

Notifications d’erreur

La façon dont vous signalez les erreurs aux utilisateurs dépend du système d’interface utilisateur que vous utilisez.

  • Si vous utilisez React comme système d’interface utilisateur, utilisez les composants et les éléments de conception de Fluent UI. Nous recommandons que les messages d’erreur soient transmis avec un composant de boîte de dialogue . Si l’erreur se trouve dans l’entrée de l’utilisateur, configurez le composant Input pour afficher l’erreur sous forme de texte rouge gras.

    Remarque

    Le composant Alerte peut également être utilisé pour signaler des erreurs aux utilisateurs, mais il est actuellement en préversion et ne doit pas être utilisé dans un complément de production. Pour plus d’informations sur son status de publication, consultez la feuille de route du composant Fluent UI React v9.

  • Si vous n’utilisez pas React pour l’interface utilisateur, envisagez d’utiliser les anciens composants de l’interface utilisateur de Fabric implémentés directement dans HTML et JavaScript.

Voir aussi

  • Last updated on