Back to Details

plantuml-ascii

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PlantUML ASCII Art Diagram Generator

PlantUML ASCII艺术图生成器

Overview

概述

Create text-based ASCII art diagrams using PlantUML. Perfect for documentation in terminal environments, README files, emails, or any scenario where graphical diagrams aren't suitable.
使用PlantUML创建基于文本的ASCII艺术图。非常适合终端环境、README文件、电子邮件或任何不适合使用图形图的场景中的文档编写。

What is PlantUML ASCII Art?

什么是PlantUML ASCII艺术图？

PlantUML can generate diagrams as plain text (ASCII art) instead of images. This is useful for:
  • Terminal-based workflows
  • Git commits/PRs without image support
  • Documentation that needs to be version-controlled
  • Environments where graphical tools aren't available
PlantUML可以生成纯文本（ASCII艺术图）格式的图，而非图片。这在以下场景中非常有用：
  • 基于终端的工作流
  • 不支持图片的Git提交/PR
  • 需要版本控制的文档
  • 无法使用图形工具的环境

Installation

安装

bash
undefined
bash
undefined

macOS

macOS

brew install plantuml
brew install plantuml

Linux (varies by distro)

Linux (因发行版而异)

sudo apt-get install plantuml # Ubuntu/Debian sudo yum install plantuml # RHEL/CentOS
sudo apt-get install plantuml # Ubuntu/Debian sudo yum install plantuml # RHEL/CentOS

Or download JAR directly

或直接下载JAR包

wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar
undefined
wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar
undefined

Output Formats

输出格式

FlagFormatDescription
-txt
ASCIIPure ASCII characters
-utxt
Unicode ASCIIEnhanced with box-drawing characters
标志格式说明
-txt
ASCII纯ASCII字符
-utxt
Unicode ASCII使用方框绘制字符增强显示

Basic Workflow

基本工作流

1. Create PlantUML Diagram File

1. 创建PlantUML图文件

plantuml
@startuml
participant Bob
actor Alice

Bob -> Alice : hello
Alice -> Bob : Is it ok?
@enduml
plantuml
@startuml
participant Bob
actor Alice

Bob -> Alice : hello
Alice -> Bob : Is it ok?
@enduml

2. Generate ASCII Art

2. 生成ASCII艺术图

bash
undefined
bash
undefined

Standard ASCII output

标准ASCII输出

plantuml -txt diagram.puml
plantuml -txt diagram.puml

Unicode-enhanced output (better looking)

Unicode增强输出（视觉效果更好）

plantuml -utxt diagram.puml
plantuml -utxt diagram.puml

Using JAR directly

直接使用JAR包

java -jar plantuml.jar -txt diagram.puml java -jar plantuml.jar -utxt diagram.puml
undefined
java -jar plantuml.jar -txt diagram.puml java -jar plantuml.jar -utxt diagram.puml
undefined

3. View Output

3. 查看输出

Output is saved as 
diagram.atxt
(ASCII) or 
diagram.utxt
(Unicode).
输出将保存为
diagram.atxt
（ASCII格式）或
diagram.utxt
（Unicode格式）。

Diagram Types Supported

支持的图类型

Sequence Diagram

序列图

plantuml
@startuml
actor User
participant "Web App" as App
database "Database" as DB

User -> App : Login Request
App -> DB : Validate Credentials
DB --> App : User Data
App --> User : Auth Token
@enduml
plantuml
@startuml
actor User
participant "Web App" as App
database "Database" as DB

User -> App : Login Request
App -> DB : Validate Credentials
DB --> App : User Data
App --> User : Auth Token
@enduml

Class Diagram

类图

plantuml
@startuml
class User {
  +id: int
  +name: string
  +email: string
  +login(): bool
}

class Order {
  +id: int
  +total: float
  +items: List
  +calculateTotal(): float
}

User "1" -- "*" Order : places
@enduml
plantuml
@startuml
class User {
  +id: int
  +name: string
  +email: string
  +login(): bool
}

class Order {
  +id: int
  +total: float
  +items: List
  +calculateTotal(): float
}

User "1" -- "*" Order : places
@enduml

Activity Diagram

活动图

plantuml
@startuml
start
:Initialize;
if (Is Valid?) then (yes)
  :Process Data;
  :Save Result;
else (no)
  :Log Error;
  stop
endif
:Complete;
stop
@enduml
plantuml
@startuml
start
:Initialize;
if (Is Valid?) then (yes)
  :Process Data;
  :Save Result;
else (no)
  :Log Error;
  stop
endif
:Complete;
stop
@enduml

State Diagram

状态图

plantuml
@startuml
[*] --> Idle
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> [*]
Error --> Idle : retry
@enduml
plantuml
@startuml
[*] --> Idle
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> [*]
Error --> Idle : retry
@enduml

Component Diagram

组件图

plantuml
@startuml
[Client] as client
[API Gateway] as gateway
[Service A] as svcA
[Service B] as svcB
[Database] as db

client --> gateway
gateway --> svcA
gateway --> svcB
svcA --> db
svcB --> db
@enduml
plantuml
@startuml
[Client] as client
[API Gateway] as gateway
[Service A] as svcA
[Service B] as svcB
[Database] as db

client --> gateway
gateway --> svcA
gateway --> svcB
svcA --> db
svcB --> db
@enduml

Use Case Diagram

用例图

plantuml
@startuml
actor "User" as user
actor "Admin" as admin

rectangle "System" {
  user -- (Login)
  user -- (View Profile)
  user -- (Update Settings)
  admin -- (Manage Users)
  admin -- (Configure System)
}
@enduml
plantuml
@startuml
actor "User" as user
actor "Admin" as admin

