Urăști desenul diagrame pentru documentatie tehnica? Se pare că, de îndată ce terminați o schiță, apar noi rafinamente, care vă obligă să schimbați nu numai textul, ci și imaginea. Dacă utilizați un instrument de desen tradițional, acest lucru poate fi obositor.

UML

UML este acronimul pentru Universal Modeling Language, un efort de standardizare a unei iconografii pentru designul de software care a apărut pentru prima dată acum 25 de ani. Deși poate nu a fost la înălțimea ambiții mai mari a lui designeri, oferă în continuare un mod consecvent de a vizualiza diverse fațete ale designului software.

PlantUML

Desenarea diagramelor UML este plictisitoare, dar ce se întâmplă dacă ai putea descrie textul unei diagrame UML într-un mod în care ai putea să îl incluzi direct într-un document bazat pe Markdown, vezi atât diagramele cât și textul formatat într-o previzualizare pe măsură ce o editezi și în plus, puteți exporta Markdown ca HTML sau PDF? Textul și diagramele dvs. sunt integrate perfect într-un singur fișier. Acolo este PlantUML vine în …

Cod VS

Visual Studio Code (alias VS Code) a devenit un editor popular pentru diferite limbi de computer, inclusiv Markdown. Cu o singură extensie, puteți vizualiza diagrame UML în panoul de previzualizare VS Code.

Acea extensie se numește plantuml, și îl puteți instala fie căutându-l în panoul de extensii (faceți clic pe pictograma extensiei):

Cum se editeaza Markdown UML in Visual Studio Code

apoi faceți clic pe instalare sau pur și simplu executând următoarele dintr-un panou terminal (Ctrl + ‘obține unul):

ext install plantuml

De asemenea, va trebui să aveți instalată o versiune de Java, cu JAVA_HOME set de variabile de mediu sau o cale executabilă cu java locație binară în ea.

Adăugarea PlantUML la Markdown

Cu extensia instalată, puteți introduce acum diagrame UML folosind limbajul PlantUML. Un exemplu:

## uml: sequence diagram
Here I will embed PlantUML markup to generate a sequence diagram.

I can include as many plantuml segments as I want in my Markdown, and the diagrams can be of any type supported by PlantUML.

```plantuml
@startuml
    skinparam backgroundColor #EEEBDC
    skinparam handwritten true
    actor Customer
    Customer -> "login()" : username & password
    "login()" -> Customer : session token
    activate "login()"
    Customer -> "placeOrder()" : session token, order info
    "placeOrder()" -> Customer : ok
    Customer -> "logout()"
    "logout()" -> Customer : ok
    deactivate "login()"
@enduml
```

Și acum, când deschid panoul de previzualizare al codului VS:

1612041185 764 Cum se editeaza Markdown UML in Visual Studio Code
Document de marcare în stânga, Previzualizare în dreapta

Mai mult, diagrama din panoul Preview este păstrată sincronizată cu UML așa cum este descris în documentul Markdown. Nu este nevoie să reîmprospătați panoul de previzualizare.

Este minunat, dar ce se întâmplă dacă doriți să exportați o diagramă din Markdown? Pentru asta veți avea nevoie de puțin ajutor de la prietenii dvs. …

Exportul în SVG sau PNG

Pentru a exporta diagrame individuale, trebuie să instalez GraphViz, care este „software de vizualizare a graficelor open source”. Funcționează împreună cu plantuml extensie instalată mai devreme. Spre deosebire de plantuml, nu este o extensie de cod VS, ci un executabil.

Pentru a exporta în SVG sau PNG:

  1. plasați cursorul în textul PlantUML dorit,
  2. deschideți paleta de comenzi (Ctrl-Shift-P pe computerul meu); sau faceți clic dreapta și selectați Command Palette …
  3. Alegeți „PlantUML: Exportați diagrama curentă”

Puteți alege PNG, SVG sau alte formate. ** Iată versiunile PNG și SVG ale diagramei prezentate în panoul Preview, de mai sus:

1612041185 584 Cum se editeaza Markdown UML in Visual Studio Code
PNG
Cum se editeaza Markdown UML in Visual Studio Code.svg
SVG

