1. 安装

官方站点

  1. 需要 java 环境。
  2. 需要安装 [Graphviz] 依赖
  3. 下载 plantuml

2. 使用命令

planuml.jar 同级别文件夹建立 planuml.bat. 类 Unix 系统中使用 bash 即 .sh 脚本,或者创建 alias 别名。

添加内容

java -jar plantuml.jar -gui

执行后打开 .puml 为后缀的文件夹。

window 下使用 ansi 编码保存puml文件(默认的 txt 文档,修改 pu 为后缀)。

最新版本的 PlantUML 已经支持汉字,在创建文件的时候尽量使用 UTF-8 格式创建文本

3. 使用 VSCODE 来创建和预览

  1. 下载 vscode 编辑器。
  2. 打开扩展搜索 "jebbs.plantuml" 或者"plantuml",点击安装即可。或者访问 vscode PlantUML 插件 来安装。

该扩展内置了 plantuml.jar , 自动识别.wsd,.pu,.puml,.plantuml,.iuml文件,并配置高亮。
修改默认配置

  "plantuml.previewFileType": "svg",  // 预览文件,默认为 png
  "plantuml.exportFormat": "svg",     // 导出文件,默认为 png
  "plantuml.exportOutDirName": ".",   // 直接生成在文件当前目录
  "plantuml.exportSubFolder": false,  // 关闭使用子目录

使用 Alt + D 可以预览 png 格式的图片,修改配置, 具体可以使用 shift + comand + p 输入 uml 来查看。

该插件提供多种编译方式。

4. 脚本语法

puml 是脚本语言,分行是按照换行来识别语法的
一般的表达语句为

1.
节点  连接符号  节点
2.
关键字  节点或内容
3.
开始关键字
  内容
结束关键字

注意空格等非字符作为节点内容的使用,有些多关键字语句中需要使用双引号来讲包含空格的语句左右单个节点的存在

5. Activity Diagram 新版流程图

上面的流程图在修改节点的时候因为会自动寻找位置而导致会有所变动,导致一些不便。

新的语法(测试)兼容。

5.1. Simple Activity

新的语法是 : 节点 ; 结束。

@startuml

title act_new_1

:步骤一;
:此处有个支持简单的 mark 语法 **加粗字体**;

@enduml

5.2. Start/Stop 开始和结束

开始位置为 start 开始 , stop 停止 , end 结束.

@startuml
title act_new_2

start

:步骤一;
:mark 语法 **加粗字体**;

stop

@enduml

5.3. Conditional 条件语句

控制语句的使用,注意内容 () 的使用

@startuml

title act_new_3

start
if (是否已下载 graphviz?) then (是)
    :执行 \ndiagrams;
else (否)
    :需要下载 graphviz 后才能执行
    __activity__ diagrams;
endif
stop

@enduml

5.4. Repeat loop 循环处理(控制语句)

使用关键字 repeat, repeat while () 来实现

@startuml
title act_new_4

start

repeat
    :读取文件;
    :编译 diagrams;
repeat while (更多,执行下一个?)

stop
@enduml

5.5. While loop 循环控制

使用 while endwhile 循环控制

    @startuml
    title act_new_5

    start

    while (执行条件允许文件存在?)
      :读取文件;
      :编译 diagrams;
    endwhile

    stop

    @enduml

可以追加标签

@startuml
title act_new_6
start
:打开文件;
while (检查文件大小 ?) is (有内容)
    :读取文件;
    :编译 dia;
endwhile (空)
:关闭文件;
end
@enduml

5.6. Parallel processing 并行处理

使用 fork 关键字创建并行处理

@startuml
title act_new_7

start

if (multiprocessor?) then (yes)
  fork
    :Treatment 1;
  fork again
    :Treatment 2;
  end fork
else (monoproc)
  :Treatment 1;
  :Treatment 2;
endif

@enduml

5.7. Notes 注释

和旧版基本相同,单行注释使用 note right|left 内容,注意后面没有分号。而多行注释依旧使用 note right|left 换行 内容 换行 end note的方式处理。

@startuml

title act_new_8

start
: 步骤1;
note left: This is a __NOTE__
: 步骤2;
note right
    支持 mark 编辑语法
    This note is on several
    //lines// and can
    contain <b>HTML</b>
    ====
    * Calling the method ""foo()"" is prohibited
end note
stop

@enduml

注意 mark 并非 Markdown 语法,以案例为 b

5.8. Color 颜色

在冒号钱可以追加 #十六进制 的颜色编号或者名称。

@startuml
title act_new_9
start
:进程开始;
#red:试着读取文件
文件必须有可写权限!;
#AAAAAA:结束进程;
stop
@enduml

