Руководство по синтаксису диаграмм состояний Mermaid.js

Что такое диаграмма состояний?

A Диаграмма состояний (также известная как диаграмма состояний) — это поведенческая диаграмма UML которая моделирует конечный жизненный цикл одного объекта или подсистемы. Признана основным типом типа диаграммы UML, она иллюстрирует дискретные состояния (состояния), которые может занимать сущность, внешние события или триггеры, вызывающие переход между этими состояниями (переходы), а также условные ветвления правил, изменяющие пути выполнения. Это отображение необходимо для отслеживания сложных жизненных циклов объектов, таких как прогресс заказа от выполнения до доставки, последовательность истечения сессии пользователя или цикл переключения встроенного аппаратного обеспечения.

С помощью Mermaid.js, вы можете определять свои реактивные машины состояний с помощью декларативной, основанной на тексте схемы. Движок парсинга автоматически рассчитывает оптимальные интервалы размещения, обрабатывает рекурсивные петли стрелок и плавно масштабирует границы контейнеров состояний.

Руководство по основному синтаксису: элементы и конструкции

Чтобы создать точную, соответствующую стандартам диаграмму состояний UML в Mermaid, необходимо освоить маркеры входа/выхода, строки переходов, композитную вложенность и блоки условного выбора.

1. Определение состояний входа, выхода и стандартных состояний

Вы инициализируете холст состояний в первой строке, используя ключевое слово stateDiagram-v2 ключевое слово. Жизненные циклы требуют явных точек начала и окончания, которые обозначаются сплошным кругом ([*]):

• Начальное состояние (вход): [*] --> StateName (Обозначает начало жизненного цикла).
• Конечное состояние (выход): StateName --> [*] (Обозначает окончание жизненного цикла).

stateDiagram-v2
    [*] --> Idle
    Idle --> [*]

2. Настройка триггеров переходов и меток событий

Чтобы отобразить смену состояния, соедините ваши определённые токены состояний с помощью стандартной линии со стрелкой (-->). Чтобы зафиксировать точное событие, ответ API или нажатие кнопки, вызывающее этот переход, добавьте двоеточие (:) за которым следует ваша описательная строка текста:

stateDiagram-v2
    Active --> Suspended : PaymentFailed
    Suspended --> Active : InvoiceSettled

3. Реализация блоков условного выбора

Для обработки ветвящихся циклов оценки используйте <<choice>>стереотип. Это создаёт чёткую ромбовидную форму на холсте, которая разделяет один входящий путь перехода на несколько различных исходящих путей на основе проверок логики во время выполнения:

stateDiagram-v2
    state check_status <<choice>>
    [*] --> check_status
    check_status --> PremiumUser : if balance >= 100
    check_status --> StandardUser : if balance < 100

4. Структурирование составных (вложенных) состояний

При моделировании сложной системы одно высокое состояние может содержать собственный независимый внутренний жизненный цикл. Вы можете создать вложенную структуру подсостояний, определив родительское состояние, за которым следует блок тела, заключённый в фигурные скобки:

stateDiagram-v2
    state OrderProcessing {
        [*] --> Packaging
        Packaging --> Labeling
    }

Лучшие практики для чистых макетов машин состояний

• Держите токены состояний короткими: Используйте краткие строки текста в формате CamelCase для внутренних токенов состояний (например, AwaitingRefund). Если вам нужен длинный описательный заголовок на холсте, используйте state "Описательный текстовый блок" как Токен синтаксис для создания явного псевдонима.
• Обеспечьте единый входной пункт: Всегда начинайте свой диаграмму с одного [*] узла. Наличие нескольких начальных точек может запутать пользователей, пытающихся отследить путь инициализации системы.
• Всегда используйте stateDiagram-v2: Всегда выбирайте stateDiagram-v2 ключевое слово вместо устаревшего stateDiagram флаг. Двигатель отображения v2 использует обновленный алгоритм размещения, обеспечивающий более чистое направление линий и лучшую выравнивание вложенных блоков.

Примеры диаграмм состояний Mermaid.js из реальной жизни

Пример 1: Жизненный цикл транзакции цифрового кошелька (ветвление выбора и циклы сбоев)

Этот функциональный чертеж моделирует жизненный цикл цифровой платежной транзакции, показывая, как транзакция перемещается от начальной точки отправки через ветвление проверки мошенничества в итоговые состояния бухгалтерского учета.

stateDiagram-v2
    state fraud_check <<choice>>

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

    fraud_check --> TransApproved : Risk Score Low
    fraud_check --> TransFlagged : Risk Score Elevated
    
    TransFlagged --> TransApproved : ManualManagerOverride
    TransFlagged --> TransDeclined : SecurityTimeout
    
    TransApproved --> SettlementPending : CommitLedger
    SettlementPending --> TransCompleted : BankSettlementSuccess
    
    TransDeclined --> [*]
    TransCompleted --> [*]

Разбор синтаксиса: Этот рабочий процесс использует <<choice>> блок для оценки показателей безопасности сразу в начале. Транзакция переходит по различным путям в зависимости от этих показателей, с четкими именами событий (например, ExecuteRiskAssessment) документированы непосредственно на стрелках переходов.

Пример 2: Цепочка выполнения заказов в электронной коммерции (составные вложенные системы)

Этот продвинутый корпоративный чертеж описывает полный жизненный цикл доставки и управления заказами, используя вложенные составные блоки для отображения внутренних операций, происходящих в фазе выполнения заказа.

stateDiagram-v2
    [*] --> OrderPlaced
    
    OrderPlaced --> InFulfillment : PaymentCaptured
    
    state InFulfillment {
        [*] --> ItemPicking
        ItemPicking --> QualityAudit : BatchPicked
        QualityAudit --> SecureBoxPacking : AuditPassed
        SecureBoxPacking --> CarrierManifest Generated : LabelPrinted
    }
    
    InFulfillment --> Shipped : CarrierHandshake
    Shipped --> Delivered : OutForDeliveryConfirmed
    
    Delivered --> [*]

Разбор синтаксиса: Обернув шаги внутри state InFulfillment {...} блока тела, вы создаете четкую структурную границу на холсте. Движок рассматривает этот блок как единый объединенный родительский состояние во время отрисовки его внутренних шагов рабочего процесса последовательно, что делает сложные многоуровневые жизненные циклы простыми для навигации.