De asemenea, aveți opțiunea de a exporta toate diagramele într-un document Markdown (opțiunea paletei de comenzi „PlantUML: Export Diagramele fișierului curent”), care va crea fișiere de imagine separate pentru fiecare diagramă. De exemplu, documentul meu Markdown este numit basic.md iar când export toate diagramele (sunt trei) ca SVG, sunt generate trei fișiere imagine:

  • basic.svg (diagrama de secvență deja afișată)
  • basic-1.svg (o diagramă de clasă)
### uml: class diagram
```plantuml
@startuml
package "customer domain" #DDDDDD {
    class Contact {
        + email
        + phone
    }

    class Address {
        + address1
        + address2
        + city
        + region
        + country
        + postalCode
        + organization
    }

    note right of Address 
        There are two types of 
        addresses: billing and shipping
    end note

    class Customer {
    }

    Customer *-- Contact
    Customer *-- ShippingAddress
    Customer *-- BillingAddress
    Customer *--{ SalesOrder

    class ShippingAddress <<Address>>
    class BillingAddress <<Address>>
    class SalesOrder {
        + itemDescription
        + itemPrice
        + shippingCost
        + trackingNumber
        + shipDate
    }
}
@enduml
```
1612041185 989 Cum se editeaza Markdown UML in Visual Studio Code.svg
  • basic-2.svg (o diagramă de stare)
## uml: state diagram
```plantuml
@startuml
scale 600 width
skinparam backgroundColor #FFEBDC
[*] -> Begin
Begin -right-> Running : Succeeded
Begin --> [*] : Aborted
state Running {
  state "The game runneth" as long1
  long1 : Until you die
  long1 --> long1 : User interaction
  long1 --> keepGoing : stillAlive
  keepGoing --> long1
  long1 --> tooBadsoSad : killed
  tooBadsoSad --> Dead : failed
}
Dead --> [*] : Aborted
@enduml
```
1612041185 34 Cum se editeaza Markdown UML in Visual Studio Code.svg

** Alte formate pe care am încercat să le export doar folosind această extensie sunt HTML, care nu a reușit cu o eroare Java:

java.lang.UnsupportedOperationException: HTML

și PDF, care eșuează cu o eroare similară. Fără griji! Am soluții, așa cum se va arăta.

Funcționalități suplimentare

Există o altă extensie utilă de cod VS numită Previzualizare Markdown Îmbunătățită. Aceasta adaugă un al doilea panou de previzualizare în plus față de panoul de previzualizare nativ al codului VS.

Din anumite motive, două versiuni apar în panoul meu Extensie când l-am căutat; Am ales cel mai recent:

1612041185 2 Cum se editeaza Markdown UML in Visual Studio Code

Acum veți vedea două controale de previzualizare deasupra documentului Markdown:

1612041185 982 Cum se editeaza Markdown UML in Visual Studio Code
Prima pictogramă activează noul panou Markdown Preview Enhanced

Cu panoul deschis, puteți face clic dreapta pe acesta și exporta în diferite formate, cum ar fi HTML sau PDF.

Exportați în PDF

Markdown Preview Enhanced poate lucra cu browserul Chrome pentru a genera documente PDF, prin intermediul Păpușar conducător auto. Tot ce trebuie să faceți este să oferiți câteva materie frontală în reducerea dvs. care indică Puppeteer cum să aranjați PDF-ul:

---
puppeteer:
    landscape: true
    format: "letter"
    timeout: 3000 # <= wait 3 seconds before rendering in browser
---

# Overview
This walks through a few of use cases, linking them to "classes", which are either simple data objects or objects with methods. 

---
# UML Diagrams
...

Materia primă nu va apărea în panoul obișnuit de previzualizare a codului VS și nici în panoul de previzualizare îmbunătățit Markdown.

Pentru a exporta, faceți clic dreapta în panoul Markdown Preview Enhanced și selectați Chome (Puppeteer) -> PDF:

1612041185 141 Cum se editeaza Markdown UML in Visual Studio Code

Durează câteva secunde, dar PDF-ul va fi în cele din urmă generat și browserul dvs. implicit se va deschide (nu neapărat Chrome) cu documentul PDF afișat.


UML este un limbaj bogat și PlantUML suportă o mare parte din acesta, pe lângă unele diagrame non-UML. Nu trebuie să fiți un expert UML pentru a transmite idei prin diagrame, dar veți găsi diagramele mai ușor de modificat prin text decât printr-un instrument de desen. Mai mult decât atât, posibilitatea de a încorpora diagrame în documentația dvs. Markdown și de a o exporta în diferite formate este un mare plus.