5.9. Complete example 案例

@startuml
title act_new_10

start
:ClickServlet.handleRequest();
:new page;
if (Page.onSecurityCheck) then (true)
    #7c7c7c:Page.onInit();
    if (isForward?) then (no)
    #red:Process controls;
    if (continue processing?) then (no)
        stop
    endif

    if (isPost?) then (yes)
        :Page.onPost();
    else (no)
        :Page.onGet();
    endif
    :Page.onRender();
    endif
else (false)
endif

if (do redirect?) then (yes)
    :redirect process;
else
    if (do forward?) then (yes)
    :Forward request;
    else (no)
    :Render page template;
    endif
endif

stop

@enduml

6. 流程图 (旧版)

流程图语法在开始位置必须为 节点 --> 节点, 使用 (*) 来标识开始和结束。
内部则可以 使用 --> 节点

节点是具有唯一性的,当流程中出现节点名称相同的时候会产生混乱, 所以在写 uml 的时候注意保证节点的唯一性

6.1. 开始与结束

@startuml

title act_1

(*) --> "文档  内容"
--> (*)
@enduml

例子_1

6.2. 进程节点

在箭头后追加 [标签内容] 可以放置标签。
--> 中间可以通过 up,down,left,right 来人为控制箭头的方向。

@startuml

title act_2

(*)-->"开始"
-->  "节点名称"
-->[箭头的注释]  "节点名称0"
-up->  "节点名称1"
-down->  "节点名称2"
-left->  "节点名称3"
-right->  "节点名称4"
-->(*)
@enduml

注意在内容 -right-> 可以定义方向

例子_2

6.3. 条件语句(控制流程)

使用 if 条件 then \n elseendif 写控制语句。

@startuml

title act_3

(*)->1
if  "介绍" then
    -->[true] "真"
else
    -->[false] "真"
endif
->(*)
@enduml

6.4. 注释

单行注释

note right:  右侧的内容
note left:  右侧的内容

多行注释

note right:
多行内容
endnote

6.5. 分区

@startuml

title act_4

(*) --> 开始
partition "分区名称" {
    --> "基本节点"
}
--> (*)

@enduml

6.6. Parallel processing 并行处理

使用 ===标记===, 来处理, 重新从某位置开始的时候使用 ===标记=== --> 节点 重新开始

@startuml
title act_5

(*) -->内容

--> ===B1===
--> "Parallel Activity 1"
--> ===B2===

===B1=== --> "Parallel Activity 2"
--> ===B2===

--> (*)

@enduml

6.7. 综合案例

@startuml

title act_6

(*) --> "ClickServlet.handleRequest()"
--> "new Page"

if "Page.onSecurityCheck" then
  ->[true] "Page.onInit()"

  if "isForward?" then
   ->[no] "Process controls"

   if "continue processing?" then
     -->[yes] ===RENDERING===
   else
     -->[no] ===REDIRECT_CHECK===
   endif

  else
   -->[yes] ===RENDERING===
  endif

  if "is Post?" then
    -->[yes] "Page.onPost()"
    --> "Page.onRender()" as render
    --> ===REDIRECT_CHECK===
  else
    -->[no] "Page.onGet()"
    --> render
  endif

else
  -->[false] ===REDIRECT_CHECK===
endif

if "Do redirect?" then
 ->[yes] "redirect request"
 --> ==BEFORE_DESTROY===
else
 if "Do Forward?" then
  -left->[yes] "Forward request"
  --> ==BEFORE_DESTROY===
 else
  -right->[no] "Render page template"
  --> ==BEFORE_DESTROY===
 endif
endif

--> "Page.onDestroy()"
-->(*)

@enduml

7. Sequence Diagram 时序图

基本语法

  1. 使用 节点 -> 节点: 描述 -> 为实线
  2. 如果使用虚线则 用 -->
  3. 箭头的方向可以是双向的 节点 <-- 节点
@startuml

title seq_1

用户 -> 平台: 发送登录请求
平台 --> 用户: 验证通过
用户 -> 平台: 另一个请求
用户 <-- 平台: 返回验证消息
@enduml

7.1. Comments 注释

内部注释使用 ' 单引号来开始 单行注释, 多行注释则使用 /''/ 包括

7.2. Declaring participant (角色)

提供了的声明参加者(角色),来丰富图形, 默认情况下在箭头两边的已经隐式声明了(participant),也可以使用 participant 节点 来显示声明角色,这种状况主要是为了声明角色的顺序。

  • actor
  • boundary
  • control
  • entity
  • database
@startuml
title seq_2

