Aller au contenu principal
Version: 3.0.0-rc.1

📦 logger

Un générateur de journaux encapsulé pour le formatage sémantique des messages de la console.

Les auteurs de paquets de l'écosystème Docusaurus sont encouragés à utiliser ce paquet pour fournir des formats de log unifiés.

API

It exports a single object as default export: logger. logger has the following properties:

  • Quelques couleurs utiles.
    • red
    • yellow
    • green
    • bold
    • dim
  • Formatteurs. These functions all have the signature (msg: unknown) => string. Notez que leurs implémentations ne sont pas garanties. Vous ne devriez vous préoccuper que de leur sémantique.
    • path: formats a file path.
    • url: formats a URL.
    • name: formats an identifier.
    • code: formats a code snippet.
    • subdue: subdues the text.
    • num: formats a number.
  • The interpolate function. C'est un gabarit étiqueté. La syntaxe peut être trouvée ci-dessous.
  • Fonctions de journalisation. All logging functions can both be used as normal functions (similar to the console.log family, but only accepts one parameter) or template literal tags.
    • info: prints information.
    • warn: prints a warning that should be paid attention to.
    • error: prints an error (not necessarily halting the program) that signals significant problems.
    • success: prints a success message.
  • The report function. It takes a ReportingSeverity value (ignore, log, warn, throw) and reports a message according to the severity.
A word on the error formatter

Beware that an error message, even when it doesn't hang the program, is likely going to cause confusion. When users inspect logs and find an [ERROR], even when the build succeeds, they will assume something is going wrong. Utilisez-le avec modération.

Docusaurus only uses logger.error when printing messages immediately before throwing an error, or when user has set the reporting severity of onBrokenLink, etc. to "error".

In addition, warn and error will color the entire message for better attention. If you are printing large blocks of help text about an error, better use logger.info.

Utilisation du gabarit étiqueté

Le gabarit étiqueté évalue le template et les expressions intégrées. interpolate returns a new string, while other logging functions prints it. Ci-dessous est une utilisation typique :

import logger from '@docusaurus/logger';

logger.info`Hello name=${name}! You have number=${money} dollars. Here are the ${
items.length > 1 ? 'items' : 'item'
} on the shelf: ${items}
To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to quit, press code=${'Ctrl + C'}.`;

An embedded expression is optionally preceded by a flag in the form [a-z]+= (a few lowercase letters, followed by an equals sign, directly preceding the embedded expression). Si l'expression n'est précédée d'aucun drapeau, elle est imprimée telle quelle. Sinon, il est formaté avec un des formateurs :

  • path=: path
  • url=: url
  • name=: name
  • code=: code
  • subdue=: subdue
  • number=: num

If the expression is an array, it's formatted by `\n- ${array.join('\n- ')}\n` (note it automatically gets a leading line end). Chaque membre est formaté par lui-même et la puce n'est pas formatée. Vous verrez donc le message ci-dessus affiché sous la forme suivante :

Some text output in the terminal, containing array, code, name, and number formatting