Guía de sintaxis de diagramas de estado de Mermaid.js

¿Qué es un diagrama de estado?

Un diagrama de estado (también conocido como Statechart) es un diagrama de comportamiento diagrama UML que modela el ciclo de vida finito de un objeto o subsistema individual. Reconocido como un tipo fundamental de tipo de diagrama UML, ilustra las condiciones discretas (estados) que una entidad puede ocupar, los eventos externos o desencadenantes que obligan a un cambio entre esas condiciones (transiciones), y las bifurcaciones de reglas condicionales que alteran los caminos de ejecución. Este mapeo es esencial para rastrear ciclos de vida de objetos complejos, como la progresión de un pedido desde la cumplimentación hasta la entrega, una secuencia de tiempo de espera de sesión de usuario o un bucle de interruptor de hardware integrado.

Con Mermaid.js, puedes definir tus máquinas de estado reactivas utilizando un esquema declarativo y basado en texto. El motor de análisis calcula automáticamente el espaciado óptimo del diseño, maneja flechas de bucle recursivas y escala los límites del contenedor de estados de forma suave.

Guía de sintaxis básica: elementos y construcciones

Para diseñar un diagrama de estado UML preciso y conforme a las normas en Mermaid, debes dominar los marcadores de entrada/salida, las cadenas de transición, el anidamiento compuesto y los bloques de elección condicional.

1. Definir estados de entrada, salida y estándar

Inicializas una superficie de estado en la primera línea utilizando la palabra clave stateDiagram-v2 palabra clave. Los ciclos de vida requieren puntos de inicio y parada explícitos, que se representan con un símbolo de círculo sólido ([*]):

• Estado inicial (entrada): [*] --> NombreEstado (Marca el punto donde comienza el ciclo de vida).
• Estado terminal (salida): NombreEstado --> [*] (Marca el punto donde concluye el ciclo de vida).

stateDiagram-v2
    [*] --> Inactivo
    Inactivo --> [*]

2. Configuración de desencadenantes de transición y etiquetas de eventos

Para mapear un cambio de estado, conecte sus tokens de estado definidos utilizando una línea de flecha estándar (-->). Para documentar el evento exacto, respuesta de API o clic en botón que causa esta transición, agregue dos puntos (:) seguido por su cadena de texto descriptiva:

stateDiagram-v2
    Activo --> Suspensión : FalloPago
    Suspensión --> Activo : FacturaPagada

3. Implementación de bloques de elección condicional

Para manejar bucles de evaluación con ramificaciones, use el <<choice>>esteriotipo. Esto crea una forma de diamante clara en el lienzo que divide una única ruta de transición entrante en múltiples rutas salientes distintas basadas en comprobaciones lógicas en tiempo de ejecución:

stateDiagram-v2
    state verificar_estado <<choice>>
    [*] --> verificar_estado
    verificar_estado --> UsuarioPremium : si saldo >= 100
    verificar_estado --> UsuarioEstándar : si saldo < 100

4. Estructuración de estados compuestos (anidados)

Cuando se modela un sistema complejo, un estado de alto nivel puede contener su propia vida interna independiente. Puede crear una disposición de subestados anidados definiendo un estado padre seguido de un bloque de cuerpo encerrado entre llaves:

stateDiagram-v2
    state ProcesamientoPedido {
        [*] --> Empaquetado
        Empaquetado --> Etiquetado
    }

Mejores prácticas para diseños limpios de máquinas de estado

• Mantenga los tokens de estado cortos:Use cadenas de texto breves en formato CamelCase para sus tokens de estado internos (por ejemplo, EsperandoReembolso). Si necesita un título descriptivo largo en el lienzo, use el estado "Bloque de texto descriptivo" como Token sintaxis para crear un alias explícito.
• Impone un único punto de entrada: Comienza siempre tu diagrama desde un solo [*] nodo. Tener múltiples puntos de inicio puede confundir a los usuarios que intentan rastrear la ruta de inicialización raíz del sistema.
• Siempre usa stateDiagram-v2: Siempre elige la stateDiagram-v2 palabra clave sobre la antigua stateDiagram bandera. El motor de renderizado v2 utiliza un algoritmo de diseño actualizado que proporciona una mejor ruta de líneas y una alineación más precisa de cuadros anidados.

Ejemplos reales de diagramas de estado de Mermaid.js

Ejemplo 1: Ciclo de vida de una transacción de billetera digital (ramificaciones de elección y bucles de fallo)

Este plano funcional modela el ciclo de vida de una transacción de pago digital, mostrando cómo una transacción pasa desde un punto de envío inicial a través de una bifurcación de verificación de fraude hasta estados finales del libro contable.

stateDiagram-v2
    estado fraud_check <<choice>>

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

    fraud_check --> TransApproved : Puntuación de riesgo baja
    fraud_check --> TransFlagged : Puntuación de riesgo elevada
    
    TransFlagged --> TransApproved : OverrideManualManager
    TransFlagged --> TransDeclined : SecurityTimeout
    
    TransApproved --> SettlementPending : CommitLedger
    SettlementPending --> TransCompleted : BankSettlementSuccess
    
    TransDeclined --> [*]
    TransCompleted --> [*]

Desglose de sintaxis: Este flujo de trabajo utiliza un <<choice>> bloque para evaluar las puntuaciones de seguridad desde el principio. La transacción avanza por rutas distintas según estas puntuaciones, con nombres de eventos claros (como ExecuteRiskAssessment) documentados directamente en las flechas de transición.

Ejemplo 2: Canal de cumplimiento de pedidos de comercio electrónico (sistemas anidados compuestos)

Este plano avanzado de empresa describe un ciclo de vida completo de envío y gestión de pedidos, utilizando bloques compuestos anidados para mostrar las operaciones internas que ocurren durante la fase de cumplimiento.

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

Desglose de sintaxis: Al envolver los pasos dentro del estado InFulfillment {...} bloque de cuerpo, creas un límite estructural claro en la cuadrícula. El motor trata este bloque como un estado padre consolidado único mientras representa sus pasos de flujo de trabajo internos de forma secuencial, lo que hace que los ciclos de vida complejos de múltiples capas sean fáciles de navegar.