actor Foo1
boundary Foo2
control Foo3
entity Foo4
database Foo5
Foo1 -> Foo2 : To boundary
Foo1 -> Foo3 : To control
Foo1 -> Foo4 : To entity
Foo1 -> Foo5 : To database

@enduml

追加色彩案例

@startuml
title seq_3

actor 客户 #red
' 声明角色的时候在后面可以追加颜色
' 注释内容并不会显示
' The only difference between actor
' and participant is the drawing

participant 服务端
participant "I have a really\nlong name" as L #99FF99
/'  这里使用 `as` 关键字声明了 L 来作为别名
    你也可以这样写:
    participant L as "I have a really\nlong name"  #99FF99
    '/

服务端->客户: 请求认证
客户->服务端: Authentication Response
客户->L: Log transaction
@enduml

7.3. Use non-letters in participants 非字符处理

在声明非字母的角色的时候使用双引号处理。(包含空格)

@startuml
title seq_4

服务端 -> "客户()" : Hello
"客户()" -> "This is very\nlong" as Long
' You can also declare:
' "客户()" -> Long as "This is very\nlong"
Long --> "客户()" : ok
@enduml

7.4. Message to Self

在介绍过长的内容的时候使用 \n 来换行。

@startuml
title seq_5
服务端->服务端: This is a signal to self.\nIt also demonstrates\nmultiline \ntext
@enduml

7.5. Change arrow style 箭头样式

在时序图中可以使用多种样式,基于下面的案例,来替换默认的箭头。

总体来说 - 表示实线, -- 标识虚线
而在在两边的标识箭头的方向和样式

@startuml
title seq_6

客户 -> 服务端
客户 ->> 服务端
客户 -\ 服务端
客户 \\- 服务端
客户 //-- 服务端

客户 ->o 服务端
客户 o\\-- 服务端

客户 <-> 服务端
客户 <->o 服务端
@enduml

7.6. Change arrow color 箭头色彩

