Partager via

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

  • Article

Lorsque vous créez un complément à l’aide des API JavaScript Office spécifiques à l’application, veillez à inclure la 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 extraits de code script lab , vous remarquerez que chaque appel à Excel.run, PowerPoint.runou Word.run est accompagné d’une instruction pour intercepter les catch erreurs. Nous vous recommandons d’utiliser le même modèle lorsque vous générez 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 retourne un objet d’erreur qui contient 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.

Notes

Si vous utilisez console.log() pour imprimer des messages d’erreur sur la console, ces messages sont uniquement visibles 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’erreurs.

Codes d’erreur et messages

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

Notes

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. Aucune
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 peut être disponible dans une version plus récente de l’application Office. Pour plus d’informations, voir Disponibilité des applications clientes et des plateformes Office 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 Objet RibbonUpdateObject non valide est passé à 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 être terminée. Aucune
NotImplemented La fonctionnalité demandée n’est pas implémentée Cela peut signifier que l’API est en préversion ou uniquement prise en charge sur une plateforme particulière (par exemple, en ligne uniquement). Pour plus d’informations, voir Disponibilité des applications clientes et des plateformes Office 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 propres à Excel

Code d’erreur Message d’erreur Notes
EmptyChartSeries L’opération tentée a échoué, 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 les ordinateurs 32 bits, la longueur limite du bytecode est de 16 384 caractères. Sur les ordinateurs 64 bits, la limite de longueur du bytecode est de 32 768 caractères. Cette erreur se produit dans Excel sur le web et sur le bureau.
GeneralException Divers. Les API de types de données retournent 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 : « La cellule A1 ne contient pas la propriété typerequise ».
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 en utilisant les touches Entrée ou Tab , ou en sélectionnant une autre cellule, puis réessayez. Aucune
MergedRangeConflict Impossible de terminer l’opération. Une table ne peut pas chevaucher une autre table, un rapport de tableau croisé dynamique, des résultats de requête, des cellules fusionnées ou un mappage XML. Aucune
NonBlankCellOffSheet Microsoft Excel ne peut pas insérer de nouvelles cellules, car il pousserait les cellules non vides hors de la fin de la feuille de calcul. Ces cellules non vides peuvent apparaître vides, mais avoir des valeurs vides, une mise en forme ou une formule. Supprimez suffisamment de lignes ou de colonnes pour libérer de l’espace 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 TableColumnCollection.add API déclenche cette erreur, vérifiez qu’il n’y a pas de données involontaires dans la feuille de calcul, mais en dehors de la table. En particulier, recherchez les données dans les colonnes les plus à droite de la feuille de calcul. Supprimez les données involontaires pour résoudre cette erreur. Une façon de vérifier le nombre de cellules qu’une opération traite 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 pris en charge par Excel.

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 dans 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 externe. Aucune
UnsupportedSheet Ce type de feuille ne prend pas en charge cette opération, car il s’agit d’une feuille Macro ou Graphique. Aucune

Codes d’erreur et messages 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 est trop longue. La chaîne de recherche maximale est de 255 caractères.

Notifications d’erreurs

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 d’interface utilisateur Fluent et les éléments de conception. Nous vous recommandons de transmettre les messages d’erreur avec un composant Dialog . Si l’erreur se trouve dans l’entrée de l’utilisateur, configurez le composant Entrée pour afficher l’erreur sous forme de texte rouge gras.

    Notes

    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 l’état de sa mise en production, 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 Fabric implémentés directement en HTML et JavaScript. Certains exemples de modèles se trouvent dans le référentiel Office-Add-in-UX-Design-Patterns-Code . Examinez en particulier la boîte de dialogue et les sous-dossiers de navigation. L’exemple Excel-Add-in-SalesLeads utilise une bannière de message.

Voir aussi