Guide de syntaxe des diagrammes d’état Mermaid.js

Qu’est-ce qu’un diagramme d’état ?

Un diagramme d’état (également connu sous le nom de Statechart) est un diagramme comportemental diagramme UML qui modélise le cycle de vie fini d’un objet ou d’un sous-système. Reconnu comme un type fondamental de diagramme UML, il illustre les conditions discrètes (états) qu’une entité peut occuper, les événements externes ou déclencheurs qui obligent un changement entre ces conditions (transitions), et les branches conditionnelles qui modifient les chemins d’exécution. Cette cartographie est essentielle pour suivre les cycles de vie complexes des objets, tels que l’évolution d’une commande du traitement à la livraison, une séquence d’expiration de session utilisateur, ou une boucle de commutateur matériel intégré.

Avec Mermaid.js, vous pouvez définir vos machines à états réactives à l’aide d’un schéma déclaratif basé sur le texte. Le moteur d’analyse calcule automatiquement l’espacement optimal du layout, gère les flèches de boucle récursive et ajuste les limites des conteneurs d’état de manière fluide.

Guide de syntaxe fondamentale : éléments et constructions

Pour concevoir un diagramme d’état UML précis et conforme aux normes dans Mermaid, vous devez maîtriser les marqueurs d’entrée/sortie, les chaînes de transition, le regroupement composite et les blocs de choix conditionnels.

1. Définition des états d’entrée, de sortie et standards

Vous initialisez une toile d’état à la première ligne en utilisant le mot-clé stateDiagram-v2mot-clé. Les cycles de vie nécessitent des points de départ et d’arrêt explicites, représentés par un symbole de cercle plein ([*]):

• État initial (entrée) : [*] --> NomÉtat (Marque le point de départ du cycle de vie).
• État terminal (sortie) : NomÉtat --> [*] (Marque la fin du cycle de vie).

stateDiagram-v2
    [*] --> Inactif
    Inactif --> [*]

2. Configuration des déclencheurs de transition et des étiquettes d’événement

Pour cartographier un changement d’état, connectez vos jetons d’état définis à l’aide d’une ligne fléchée standard (“-->). Pour documenter l’événement exact, la réponse API ou le clic sur le bouton qui provoque cette transition, ajoutez deux points (“:) suivi de votre chaîne de texte descriptive :

stateDiagram-v2
    Actif --> Suspendu : PaiementÉchoué
    Suspendu --> Actif : FacturePayée

3. Mise en œuvre des blocs de choix conditionnels

Pour gérer les boucles d’évaluation imbriquées, utilisez le <<choice>> stéréotype. Cela crée une forme de losange claire sur le canevas qui divise un seul chemin d’entrée de transition en plusieurs chemins de sortie distincts basés sur des vérifications logiques en temps réel :

stateDiagram-v2
    state verifier_statut <<choice>>
    [*] --> verifier_statut
    verifier_statut --> UtilisateurPremium : si solde >= 100
    verifier_statut --> UtilisateurStandard : si solde < 100

4. Structuration des états composites (imbriqués)

Lors de la modélisation d’un système complexe, un état de haut niveau unique peut contenir son propre cycle de vie interne indépendant. Vous pouvez créer une disposition d’état sous-jacent imbriqué en définissant un état parent suivi d’un bloc de corps entouré d’accolades :

stateDiagram-v2
    state TraitementCommande {
        [*] --> Emballage
        Emballage --> Étiquetage
    }

Meilleures pratiques pour des dispositions de machines à états propres

• Gardez les jetons d’état courts : Utilisez des chaînes de texte courtes en notation CamelCase pour vos jetons d’état internes (par exemple, EnAttenteRemboursement). Si vous avez besoin d’un titre descriptif long sur le canevas, utilisez le état "BlocTexteDescriptif" comme Jeton syntaxe pour créer un alias explicite.
• Imposer un point d’entrée unique : Commencez toujours votre diagramme à partir d’un seul [*] nœud. Avoir plusieurs points de départ peut confondre les utilisateurs essayant de suivre le chemin d’initialisation racine du système.
• Utilisez toujours stateDiagram-v2 : Choisissez toujours le stateDiagram-v2 état ancien stateDiagram indicateur. Le moteur de rendu v2 utilise un algorithme de disposition mis à jour qui offre un routage de lignes plus propre et une meilleure alignement des boîtes imbriquées.

Exemples réels de diagrammes d’état Mermaid.js

Exemple 1 : Cycle de vie d’une transaction de portefeuille numérique (branches de choix et boucles d’erreur)

Ce plan fonctionnel modélise le cycle de vie d’une transaction de paiement numérique, en montrant comment une transaction passe d’un point de soumission initial à une bifurcation de vérification de fraude jusqu’à des états finaux du registre.

stateDiagram-v2
    état fraud_check <<choice>>

    [*] --> TransSubmitted
    TransSubmitted --> fraud_check : ExecuteRiskAssessment

    fraud_check --> TransApproved : Score de risque Faible
    fraud_check --> TransFlagged : Score de risque Élevé
    
    TransFlagged --> TransApproved : Remise manuelle par le gestionnaire
    TransFlagged --> TransDeclined : Délai de sécurité dépassé
    
    TransApproved --> SettlementPending : Valider le registre
    SettlementPending --> TransCompleted : Succès du règlement bancaire
    
    TransDeclined --> [*]
    TransCompleted --> [*]

Analyse de la syntaxe : Ce flux de travail utilise un <<choice>> bloc pour évaluer les scores de sécurité dès le départ. La transaction suit des chemins distincts en fonction de ces scores, avec des noms d’événements clairs (comme ExecuteRiskAssessment) documentés directement sur les flèches de transition.

Exemple 2 : Pipeline de traitement des commandes e-commerce (systèmes imbriqués composites)

Ce plan d’entreprise avancé décrit le cycle de vie complet de l’expédition et de la gestion des commandes, en utilisant des blocs composites imbriqués pour montrer les opérations internes effectuées pendant la phase de traitement.

stateDiagram-v2
    [*] --> OrderPlaced
    
    OrderPlaced --> InFulfillment : Paiement capturé
    
    état InFulfillment {
        [*] --> ItemPicking
        ItemPicking --> QualityAudit : Lot sélectionné
        QualityAudit --> SecureBoxPacking : Audit validé
        SecureBoxPacking --> CarrierManifest Generated : Étiquette imprimée
    }
    
    InFulfillment --> Shipped : Échange avec le transporteur
    Shipped --> Delivered : Livraison confirmée
    
    Delivered --> [*]

Analyse syntaxique : En encapsulant les étapes à l’intérieur du état InFulfillment {...} bloc corps, vous créez une frontière structurelle claire sur la toile. Le moteur traite ce bloc comme un état parent consolidé unique tout en rendant les étapes internes du flux de travail de manière séquentielle, ce qui rend les cycles de vie complexes à plusieurs niveaux faciles à naviguer.