Panduan Sintaks Diagram State Mermaid.js

Apa itu Diagram State?

Sebuah Diagram State (juga dikenal sebagai Statechart) adalah diagram perilaku diagram UML yang memodelkan siklus hidup terbatas dari satu objek atau subsistem. Diakui sebagai jenis diagram UML inti, jenis diagram UML, menggambarkan kondisi diskrit (state) yang dapat diisi oleh suatu entitas, peristiwa eksternal atau pemicu yang memaksa perpindahan antar kondisi tersebut (transisi), serta cabang aturan bersyarat yang mengubah jalur eksekusi. Pemetaan ini sangat penting untuk melacak siklus hidup objek yang kompleks, seperti perkembangan pesanan dari pemenuhan hingga pengiriman, urutan waktu habis sesi pengguna, atau loop saklar perangkat keras tertanam.

Dengan Mermaid.js, Anda dapat mendefinisikan mesin state reaktif Anda menggunakan skema deklaratif yang didorong teks. Mesin pemroses secara otomatis menghitung jarak tata letak optimal, menangani panah perulangan rekursif, dan menyesuaikan batas wadah state secara halus.

Panduan Sintaks Inti: Elemen dan Konstruksi

Untuk merancang diagram state UML yang akurat dan sesuai standar di Mermaid, Anda harus menguasai penanda masuk/keluar, string transisi, penyusunan komposit, dan blok pilihan bersyarat.

1. Menentukan State Masuk, Keluar, dan Standar

Anda menginisialisasi kanvas state pada baris pertama menggunakan stateDiagram-v2kata kunci. Siklus hidup memerlukan titik mulai dan berhenti yang jelas, yang digambarkan dengan simbol lingkaran padat ([*]):

• State Awal (Masuk): [*] --> NamaState (Menandai di mana siklus hidup dimulai).
• State Akhir (Keluar): NamaState --> [*] (Menandai di mana siklus hidup berakhir).

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

2. Mengonfigurasi Pemicu Transisi dan Label Acara

Untuk memetakan perubahan status, hubungkan token status yang telah Anda definisikan menggunakan garis panah standar (-->). Untuk mendokumentasikan acara, respons API, atau klik tombol yang tepat yang menyebabkan transisi ini, tambahkan tanda titik dua (:) diikuti oleh string teks deskriptif Anda:

stateDiagram-v2
    Aktif --> Tertunda : PembayaranGagal
    Tertunda --> Aktif : FakturLunas

3. Menerapkan Blok Pilihan Bersyarat

Untuk menangani loop evaluasi bercabang, gunakan <<pilihan>>stereotip. Ini menciptakan bentuk berlian yang jelas di kanvas yang membagi satu jalur transisi masuk menjadi beberapa jalur keluar yang berbeda berdasarkan pemeriksaan logika saat runtime:

stateDiagram-v2
    state cek_status <<pilihan>>
    [*] --> cek_status
    cek_status --> PenggunaPremium : jika saldo >= 100
    cek_status --> PenggunaStandar : jika saldo < 100

4. Menata Status Komposit (Bersarang)

Ketika memodelkan sistem yang kompleks, satu status tingkat tinggi dapat berisi siklus hidup internal yang independen. Anda dapat membuat tata letak sub-status bersarang dengan mendefinisikan status induk diikuti oleh blok tubuh yang dibungkus dengan kurung kurawal:

stateDiagram-v2
    state PemrosesanPesanan {
        [*] --> Pengemasan
        Pengemasan --> Pelabelan
    }

Praktik Terbaik untuk Tata Letak Mesin Status yang Bersih

• Buat Token Status Singkat:Gunakan string teks CamelCase singkat untuk token status internal Anda (misalnya, MenungguPengembalianDana). Jika Anda membutuhkan judul deskriptif panjang di kanvas, gunakan state "Blok Teks Deskriptif" sebagai Token sintaks untuk membuat alias eksplisit.
• Pastikan satu titik masuk: Selalu mulai diagram Anda dari satu titik [*] node. Memiliki beberapa titik awal dapat membingungkan pengguna yang berusaha melacak jalur inisialisasi utama sistem.
• Selalu Gunakan stateDiagram-v2: Selalu pilih stateDiagram-v2 kata kunci daripada yang lama stateDiagram bendera. Mesin rendering v2 menggunakan algoritma tata letak yang diperbarui yang memberikan rute garis yang lebih bersih dan penataan kotak bersarang yang lebih baik.

Contoh Diagram Status Mermaid.js Dunia Nyata

Contoh 1: Siklus Hidup Transaksi Dompet Digital (Cabang Pilihan & Putaran Gagal)

Rancangan fungsional ini memodelkan siklus hidup transaksi pembayaran digital, menunjukkan bagaimana transaksi bergerak dari titik pengiriman awal melalui cabang pemeriksaan penipuan hingga ke status ledger yang telah final.

stateDiagram-v2
    state fraud_check <<choice>>

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

    fraud_check --> TransApproved : Skor Risiko Rendah
    fraud_check --> TransFlagged : Skor Risiko Tinggi
    
    TransFlagged --> TransApproved : OverrideManajerManual
    TransFlagged --> TransDeclined : TimeoutKeamanan
    
    TransApproved --> SettlementPending : CommitLedger
    SettlementPending --> TransCompleted : BankSettlementSuccess
    
    TransDeclined --> [*]
    TransCompleted --> [*]

Analisis Sintaks: Alur kerja ini menggunakan <<choice>> blok untuk mengevaluasi skor keamanan sejak awal. Transaksi berpindah melalui jalur yang berbeda berdasarkan skor ini, dengan nama acara yang jelas (seperti ExecuteRiskAssessment) yang didokumentasikan langsung pada panah transisi.

Contoh 2: Saluran Pemenuhan Pesanan E-Commerce (Sistem Bersarang Komposit)

Rancangan perusahaan canggih ini menggambarkan siklus hidup pengiriman dan manajemen pesanan secara lengkap, menggunakan blok komposit bersarang untuk menunjukkan operasi internal yang terjadi selama tahap pemenuhan.

stateDiagram-v2
    [*] --> OrderPlaced
    
    OrderPlaced --> InFulfillment : PembayaranDitangkap
    
    state InFulfillment {
        [*] --> ItemPicking
        ItemPicking --> QualityAudit : BatchDipilih
        QualityAudit --> SecureBoxPacking : AuditLulus
        SecureBoxPacking --> CarrierManifest Generated : LabelDicetak
    }
    
    InFulfillment --> Shipped : SerahTerimaPengiriman
    Shipped --> Delivered : KonfirmasiDalamPengiriman
    
    Delivered --> [*]

Analisis Sintaks: Dengan membungkus langkah-langkah di dalam state InFulfillment {...} blok badan, Anda menciptakan batas struktural yang jelas di atas kanvas. Mesin menganggap blok ini sebagai satu status induk yang terkonsolidasi saat merender langkah-langkah kerja internal secara berurutan, membuat siklus hidup yang kompleks dan berlapis-lapis menjadi mudah dijelajahi.