rectangle "System" {
  user -- (Login)
  user -- (View Profile)
  user -- (Update Settings)
  admin -- (Manage Users)
  admin -- (Configure System)
}
@enduml

Deployment Diagram

部署图

plantuml
@startuml
actor "User" as user
node "Load Balancer" as lb
node "Web Server 1" as ws1
node "Web Server 2" as ws2
database "Primary DB" as db1
database "Replica DB" as db2

user --> lb
lb --> ws1
lb --> ws2
ws1 --> db1
ws2 --> db1
db1 --> db2 : replicate
@enduml
plantuml
@startuml
actor "User" as user
node "Load Balancer" as lb
node "Web Server 1" as ws1
node "Web Server 2" as ws2
database "Primary DB" as db1
database "Replica DB" as db2

user --> lb
lb --> ws1
lb --> ws2
ws1 --> db1
ws2 --> db1
db1 --> db2 : replicate
@enduml

Command-Line Options

命令行选项

bash
undefined
bash
undefined

Specify output directory

指定输出目录

plantuml -txt -o ./output diagram.puml
plantuml -txt -o ./output diagram.puml

Process all files in directory

处理目录中的所有文件

plantuml -txt ./diagrams/
plantuml -txt ./diagrams/

Include dot files (hidden files)

包含点文件（隐藏文件）

plantuml -txt -includeDot diagrams/
plantuml -txt -includeDot diagrams/

Verbose output

详细输出

plantuml -txt -v diagram.puml
plantuml -txt -v diagram.puml

Specify charset

指定字符集

plantuml -txt -charset UTF-8 diagram.puml
undefined
plantuml -txt -charset UTF-8 diagram.puml
undefined

Ant Task Integration

Ant任务集成

xml
<target name="generate-ascii">
  <plantuml dir="./src" format="txt" />
</target>

<target name="generate-unicode-ascii">
  <plantuml dir="./src" format="utxt" />
</target>
xml
<target name="generate-ascii">
  <plantuml dir="./src" format="txt" />
</target>

<target name="generate-unicode-ascii">
  <plantuml dir="./src" format="utxt" />
</target>

Tips for Better ASCII Diagrams

优化ASCII图的技巧

  1. Keep it simple: Complex diagrams don't render well in ASCII
  2. Short labels: Long text breaks ASCII alignment
  3. Use Unicode (
    -utxt
    )    : Better visual quality with box-drawing chars
  4. Test before sharing: Verify in terminal with fixed-width font
  5. Consider alternatives: For complex diagrams, use Mermaid.js or graphviz
  1. 保持简洁：复杂图在ASCII格式下显示效果不佳
  2. 使用短标签：长文本会破坏ASCII的对齐效果
  3. 使用Unicode（
    -utxt
    ）    ：通过方框绘制字符获得更好的视觉效果
  4. 分享前测试：在使用等宽字体的终端中验证显示效果
  5. 考虑替代方案：对于复杂图，可使用Mermaid.js或graphviz

Example Output Comparison

示例输出对比

Standard ASCII (
-txt
):
     ,---.          ,---.
     |Bob|          |Alice|
     `---'          `---'
      |   hello      |
      |------------->|
      |              |
      |  Is it ok?   |
      |<-------------|
      |              |
Unicode ASCII (
-utxt
):
┌─────┐        ┌─────┐
│ Bob │        │Alice│
└─────┘        └─────┘
  │   hello      │
  │─────────────>│
  │              │
  │  Is it ok?   │
  │<─────────────│
  │              │
标准ASCII（
-txt
）:
     ,---.          ,---.
     |Bob|          |Alice|
     `---'          `---'
      |   hello      |
      |------------->|
      |              |
      |  Is it ok?   |
      |<-------------|
      |              |
Unicode ASCII（
-utxt
）:
┌─────┐        ┌─────┐
│ Bob │        │Alice│
└─────┘        └─────┘
  │   hello      │
  │─────────────>│
  │              │
  │  Is it ok?   │
  │<─────────────│
  │              │

Quick Reference

快速参考

bash
undefined
bash
undefined

Create sequence diagram in ASCII

创建ASCII格式的序列图

cat > seq.puml << 'EOF' @startuml Alice -> Bob: Request Bob --> Alice: Response @enduml EOF
plantuml -txt seq.puml cat seq.atxt
cat > seq.puml << 'EOF' @startuml Alice -> Bob: Request Bob --> Alice: Response @enduml EOF
plantuml -txt seq.puml cat seq.atxt

Create with Unicode

创建Unicode格式的图

plantuml -utxt seq.puml cat seq.utxt
undefined
plantuml -utxt seq.puml cat seq.utxt
undefined

Troubleshooting

故障排除

Problem: Garbled Unicode characters
  • Solution: Ensure terminal supports UTF-8 and has proper font
Problem: Diagram looks misaligned
  • Solution: Use fixed-width font (Courier, Monaco, Consolas)
Problem: Command not found
  • Solution: Install PlantUML or use Java JAR directly
Problem: Output file not created
  • Solution: Check file permissions, ensure PlantUML has write access
问题：Unicode字符显示乱码
  • 解决方案：确保终端支持UTF-8并使用合适的字体
问题：图显示对齐错误
  • 解决方案：使用等宽字体（Courier、Monaco、Consolas）
问题：命令未找到
  • 解决方案：安装PlantUML或直接使用Java JAR包
问题：未生成输出文件
  • 解决方案：检查文件权限，确保PlantUML有写入权限