两种方式追加箭头色彩

  1. 实线样式为在箭头和线使用 [#颜色值] 来设定色彩
  2. 虚线样式为在虚线中间使用 [#颜色值] 来设定色彩
@startuml
title seq_7

客户 -[#red]> 服务端 : hello
服务端 -[#0000FF]->客户 : ok
@enduml

7.7. Message sequence numbering 计数

使用关键字 autonumber 来自动为消息生成索引数字

    @startuml
    title seq_8

    autonumber
    客户 -> 服务端 : 请求认证
    客户 <- 服务端 : Authentication Response
    @enduml

autonumber 后可以设定 开始位置 梯度 参数.
在默认情况下 autonumber 自动追加了 start 参数, 在使用 stop 参数可以停止计数.

    @startuml
    title seq_9
    autonumber
    客户 -> 服务端 : 请求认证
    客户 <- 服务端 : Authentication Response
    autonumber stop

    客户 <- 服务端 : 停止

    autonumber 15
    客户 -> 服务端 : Another 请求认证
    客户 <- 服务端 : Another authentication Response

    autonumber 40 10
    客户 -> 服务端 : Yet another 请求认证
    客户 <- 服务端 : Yet another authentication Response

    @enduml

你也可以对数字进行格式化输出, 为 autonumber 追加格式化使用单引号 "格式" ,内部可以使用 HTML 标记。 可以参看后面的 Formatting using HTML 。

    @startuml
    title seq_10
    autonumber "<b>[000]</b>"
    客户 -> 服务端 : 请求认证
    客户 <- 服务端 : Authentication Response

    autonumber 15 "<b>(<u>###</u>)"
    客户 -> 服务端 : Another 请求认证
    客户 <- 服务端 : Another authentication Response

    autonumber 40 10 "<font color=red><b>Message 0  "
    客户 -> 服务端 : Yet another 请求认证
    客户 <- 服务端 : Yet another authentication Response

    @enduml

上面例子可以看出 使用的是 html 标记 <b> 标识加粗 , <u> 标识下划线, 而写法有 单标签<b> 和 封闭标签 <b></b> 两种标记方式。 000 表示数字格式,位置不足则补 0 ### 表示数字或空

7.8. Splitting diagrams 分割为多个图形

关键字 newpage 可以将同一张图形分割为多个图。 可以追加 标题参数。

    @startuml
    title seq_11

    服务端 -> 客户 : message 1
    服务端 -> 客户 : message 2

    newpage

    服务端 -> 客户 : message 3
    服务端 -> 客户 : message 4

    newpage 第三章的标题\n最后一页

    服务端 -> 客户 : message 5
    服务端 -> 客户 : message 6
    @enduml

7.9. Grouping message 分组消息

提供了一下几组关键词

  • alt/else
  • opt
  • loop
  • par
  • break
  • critical
  • group, followed by a text to be displayed

关键词后可以追加文本,来作为副标题。
使用 end 关键词来表示结束。

    @startuml
    title seq_12

    服务端 -> 客户: 请求认证

    alt 成功

        客户 -> 服务端: 许可认证

    else 可识别的正常失败

        客户 -> 服务端: 认证失败
        group 组名称
            服务端 ->  日志:  attack start
            loop 1000 times
                服务端 -> 客户: DNS Attack
            end
            服务端 ->  日志: Log attack end
        end

    else  其他失败

       客户 -> 服务端: 重新请求

    end
    @enduml

7.10. Notes on messages

单行注释

note right:  右侧的内容
note left:  右侧的内容

多行注释

note right:
多行内容
end note
@startuml
title seq_13

服务端->客户 : hello
note left: this is a first note

客户->服务端 : ok
note right: this is another note

客户->客户 : I am thinking
note left
    a note
    can also be defined
    on several lines
end note
@enduml

7.11. Some other notes

of, over 后跟上角色(参与者),可以管理。
其中 over 可以覆盖在线上。

    @startuml
    title seq_14

    participant 服务端
    participant 客户
    note left of 服务端 #aqua
        显示
        左侧 of 服务端.
    end note

    note right of 服务端: 显示在右侧 of 服务端.

    note over 服务端: over 注释覆盖在服务端.

    note over 服务端, 客户 #FFAAAA: 注释\n 覆盖在 客户 和 服务端.

    note over 客户, 服务端
        This is yet another
        example of
        a long note.
    end note
    @enduml

7.12. Formatting using HTML

使用类 html-tag:

  • <b> 来加粗字体
  • <u> or <u:#AAAAAA> or <u:colorName> 输出下划线
  • <i> 斜体字输出
  • <s> or <s:#AAAAAA> or <s:colorName> for strike text
  • <w> or<w:#AAAAAA>or<w:colorName>` for wave underline text
  • <color:#AAAAAA> or <color:colorName>
  • <back:#AAAAAA> or <back:colorName> for background color
  • `size:nn to change font size
  • <img src="file"> or <img:file> : the file must be accessible by the filesystem
  • <img src="http://url"> or <img:http://url> : the URL must be available from the Internet

example

    @startuml
    title seq_15

    participant 服务端
    participant "The <b>Famous</b> 客户" as 客户

    服务端 -> 客户 : A <i>well formated</i> message
    note right of 服务端
     This is <back:cadetblue><size:18>displayed</size></back>
     <u>left of</u> 服务端.
    end note
    note left of 客户
     <u:red>This</u> is <color #118888>displayed</color>
     <b><color purple>left of</color> <s:red>服务端</strike> 客户</b>.
    end note
    note over 服务端, 客户
     <w:#FF33FF>This is hosted</w> by <img http://s.plantuml.com/logoc.png>
    end note

    @enduml

更多的方式查看 官方文档

7.13. Divider

If you want, you can split a diagram using == separator to divide your diagram into logical steps.

    @startuml
    title seq_16

    == Initialisation ==

    服务端 -> 客户: 请求认证
    客户 --> 服务端: Authentication Response

    == Repetition ==

    服务端 -> 客户: Another 请求认证
    服务端 <-- 客户: another authentication Response

    @enduml

7.14. Reference

You can use reference in a diagram, using the keyword ref over.

    @startuml
    title seq_17

    participant 服务端
    actor 客户

    ref over 服务端, 客户 : init

    服务端 -> 客户 : hello

    ref over 客户
      This can be on
      several lines
    end ref
    @enduml

7.15. Delay

You can use ... to indicate a delay in the diagram. And it is also possible to put a message with this delay.

    @startuml

    title seq_18
    服务端 -> 客户: 请求认证
    ...
    客户 --> 服务端: Authentication Response
    ...5 minutes latter...
    客户 --> 服务端: Bye !

    @enduml

7.16. Space

对消息使用空行 |||, 也可以自己定义像素高度 ||数字||

    @startuml
    title seq_19

    服务端 -> 客户: message 1
    客户 --> 服务端: ok
    |||
    服务端 -> 客户: message 2
    客户 --> 服务端: ok
    ||45||
    服务端 -> 客户: message 3
    客户 --> 服务端: ok

    @enduml

7.17. Lifeline Activation and Destruction 生命周期

使用 activate 角色 表示开始生命周期,使用 destory 角色 标识结束周期。开始和结束必须成对的存在。

    @startuml
    title seq_20

    participant User

    User -> A: DoWork
    activate A

    A -> B: << createRequest >>
    activate B

    B -> C: DoWork
    activate C
    C --> B: WorkDone
    destroy C

    B --> A: RequestCreated
    deactivate B

    A -> User: Done
    deactivate A

    @enduml

为进程的生命周期进行标记色彩 ,可以追加色彩参数, 在 plantuml 中色彩使用 #十六进制的色彩值 来表示。

    @startuml
    title seq_21
    participant User

    User -> A: DoWork
    activate A #FFBBBB

    A -> A: Internal call
    activate A #DarkSalmon

    A -> B: << createRequest >>
    activate B

    B --> A: RequestCreated
    deactivate B
    deactivate A
    A -> User: Done
    deactivate A

    @enduml

7.18. Participant creation

You can use the create keyword just before the first reception of a message to emphasize the fact that this message is actually creating this new object.

    @startuml
    客户 -> 服务端 : hello

    create Other
    服务端 -> Other : new

    create control String
    服务端 -> String
    note right : You can also put notes!

    服务端 --> 客户 : ok

    @enduml

7.19. Incoming and outgoing messages

You can use incoming or outgoing arrows if you want to focus on a part of the diagram. Use square brackets to denotate the left "[" or the right "]" side of the diagram.

    @startuml
    [-> A: DoWork

    activate A

    A -> A: Internal call
    activate A

    A ->] : << createRequest >>

    A<--] : RequestCreated
    deactivate A
    [<- A: Done
    deactivate A
    @enduml

7.20. Stereotypes and Spots

It is possible to add stereotypes to participants using << and >>. In the stereotype, you can add a spotted character in a colored circle using the syntax (X,color).

    @startuml

    participant "Famous 客户" as 客户 << Generated >>
    participant 服务端 << (C,#ADD1B2) Testable >>

    客户->服务端: First message

    @enduml

或者

    @startuml

    participant 客户 << (C,#ADD1B2) >>
    participant 服务端 << (C,#ADD1B2) >>

    客户->服务端: First message

    @enduml

7.21. More information on titles

You can use some HTML tags in the title.

    @startuml

    title <u>Simple</u> communication example

    服务端 -> 客户: 请求认证
    客户 -> 服务端: Authentication Response

    @enduml

You can add newline using \n in the title description.

    @startuml

    title <u>Simple</u> communication example\non several lines

    服务端 -> 客户: 请求认证
    客户 -> 服务端: Authentication Response

    @enduml

You can also define title on several lines using title and end title keywords.

    @startuml

    title
     <u>Simple</u> communication example
     on <i>several</i> lines and using <font color=red>html</font>
     This is hosted by <img:sourceforge.jpg>
    end title

    服务端 -> 客户: 请求认证
    客户 -> 服务端: Authentication Response

    @enduml

7.22. Participants englober

It is possible to draw a box arround some participants, using box and end box commands. You can add an optional title or a optional background color, after the box keyword.

    @startuml

    box "Internal Service" #LightBlue
        participant 客户
        participant 服务端
    end box
    participant Other

    客户 -> 服务端 : hello
    服务端 -> Other : hello

    @enduml

You can use the hide footbox keywords to remove the footer of the diagram.

    @startuml

    hide footbox
    title Footer removed

    服务端 -> 客户: 请求认证
    客户 --> 服务端: Authentication Response

    @enduml

Skinparam

You can use the skinparam command to change colors and fonts for the drawing. You can use this command :

In the diagram definition, like any other commands, In an included file, In a configuration file, provided in the command line or the ANT task.

    @startuml
    skinparam backgroundColor #EEEBDC

    skinparam sequence {
        ArrowColor DeepSkyBlue
        ActorBorderColor DeepSkyBlue
        LifeLineBorderColor blue
        LifeLineBackgroundColor #A9DCDF

        ParticipantBorderColor DeepSkyBlue
        ParticipantBackgroundColor DodgerBlue
        ParticipantFontName Impact
        ParticipantFontSize 17
        ParticipantFontColor #A9DCDF

        ActorBackgroundColor aqua
        ActorFontColor DeepSkyBlue
        ActorFontSize 17
        ActorFontName Aapex
    }

    actor User
    participant "First Class" as A
    participant "Second Class" as B
    participant "Last Class" as C

    User -> A: DoWork
    activate A

    A -> B: Create Request
    activate B

    B -> C: DoWork
    activate C
    C --> B: WorkDone
    destroy C

    B --> A: Request Created
    deactivate B

    A --> User: Done
    deactivate A

    @enduml