Guia de Sintaxe de Diagrama de Estados do Mermaid.js

O que é um Diagrama de Estados?

Um Diagrama de Estados (também conhecido como Statechart) é um diagrama comportamental diagrama UML que modela o ciclo de vida finito de um único objeto ou sub-sistema. Reconhecido como um tipo central tipo de diagrama UML, ele ilustra as condições discretas (estados) que uma entidade pode ocupar, os eventos externos ou gatilhos que forçam uma mudança entre essas condições (transições) e os ramos condicionais de regras que alteram os caminhos de execução. Essa representação é essencial para rastrear ciclos de vida complexos de objetos, como a progressão de um pedido desde a execução até a entrega, uma sequência de tempo limite de sessão de usuário ou um loop de interruptor de hardware embutido.

Com Mermaid.js, você pode definir suas máquinas de estado reativas usando um esquema declarativo e baseado em texto. O motor de análise calcula automaticamente o espaçamento ideal para o layout, manipula setas de laço recursivo e escala os limites dos contêineres de estado de forma suave.

Guia de Sintaxe Básica: Elementos e Construções

Para projetar um diagrama de estados UML preciso e compatível com padrões no Mermaid, você deve dominar marcadores de entrada/saída, strings de transição, aninhamento composto e blocos de escolha condicional.

1. Definindo Estados de Entrada, Saída e Padrão

Você inicializa uma tela de estado na primeira linha usando a stateDiagram-v2palavra-chave. Os ciclos de vida exigem pontos de início e parada explícitos, representados pelo símbolo de círculo sólido ([*]):

• Estado Inicial (Entrada): [*] --> NomeDoEstado (Marca onde o ciclo de vida começa).
• Estado Terminal (Saída): NomeDoEstado --> [*] (Marca onde o ciclo de vida conclui).

stateDiagram-v2
    [*] --> Ocioso
    Ocioso --> [*]

2. Configurando Disparadores de Transição e Rótulos de Evento

Para mapear uma mudança de estado, conecte seus tokens de estado definidos usando uma linha de seta padrão (“-->). Para documentar o evento exato, resposta da API ou clique no botão que causa essa transição, acrescente dois pontos (“:) seguido pela sua string descritiva:

stateDiagram-v2
    Ativo --> Suspensão : FalhaNoPagamento
    Suspensão --> Ativo : FaturaQuitada

3. Implementando Blocos de Escolha Condicionais

Para lidar com loops de avaliação ramificados, use o <<escolha>>estereótipo. Isso cria uma forma clara em losango na tela que divide um único caminho de transição de entrada em múltiplos caminhos de saída distintos com base em verificações lógicas em tempo de execução:

stateDiagram-v2
    estado verificar_status <<escolha>>
    [*] --> verificar_status
    verificar_status --> UsuarioPremium : se saldo >= 100
    verificar_status --> UsuarioPadrao : se saldo < 100

4. Estruturando Estados Compostos (Aninhados)

Ao modelar um sistema complexo, um único estado de alto nível pode conter sua própria vida interna independente. Você pode criar uma estrutura de sub-estado aninhado definindo um estado pai seguido por um bloco de corpo envolto por chaves:

stateDiagram-v2
    estado ProcessamentoDoPedido {
        [*] --> Embalagem
        Embalagem --> Rotulagem
    }

Melhores Práticas para Layouts Limpos de Máquinas de Estado

• Mantenha os Tokens de Estado Curto: Use strings de texto curtas em CamelCase para seus tokens de estado internos (por exemplo, AguardandoReembolso). Se você precisar de um título descritivo longo na tela, use o estado "Bloco de Texto Descritivo" como Token sintaxe para criar um alias explícito.
• Forçar um único ponto de entrada: Sempre comece seu diagrama a partir de um único[*] nó. Ter múltiplos pontos de início pode confundir os usuários tentando rastrear o caminho de inicialização raiz do sistema.
• Sempre use stateDiagram-v2: Sempre escolha ostateDiagram-v2 palavra-chave em vez da legadastateDiagram sinalizador. O motor de renderização v2 usa um algoritmo de layout atualizado que oferece roteamento de linhas mais limpo e alinhamentos melhores para caixas aninhadas.

Exemplos Reais de Diagramas de Estado Mermaid.js

Exemplo 1: Ciclo de Vida de Transação de Carteira Digital (Ramificações de Escolha e Loops de Falha)

Este plano funcional modela o ciclo de vida de uma transação de pagamento digital, mostrando como uma transação se move a partir de um ponto inicial de submissão até um ramo de verificação de fraude até estados finais no registro.

stateDiagram-v2
    estado fraud_check <<choice>>

    [*] --> TransEnviada
    TransEnviada --> fraud_check : ExecutarAvaliacaoRisco

    fraud_check --> TransAprovada : Pontuação de Risco Baixa
    fraud_check --> TransSinalizada : Pontuação de Risco Elevada
    
    TransSinalizada --> TransAprovada : SobrescritaManualGerente
    TransSinalizada --> TransRecusada : TempoLimiteSeguranca
    
    TransAprovada --> PendenteLiquidacao : ConfirmarLedger
    PendenteLiquidacao --> TransConcluida : SucessoLiquidacaoBanco
    
    TransRecusada --> [*]
    TransConcluida --> [*]

Análise da Sintaxe: Este fluxo de trabalho utiliza um<<choice>> bloco para avaliar pontuações de segurança logo no início. A transação segue caminhos distintos com base nessas pontuações, com nomes de eventos claros (comoExecutarAvaliacaoRisco) documentados diretamente nas setas de transição.

Exemplo 2: Pipeline de Cumprimento de Pedidos de E-Commerce (Sistemas Compostos Aninhados)

Este plano avançado de empresa descreve todo o ciclo de vida de envio e gerenciamento de pedidos, usando blocos compostos aninhados para mostrar as operações internas que ocorrem na fase de cumprimento.

stateDiagram-v2
    [*] --> PedidoColocado
    
    PedidoColocado --> EmCumprimento : PagamentoCapturado
    
    estado EmCumprimento {
        [*] --> ColetaItem
        ColetaItem --> AuditoriaQualidade : LotePego
        AuditoriaQualidade --> EmbalagemSegura : AuditoriaAprovada
        EmbalagemSegura --> ManifestoTransportadoraGerado : EtiquetaImpressa
    }
    
    EmCumprimento --> Enviado : ApertoTransportadora
    Enviado --> Entregue : ConfirmadoEntregaEmAndamento
    
    Entregue --> [*]

Análise de Sintaxe: Ao envolver etapas dentro do estado InFulfillment {...} bloco corpo, você cria um limite estrutural claro na tela. O motor trata este bloco como um único estado pai consolidado ao renderizar suas etapas internas de fluxo de trabalho sequencialmente, tornando os ciclos de vida complexos e multicamadas fáceis de navegar.