L'API $debug
$debug est une fonction globale installée par le plugin en développement. Cette page décrit comment l'appeler et ce qu'elle affiche. Ses contrôles à l'exécution (ns, enable, disable, setLevel, setPrefixFilter) sont décrits dans Espaces de noms et filtrage.
Signature d'appel et rendu des charges utiles
$debug<T>(
level: 'error' | 'warning' | 'info' | 'debug' | 'success' | 'trace',
payload: string | Error | T,
options?: {
showStack?: boolean
showSource?: boolean
tag?: string
prefix?: string // remplace le préfixe affiché pour cet appel
inspect?: boolean // force ou supprime la valeur vivante dans le navigateur pour cet appel
}
): void
// aussi variadique — plusieurs valeurs, ou une chaîne de format printf :
$debug('info', label, user, el) // jointes + chacune reste vivante
$debug('info', '%s a marqué %d', nom, score) // substitution printf| Option d'appel | Effet |
|---|---|
showStack | Ajoute la pile (masquée) quand la charge utile est une Error. Par défaut, suit l'option showStack du plugin. |
showSource | Affiche le fichier:ligne:colonne d'origine de l'appel. Par défaut, suit l'option showSource du plugin. |
tag | Une étiquette affichée entre crochets après le niveau, par ex. [PropsValidator]. |
prefix | Remplace le préfixe affiché pour cet appel, dans la console du navigateur, le terminal de développement et la sortie SSR. |
inspect | Navigateur uniquement : true force la valeur vivante, false la supprime. Par défaut, suit l'option output.inspect du plugin. |
Réglez output.inspect pour changer ce comportement par défaut, ou passez { inspect: true | false } pour un seul appel. Si redact contient une entrée RegExp ou si redactDefaults est activé, aucune valeur vivante n'est transmise à la console, nœuds DOM compris : un secret ne peut pas échapper au masquage à l'intérieur d'un objet vivant. Les entrées chaîne de redact n'atteignent jamais le navigateur et ne changent donc rien à ce comportement. inspect: true le contourne pour un appel : ne l'utilisez que sur des valeurs dont vous savez qu'elles ne contiennent aucun secret (voir Valeurs vivantes dans le navigateur). Le terminal de développement et la sortie SSR reçoivent toujours la chaîne masquée. raw, nom utilisé pendant le développement de la 1.0, est aussi accepté, avec un avertissement unique dans la console, jusqu'à la 2.0 ; si les deux sont définis, inspect l'emporte.
Le tableau ci-dessous donne le résumé sur une ligne, utilisé pour le terminal de développement et comme étiquette dans la console. Dans le navigateur, la valeur brute est aussi transmise à la console, pour rester vivante et inspectable : voir Inspection d'objets vivante.
| Type de charge utile | Résumé |
|---|---|
string | telle quelle |
number / boolean | String(valeur) : 42, true |
null / undefined | les mots littéraux null / undefined |
function | nom [Function] (anonymous [Function] si elle est anonyme) |
symbol | Symbol(description) |
Error | error.message (pile ajoutée si showStack: true ; les deux masquées) |
| objet / tableau | JSON.stringify avec protection contre les cycles, tronqué à 500 caractères après masquage |
| instance de classe | NomClasse { … } |
Map / Set | Map(n) / Set(n) avec les entrées |
RegExp | /motif/flags |
Date | chaîne ISO-8601 |
bigint | 123n |
ref Vue | .value déballée, puis les règles standard s'appliquent |
| nœud DOM | résumé <tag#id.class> |
Promise | [Promise] (non attendue) |
Niveaux
| Niveau | Libellé par défaut | Couleur CSS par défaut | Couleur du terminal | Méthode console du navigateur | Ordre |
|---|---|---|---|---|---|
trace | Trace | #a855f7 | magenta | console.trace | 0 |
debug | Debug | #6b7280 | gris | console.debug | 1 |
info | Info | #3b82f6 | bleu | console.info | 2 |
success | Success | #10b981 | vert | console.log | 3 |
warning | Warning | #f59e0b | jaune | console.warn | 4 |
error | Error | #ef4444 | rouge | console.error | 5 |
Les libellés par défaut sont les chaînes affichées telles quelles, en anglais. minLevel garde chaque niveau supérieur ou égal au seuil (trace < debug < info < success < warning < error). Pour choisir les niveaux conservés, voir les options levels et minLevel ; pour changer un libellé ou une couleur, voir l'option colors.
Valeurs multiples et printf
Passez plusieurs charges utiles et elles s'affichent comme console.log(a, b, c) : les résumés sont joints par des espaces sur une ligne, et dans le navigateur chaque valeur non primitive reste vivante et inspectable :
$debug("info", "user", user, el); // "user { … } <div#app>" + user vivant + nœud vivantOu commencez par une chaîne de format de style printf, suivie de ses arguments. Contrairement à la substitution native de console, elle est faite par le plugin : elle fonctionne donc dans le navigateur et dans le terminal :
$debug("info", "%s a marqué %d", nom, score); // "Ann a marqué 42"Spécificateurs pris en charge : %s %o %O %j (sérialisé), %d %i (entier), %f (flottant), %c (consommé), %% (% littéral). Les arguments restants sont joints par des espaces ; un argument manquant laisse son spécificateur tel quel. Un objet final de la forme de MTCallOptions est toujours traité comme des options : $debug("info", value, { tag: "x" }) continue donc de fonctionner.
Avec des entrées chaîne dans redact, un %d, %i ou %f venant du navigateur dont le nombre s'écrit autrement que son argument ("007" affiché 7) est masqué en entier dans le terminal et le fichier de log, quel que soit son argument ; la console du navigateur affiche toujours le nombre. Passez un entier, ou utilisez %s.
Une faute de frappe dans l'objet final n'est pas une erreur de type
Sur la forme variadique, n'importe quel objet est une charge utile valide : TypeScript ne peut donc pas signaler { tagg: "x" }. À l'exécution, un objet ne compte comme options que si chacune de ses clés est une option reconnue ; sinon il est journalisé comme charge utile, ce qui met la faute sous vos yeux au lieu de n'appliquer silencieusement rien. Utilisez la forme à deux arguments quand vous voulez l'autocomplétion sur options.
Fonctions utilitaires
$debug porte des fonctions utilitaires sur le modèle de console. Chacune est supprimée des builds de production avec les appels de base, y compris les formes méthode ($debug.time(...)) et chaînée ($debug.ns('x')('info')).
$debug.assert(user.id != null, "user must have an id", { tag: "auth" });
// journalise au niveau "error" UNIQUEMENT quand la condition est fausse
$debug.time("render");
renderExpensiveThing();
$debug.timeEnd("render"); // → MARS-TECH Debug [render] - render: 12.4ms
$debug.count("api-call"); // → api-call: 1
$debug.count("api-call"); // → api-call: 2
$debug.group("checkout"); // vrai groupe repliable dans le navigateur
$debug("info", "validating cart"); // imbriqué sous le groupe
$debug("info", "charging card");
$debug.groupEnd();
$debug.table(rows, ["name", "total"]); // console.table dans le navigateur
$debug.dir(document.body); // inspection d'objet en profondeur avec console.dir| Fonction | Comportement |
|---|---|
assert(condition, payload, opts?) | Journalise payload au niveau error uniquement quand condition est fausse. |
time(label?) / timeEnd(label?) | Journalise le temps écoulé en millisecondes entre les deux appels, au niveau debug. L'étiquette vaut default par défaut. |
count(label?) | Incrémente et journalise un compteur nommé, au niveau debug. |
group(label?) / groupCollapsed(label?) / groupEnd() | Ouvre un vrai groupe console (éventuellement replié) dans le navigateur ; indente la sortie du terminal. L'étiquette est masquée comme un message. |
table(data, columns?) | console.table dans le navigateur ; un résumé texte est envoyé au terminal. Si redact contient une entrée RegExp ou si redactDefaults est activé, le navigateur affiche le résumé masqué à la place. |
dir(item, options?) | Inspection d'objet en profondeur avec console.dir dans le navigateur ; un résumé texte est envoyé au terminal. Si redact contient une entrée RegExp ou si redactDefaults est activé, le navigateur affiche le résumé masqué à la place. |
Chaque fonction utilitaire suit les interrupteurs d'exécution : disable(), setLevel, le filtre de préfixe. Pour time / timeEnd et count, l'étiquette sert aussi d'espace de noms : un filtre d'espaces de noms ciblé comme -render fait taire une paire time("render"). group / groupCollapsed, table et dir n'ont pas d'espace de noms : ils sont filtrés comme un appel sans étiquette. Un filtre -cart les laisse passer, tandis que disable() ou un filtre qui nomme des espaces de noms (auth:*) les écarte. Comme time et count, ils ne s'affichent que si le niveau debug est actif. Un group écarté par un filtre garde son groupEnd apparié : l'imbrication ne dérive jamais. Le chronométrage utilise performance.now() quand il est disponible.
count et time retiennent chacun jusqu'à 1 000 étiquettes. Au-delà, l'étiquette utilisée le moins récemment est oubliée : son compteur repart de 1 et son timeEnd n'affiche rien. Une étiquette construite à partir de données (count(item.id)) ne peut donc pas faire grossir la mémoire pendant toute la vie de la page. L'indentation des groupes cesse de croître à 32 niveaux ; groupEnd ferme quand même chaque niveau.
Toutes ces fonctions existent sur chaque $debug : dans le navigateur, pendant le SSR, dans le processus Vite, dans le bouchon inerte de Vitest, avec test: 'log', et dans les relais ajoutés en tête d'un build brandPrefix. Un appel qui fonctionne dans un composant ne peut donc pas échouer pendant le rendu serveur ni sous test.