js-sequence-diagrams语法大全：从基础到高级技巧
项目地址: https://gitcode.com/gh_mirrors/js/js-sequence-diagrams 你是否还在为绘制复杂的UML序列图而烦恼？是否觉得传统绘图工具操作繁琐、效率低下？本文将系统介绍js-sequence-diagrams的完整语法体系，从基础元素到高级技巧，助你轻松掌握文本绘制序列图的核心技能。读完本文，你将能够独立创建包含参与者、消息传递、注释说明的专业序列图，并根据实际需求定制图表样式。
快速入门：核心语法基础
js-sequence-diagrams采用简洁的文本描述方式生成SVG序列图，核心语法定义在src/grammar.ebnf中。最基础的序列图由参与者(Actor)和消息(Signal)构成，语法结构如下：
参与者A->参与者B: 消息内容
参与者B-->参与者A: 虚线回复
上述代码会生成两个参与者之间的消息传递关系。其中->表示实线箭头，-->表示虚线箭头，冒号后的文本为消息内容。完整语法规则定义在src/grammar.jison的第82-84行，支持多种消息类型和箭头样式组合。
参与者定义与管理
基本声明方式
参与者(Actor)是序列图的核心元素，默认情况下无需显式声明即可使用。但显式声明可以定义参与者别名和顺序，语法格式为：
participant 实际名称 as 显示别名
例如：
participant Alice as A
participant Bob as B
A->B: 发送消息
此语法在src/grammar.ebnf的第13行定义，允许为参与者设置更简洁的显示名称。
参与者高级特性
参与者名称支持包含空格的字符串，只需用引号包裹：
participant "System User" as User
User->Server: 登录请求
根据src/grammar.jison第30行规则，带引号的字符串会被正确解析为单个参与者名称。
消息类型与箭头样式
基础消息类型
js-sequence-diagrams支持多种消息类型，由不同的连接线和箭头组合表示：
| 语法 | 含义 | 实现代码 |
|---|---|---|
| A->B: 文本 | 实线实心箭头 | grammar.jison#L100-L106 |
| A-->B: 文本 | 虚线实心箭头 | grammar.jison#L100-L106 |
| A->>B: 文本 | 实线空心箭头 | grammar.jison#L100-L106 |
| A-->>B: 文本 | 虚线空心箭头 | grammar.jison#L100-L106 |
这些组合由src/grammar.jison中定义的linetype(第100-102行)和arrowtype(第104-106行)规则共同控制。
消息方向与层级
消息默认从左向右传递，通过参与者声明顺序控制布局。复杂交互可通过多层消息嵌套表示：
participant Client
participant Server
participant Database
Client->Server: 请求数据
Server->Database: 查询记录
Note right of Database: 执行SQL\nSELECT * FROM table
Database-->Server: 返回结果
Server-->Client: 响应数据
注释与说明
注释基本用法
注释(Note)用于在序列图中添加额外说明，支持三种定位方式：
note left of A: 左侧注释
note right of B: 右侧注释
note over A,B: 跨参与者注释
注释语法在src/grammar.ebnf第14-17行定义，支持单行和多行文本(使用\n换行)。
复杂注释场景
多行注释示例：
note over Client: 用户操作流程\n1. 点击按钮\n2. 填写表单\n3. 提交数据
跨多个参与者的注释：
note over Client,Server: 网络传输采用HTTPS加密
图表标题与全局设置
添加标题
使用title关键字为图表添加标题：
title: 用户登录流程时序图
participant User
participant System
User->System: 输入用户名密码
System-->User: 登录成功
标题语法在src/grammar.ebnf第12行定义，冒号可选。
实战案例：完整流程图
综合运用以上语法，我们可以创建复杂的交互流程：
title: 电子商务下单流程
participant Customer as C
participant Website as W
participant PaymentGateway as PG
participant Warehouse as WH
C->W: 浏览商品
C->W: 添加到购物车
Note right of W: 计算价格\n应用优惠
C->W: 提交订单
W->PG: 请求支付
Note over W,PG: 加密传输\n订单信息
PG-->W: 支付确认
W->WH: 发送发货通知
WH-->W: 确认发货
W-->C: 订单完成通知
高级应用：主题定制
js-sequence-diagrams支持主题定制，通过CSS样式修改图表外观。项目提供两种内置主题：
- simple: 简洁风格
- hand: 手绘风格
使用方法在README.md第59-60行说明，通过options参数指定主题：
var options = {theme: 'hand'};
d.drawSVG('diagram', options);
手绘主题需要加载额外的CSS文件src/sequence-diagram.css和字体文件fonts/daniel/danielbd.woff。
常见问题与解决方案
语法错误排查
- 消息必须包含冒号和内容，否则会导致解析错误
- 参与者名称中的特殊字符需要用引号包裹
- 注释必须指定位置(left of/right of/over)
布局优化技巧
- 通过participant声明控制参与者顺序
- 使用空行分隔逻辑段落，提高可读性
- 长消息使用\n手动换行，避免图表过宽
总结与扩展
js-sequence-diagrams提供了简洁而强大的语法，通过文本描述即可生成专业的序列图。核心语法定义在src/grammar.ebnf和src/grammar.jison中，支持参与者管理、消息传递、注释说明等完整功能。
项目官方文档README.md提供了详细的安装和使用指南，包括依赖库配置和主题定制方法。更多高级用法可参考测试目录中的示例test/gallery.html。
通过掌握本文介绍的语法和技巧，你可以高效创建清晰易懂的序列图，提升系统设计和沟通效率。建议收藏本文作为参考，关注项目更新获取更多功能。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
