Éditeur de diagramme d'états Mermaid
Un diagramme d'états montre les états dans lesquels une seule chose peut se trouver et les événements qui la font passer de l'un à l'autre. Il convient quand le sujet est un cycle de vie — une commande, un abonnement, un dossier en instruction. Le signe qui ne trompe pas : vos étiquettes sont des adjectifs et non des verbes — en attente, expédiée, annulée.
Le cycle de vie d'une commande, avec une annulation terminale
Les états sont ce que la commande est ; les étiquettes des flèches sont ce qui lui est arrivé. Remarquez qu'on atteint Annulée depuis trois états mais qu'elle ne mène nulle part : cette asymétrie est exactement ce qu'un diagramme d'états rend évident et qu'un organigramme dissimule.
stateDiagram-v2
[*] --> EnAttente: commande passée
EnAttente --> Payee: paiement encaissé
EnAttente --> Annulee: le client se rétracte
Payee --> Preparee: préparation en entrepôt
Payee --> Remboursee: paiement annulé
Preparee --> Expediee: prise en charge transporteur
Preparee --> Annulee: rupture de stock
Expediee --> Livree: livraison confirmée
Expediee --> Egaree: aucun scan depuis 14 jours
Livree --> [*]
Remboursee --> [*]
Annulee --> [*]
Egaree --> Remboursee: réclamation acceptéeExemples commentés
1. La machine à états minimale
`[*]` est à la fois le pseudo-état initial et le final : ce qu'il désigne dépend du côté de la flèche où il se trouve.
stateDiagram-v2
[*] --> Brouillon
Brouillon --> Publie: publier
Publie --> [*]2. Nommer des états contenant des espaces
Un identifiant d'état ne peut pas contenir d'espace, mais `state "Libellé" as id` donne un libellé lisible avec un identifiant sûr. En français c'est presque toujours nécessaire, parce que nos états naturels sont des locutions : « en attente de paiement », « en cours d'instruction ».
stateDiagram-v2
state "En attente de relecture" as relecture
state "Corrections demandées" as corrections
[*] --> relecture
relecture --> corrections: le relecteur objecte
corrections --> relecture: l'auteur corrige
relecture --> [*]: approuvé3. États composites
Un état peut contenir sa propre machine à états. Utilisez-le quand une étape a des sous-étapes qui ont du sens et qui, au premier niveau, ne feraient qu'encombrer : ici, tout ce qui se passe dans Traitement.
stateDiagram-v2
[*] --> EnFile
EnFile --> Traitement: pris par un worker
state Traitement {
[*] --> Validation
Validation --> Transformation: schéma conforme
Transformation --> Ecriture: lignes converties
Ecriture --> [*]
}
Traitement --> Reussi: aucune erreur
Traitement --> Echoue: exception levée
Echoue --> EnFile: nouvelle tentative
Reussi --> [*]4. Pseudo-états de choix
Un `<<choice>>` est une bifurcation qui dépend d'une condition et non d'un événement. Il garde la décision visible sans faire croire que c'est un état où l'objet séjourne.
stateDiagram-v2
state evaluation <<choice>>
[*] --> Deposee
Deposee --> evaluation: calcul du score de risque
evaluation --> Acceptee: score < 40
evaluation --> RevueManuelle: score >= 40
RevueManuelle --> Acceptee: l'analyste accepte
RevueManuelle --> Refusee: l'analyste refuse
Acceptee --> [*]
Refusee --> [*]5. Régions concurrentes
Deux tirets sur une ligne à eux seuls découpent un état composite en régions actives en même temps. C'est la seule chose qu'un diagramme d'états fait et qu'un organigramme ne peut pas vraiment faire.
stateDiagram-v2
[*] --> Inscription
state Inscription {
[*] --> CourrielNonVerifie
CourrielNonVerifie --> CourrielVerifie: lien cliqué
--
[*] --> ProfilVide
ProfilVide --> ProfilComplet: formulaire envoyé
}
Inscription --> Actif: les deux sont complets
Actif --> [*]Référence de syntaxe du diagramme d'états
Utilisez `stateDiagram-v2` plutôt que `stateDiagram`. Les deux se dessinent, mais v2 est le moteur de placement encore développé et il traite bien mieux les états composites et concurrents.
| Syntaxe | Signification |
|---|---|
| stateDiagram-v2 | Ouvre le diagramme. `stateDiagram` fonctionne encore mais utilise l'ancien placement. |
| [*] --> A | État initial — le point d'entrée. |
| A --> [*] | État terminal. |
| A --> B | Transition sans événement nommé. |
| A --> B: événement | Transition étiquetée par ce qui la déclenche. |
| state "Libellé" as id | Libellé lisible avec un identifiant sans espace. |
| state A { ... } | État composite contenant sa propre machine. |
| -- | À l'intérieur d'un état composite, le découpe en régions concurrentes. |
| state x <<choice>> | Point de bifurcation conditionnel. |
| state f <<fork>> / <<join>> | Séparer en transitions parallèles et les réunir. |
| note right of A: texte | Attache une note. Aussi `note left of`. |
| direction LR | Place la machine de gauche à droite au lieu de haut en bas. |
Six erreurs qui cassent un diagramme d'états
Reproduites avec Mermaid 11.12.2. Les quatre premières empêchent le diagramme de se dessiner. Les deux dernières sont pires : elles se dessinent sans broncher et donnent un diagramme qui ne veut pas dire ce que vous avez écrit.
Ce que vous voyez
Le diagramme se dessine, mais un état est devenu plusieurs boîtes
Pourquoi
Une espace dans l'identifiant d'un état — et c'est ici que le français se fait piéger deux fois. D'abord parce que presque aucun de nos états ne tient en un mot. Ensuite parce que l'espace fautive peut être une insécable invisible, insérée d'office par un traitement de texte devant `: ; ! ?`. Mermaid ne refuse rien et ne lit pas la suite comme une description : il crée une boîte par mot. Mesuré en lisant les identifiants émis : `[*] --> En attente` donne deux états, `En` et `attente`, dont seul le premier est au bout de la flèche ; l'autre reste là, sans lien. Un libellé de trois mots donne trois boîtes et le diagramme s'élargit sans rien dire. Vérifié avec l'espace ordinaire et avec l'insécable : les deux se scindent de la même façon. La description existe bel et bien, mais elle réclame un deux-points — `attente: en attente de règlement` — et c'est avec cela que l'erreur est confondue.
Correction
Déclarez l'état avec `state "Libellé" as id` et ne le désignez plus que par son identifiant.
stateDiagram-v2
[*] --> En attente
En attente --> ClosstateDiagram-v2
state "En attente" as attente
[*] --> attente
attente --> ClosCe que vous voyez
Parse error, se terminant par : got 'INVALID'
Pourquoi
Un tiret dans l'identifiant d'un état. Les noms en kebab-case viennent naturellement — `en-cours`, `pre-valide` — mais le tiret est lu comme le début d'une flèche de transition.
Correction
Un seul mot ou des tirets bas pour l'identifiant, et le texte lisible dans un libellé entre guillemets.
stateDiagram-v2
[*] --> en-cours
en-cours --> ClosstateDiagram-v2
state "En cours" as enCours
[*] --> enCours
enCours --> ClosCe que vous voyez
Parse error à l'intérieur d'un état composite
Pourquoi
Un état composite ouvert par `{` et jamais fermé. L'accolade fermante doit être sur une ligne à elle.
Correction
Fermez le bloc.
stateDiagram-v2
[*] --> Externe
state Externe {
[*] --> InternestateDiagram-v2
[*] --> Externe
state Externe {
[*] --> Interne
}Ce que vous voyez
Lexical error on line N. Unrecognized text.
Pourquoi
Le séparateur de régions concurrentes avec le mauvais nombre de tirets. Il en faut exactement deux, sur une ligne à eux seuls, à l'intérieur d'un état composite. Trois tirets forment un jeton entièrement différent.
Correction
Utilisez exactement `--`.
stateDiagram-v2
state Deux {
[*] --> A
---
[*] --> B
}stateDiagram-v2
state Deux {
[*] --> A
--
[*] --> B
}Ce que vous voyez
Parse error on line 1, se terminant par : got 'ID'
Pourquoi
Un suffixe de version qui n'existe pas. Il y a `stateDiagram` et `stateDiagram-v2`, et rien d'autre : `-v3` échoue dès la première ligne.
Correction
Utilisez `stateDiagram-v2`.
stateDiagram-v3
[*] --> BrouillonstateDiagram-v2
[*] --> BrouillonCe que vous voyez
Le diagramme se dessine, mais le nœud de choix est dessiné comme un état ordinaire
Pourquoi
La déclaration `<<choice>>` vient après les transitions qui l'utilisent. Mermaid crée l'état à la première mention, et un stéréotype ajouté plus tard ne change rien à ce qui existe déjà.
Correction
Déclarez les pseudo-états avant les transitions qui les référencent.
stateDiagram-v2
[*] --> evaluation
evaluation --> Acceptee
evaluation --> Refusee
state evaluation <<choice>>stateDiagram-v2
state evaluation <<choice>>
[*] --> evaluation
evaluation --> Acceptee
evaluation --> RefuseeNotes sur le rendu
Mesuré sur le Mermaid 11.12.2 qu'utilise ce site.
C'est ici que l'espace insécable devient dangereuse
La comparaison entre types vaut d'être connue, parce que la même étourderie est sanctionnée très différemment. Dans un organigramme, une espace — ordinaire ou insécable — dans un identifiant de nœud provoque une erreur d'analyse : vous êtes prévenu. Dans un diagramme d'états, rien du tout : le diagramme se dessine et l'état devient une boîte par mot. Comme la typographie française insère des insécables sans qu'on les demande et qu'elles sont invisibles à l'écran, c'est le seul endroit du site où un caractère qu'on n'a pas tapé produit un diagramme faux sans le moindre signe. La parade est d'écrire `state "…" as id` par réflexe.
La hauteur augmente d'environ 114 pixels par état
Mesuré : trois états donnent un viewBox d'environ 91×348, quarante états donnent 100×4566, soit à peu près 114 pixels de hauteur par état. Comme pour les organigrammes, la largeur ne bouge presque pas : les machines à états grandissent vers le bas. Quand un cycle de vie est long et peu ramifié, `direction LR` à l'intérieur du diagramme est le remède habituel.
stateDiagram et stateDiagram-v2 se dessinent tous les deux, et c'est un piège
On lit souvent qu'il faut utiliser `stateDiagram-v2` sous peine de ne rien voir s'afficher. C'est faux en 11.12.2 : les deux mots-clés se dessinent sans erreur. Ce qui change est la qualité du placement, surtout pour les états composites et concurrents, et rien ne vous avertit quand vous employez l'ancien. Si un état composite paraît à l'étroit ou si les flèches font des détours bizarres, vérifiez avec quel mot-clé vous avez ouvert avant de réécrire le diagramme.
Les étiquettes sont du HTML, donc l'export PNG redessine
Comme pour les organigrammes, les diagrammes de classes et ER, les étiquettes d'état sont dessinées dans un `<foreignObject>` du SVG. Les navigateurs refusent de rasteriser cela sur un canvas : l'export PNG de ce site redessine donc d'abord le diagramme avec des étiquettes en texte SVG simple. Le PNG est correct et à taille réelle ; la typographie diffère très légèrement de celle de l'écran.
Le thème change les couleurs, jamais la géométrie
Les thèmes clair et sombre produisent un viewBox identique pour la même source : une machine à états ne peut donc pas se recomposer quand on change de thème.
Quand un autre diagramme convient mieux
Si vos étiquettes sont des verbes — valider, envoyer, réessayer —, vous décrivez un processus et non un cycle de vie, et le choix honnête est l'organigramme. Le signe le plus clair est que vous ne savez pas répondre à la question « quelle est la chose qui se trouve dans cet état ? ».
Si plusieurs composants ont chacun leur cycle de vie et que l'intéressant est leur interaction, un diagramme d'états par composant plus un diagramme de séquence pour l'échange valent mieux qu'une machine unique et gigantesque.
Et si tous les états communiquent avec tous les autres, le diagramme sera un plat de nouilles quelle que soit la façon de le dessiner. Cela signifie en général que ce que vous appelez des états n'en sont pas, mais des indicateurs qui se combinent librement ; dans ce cas, un tableau des combinaisons valides en dit bien plus long qu'une image.
Autres types de diagrammes
Écrit par Dominik Malsch · Dernière mise à jour: