SequenceDiagram
sequence-diagram按时间顺序画出参与者之间的调用、异步消息和返回
用法
基础用法
参与者从左到右排开,消息自上而下,数组顺序就是时间顺序。实线实心箭头是同步调用,实线开口箭头是异步消息,虚线开口箭头是返回;起点和终点相同时画成回环。注释和消息排在同一条时间轴上。
- 小程序用户端
- 认证服务
- 短信服务
- 小程序 发给 认证服务(同步调用):请求验证码
- 认证服务 发给 短信服务(异步消息):发送短信
- 注释(认证服务):同一手机号 60 秒内只发一次
- 认证服务 发给 小程序(返回):已发送
- 小程序 发给 认证服务(同步调用):提交验证码
- 认证服务 发给自己(同步调用):签发令牌
- 认证服务 发给 小程序(返回):登录成功
<SequenceDiagram
title="短信验证码登录"
participants={[
{ id: "app", label: "小程序", description: "用户端" },
{ id: "auth", label: "认证服务" },
{ id: "sms", label: "短信服务" },
]}
messages={[
{ id: "m1", from: "app", to: "auth", label: "请求验证码" },
{ id: "m2", from: "auth", to: "sms", label: "发送短信", kind: "async" },
{ id: "n1", type: "note", over: "auth", label: "同一手机号 60 秒内只发一次" },
{ id: "m3", from: "auth", to: "app", label: "已发送", kind: "reply" },
{ id: "m4", from: "app", to: "auth", label: "提交验证码" },
{ id: "m5", from: "auth", to: "auth", label: "签发令牌" },
{ id: "m6", from: "auth", to: "app", label: "登录成功", kind: "reply" },
]}
/>多参与者往返与逐步讲解
五个服务之间来回调用,minColumnWidth 调到 128 让五列在桌面上放得下。autoNumber 给消息加序号(注释不编号);activeId 高亮当前一步,读屏会读到它是当前步骤。over 传两个参与者时,注释横跨这两条生命线。
- 前端
- 订单服务
- 库存服务
- 支付服务
- 消息队列
- 1. 前端 发给 订单服务(同步调用):创建订单
- 2. 订单服务 发给 库存服务(同步调用):锁定库存
- 3. 库存服务 发给 订单服务(返回):已锁定
- 4. 订单服务 发给 支付服务(同步调用):生成支付单
- 5. 支付服务 发给 订单服务(返回):支付链接
- 6. 订单服务 发给 前端(返回):订单号与支付链接
- 注释(前端 与 支付服务 之间):用户在支付页完成付款
- 7. 支付服务 发给 订单服务(异步消息):支付成功回调
- 8. 订单服务 发给 库存服务(同步调用):扣减库存
- 9. 库存服务 发给 订单服务(返回):已扣减
- 10. 订单服务 发给 消息队列(异步消息):发布 order.paid
const [step, setStep] = useState(0);
<SequenceDiagram
title="下单与支付回调"
participants={participants}
messages={[
// …
{ id: "n1", type: "note", over: ["web", "pay"], label: "用户在支付页完成付款" },
{ id: "o7", from: "pay", to: "order", label: "支付成功回调", kind: "async" },
// …
]}
autoNumber
activeId={messages[step].id}
minColumnWidth={128}
/>
<Button onClick={() => setStep((s) => s + 1)}>下一步</Button>长名称与多行文案
名称和文案按列宽换行、撑高所在的行,不截断也不缩小字号;不带空格的长英文和 URL 也会断开。列放不下时整张图在自己的区域里横向滚动,此时它可以用 Tab 聚焦、用方向键滚动。
- 微信小程序(门店扫码下单入口)WeChat Mini Program
- OrderFulfillmentOrchestrationServicek8s · ns: fulfillment-prod
- 第三方物流平台开放接口网关
- 微信小程序(门店扫码下单入口) 发给 OrderFulfillmentOrchestrationService(同步调用):提交订单:12 个商品行、2 张优惠券、配送地址与期望送达时间段,附门店编号用于分账
- OrderFulfillmentOrchestrationService 发给自己(同步调用):重新计算分单策略:按仓库库存、距离和承运商时效综合打分,拆成 3 个包裹
- OrderFulfillmentOrchestrationService 发给 第三方物流平台开放接口网关(同步调用):POST /api/v2/fulfillment/orders/{orderId}/shipments?expand=items,packages,trackingEvents
- 注释(微信小程序(门店扫码下单入口) 与 第三方物流平台开放接口网关 之间):整条履约链路要求 3 秒内返回,超时转入异步补偿任务,由对账服务在 T+1 兜底
- 第三方物流平台开放接口网关 发给 OrderFulfillmentOrchestrationService(返回):运单号 SF1234567890123 与预计揽收时间
- 第三方物流平台开放接口网关 发给自己(异步消息):回写轨迹
- OrderFulfillmentOrchestrationService 发给 微信小程序(门店扫码下单入口)(返回):下单成功,展示 3 个包裹的物流信息
<SequenceDiagram
participants={[
{ id: "mini", label: "微信小程序(门店扫码下单入口)" },
{ id: "orch", label: "OrderFulfillmentOrchestrationService" },
{ id: "carrier", label: "第三方物流平台开放接口网关" },
]}
messages={[
{ id: "l3", from: "orch", to: "carrier", label: "POST /api/v2/fulfillment/orders/{orderId}/shipments?expand=…" },
{ id: "n1", type: "note", over: ["mini", "carrier"], label: "整条履约链路要求 3 秒内返回…" },
// …
]}
/>空数据与边界
没有消息时显示空态。重复的参与者 id、重复的消息 id、引用不存在的参与者,这些项都不画,开发环境会在控制台告警;用 validateSequence 可以拿到明细显示在图外。
没有消息
- 小程序用户端
- 认证服务
- 短信服务
暂无消息
只有一个参与者
- 定时任务
- 定时任务 发给自己(同步调用):扫描超时订单
- 注释(定时任务):每 5 分钟一次
- 定时任务 发给自己(异步消息):关闭并释放库存
无效数据
- 客户端
- 服务端
- 客户端 发给 服务端(同步调用):正常请求
- 服务端 发给 客户端(返回):正常返回
- 参与者 a 重复,第二个不成列
- 消息 x2 引用了不存在的参与者 ghost,不画
- 消息 x1 重复,第二条不画
<SequenceDiagram participants={participants} messages={[]} />
const issues = validateSequence(participants, messages);
// [{ code: "duplicate-participant", index: 2, id: "a" },
// { code: "unknown-participant", index: 1, id: "x2", ref: "ghost" },
// { code: "duplicate-item", index: 2, id: "x1" }]何时用
讲清楚「一次请求里谁先找谁」:登录、支付回调、审批流转、服务之间的调用链。参与者从左到右排开,消息自上而下。要拖拽编排节点用 Flow;只按时间列事件、不分参与者用 Timeline。
导入
import { SequenceDiagram, validateSequence } from "@hulianui/ui"
import type { SequenceParticipant, SequenceItem } from "@hulianui/ui"Props
继承 HTMLAttributes<HTMLElement>(不含 title),连同 ref 落在根 <figure> 上,它也是横向滚动容器。
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| participants * | SequenceParticipant[] | - | 参与者,按数组顺序从左到右 |
| messages * | SequenceItem[] | - | 消息与注释,按数组顺序自上而下。顺序就是时间,组件不重排、不看坐标 |
| title | string | 「时序图」 | 整张图的可访问名称 |
| autoNumber | boolean | false | 每条消息前显示序号(注释不编号),读屏也念序号 |
| activeId | string | null | - | 高亮当前这一步(消息或注释的 id),并标 aria-current="step" |
| minColumnWidth | number | 160 | 每列最小宽度(px)。容器放不下时图内横向滚动 |
数据类型
interface SequenceParticipant {
id: string; // 稳定 id,被消息和注释引用
label: string; // 列头名称,也是读屏念的名字
description?: string; // 列头第二行
}
interface SequenceMessage {
type?: "message"; // 可省略
id: string; // 稳定 id,activeId 靠它
from: string; // 发送方参与者 id
to: string; // 接收方参与者 id;与 from 相同即自调用
label: string;
kind?: "sync" | "async" | "reply"; // 默认 sync
}
interface SequenceNote {
type: "note";
id: string;
over: string | [string, string]; // 一个 id:贴在这条生命线上;两个 id:横跨这两条生命线
label: string;
}
type SequenceItem = SequenceMessage | SequenceNote;消息语义
| kind | 含义 | 画法 |
|---|---|---|
sync | 同步调用:发送方等着对方处理完 | 实线 + 实心三角箭头 |
async | 异步消息:发出去就不等了(投递、通知、回调) | 实线 + 开口箭头 |
reply | 返回:对之前某次调用的应答 | 虚线 + 开口箭头,文字颜色更淡 |
三种之间首先靠线型和箭头形状区分,颜色只是第二通道:同步用 primary、异步用 info、返回用 muted-foreground,注释用 warning-subtle 底 + warning-border 边,列头顶边用 primary。全部是语义令牌,明暗主题和运行时换肤自动跟随;去掉颜色(灰度打印、色弱)照样分得清。箭头指向接收方。
- 自调用(
from === to):画成从自己生命线出发、绕回自己的回环,不是普通的跨列箭头。回环在这一列右半边,文案借用右边一列(最右一列没得借,只有半列宽)。 - 注释:在时间轴上占自己的一行,位置就是它在数组里的位置。
over: "a"时贴在 a 的生命线上、宽度不超过这一列;over: ["a", "c"]时横跨 a 到 c,两端略越过生命线。注释不编号、没有箭头。
动效
只在挂载时播一次,不自动播放:
- 消息和注释按数组顺序依次淡入(每行错开 40ms,第 15 行之后不再往后错)。
- 箭头线从发送方一端伸到接收方,随后箭头头部出现——方向本身就是动画在讲的事。
activeId变化时,当前一步的高亮底色平滑过渡;若图在横向滚动且这一步不在视野里,图会自己横向滚过去(不动页面的纵向滚动)。- 系统开启「减弱动态效果」时,以上动画全部不播、滚动瞬时完成。
- 关键帧
hulian-sequence-in/hulian-sequence-draw在@hulianui/tokens的preset-core.css里。tokens 版本过旧找不到关键帧时,元素直接显示终态,不会卡在透明。
无效输入
组件不会把有问题的数据画到错的地方——这些项直接不画,开发环境在控制台告警(每种问题告警一次):
| 情况 | 处理 |
|---|---|
| 参与者 id 重复 | 第一次出现的成列,后面的不成列(不会多出一条空生命线) |
| 消息 / 注释 id 重复 | 第一条画,后面的不画 |
from / to / over 引用了不存在的参与者 | 这一条不画;序号跳过它,画出来的序号仍然连续 |
生产环境没有告警。要把问题展示给用户,用 validateSequence(participants, messages) 拿到 SequenceIssue[]({ code, index, id, ref? }),空数组表示全部可画。analyzeSequence 一次返回去重后的参与者、行和问题,layoutSequence 只返回行,二者都是纯函数。
没有可画的消息时显示「暂无消息」空态;没有参与者时连列头也不画。
窄屏
列宽不低于 minColumnWidth,名称和文案按列宽换行、撑高所在的行,不截断、不缩小字号;不带空格的长英文和 URL 也会在任意位置断开。列放不下时整张图在自己的区域里横向滚动,页面本身不横向溢出。此时图进入 Tab 顺序(有可见焦点环),聚焦后用方向键左右滚;宽度够、不需要滚动时它不占 Tab 焦点。手机上参与者建议不超过 3 个。
无障碍
- 根是带名称的
<figure>。参与者是<ul>,消息与注释同在一个<ol>里,按时间顺序朗读。 - 每条消息先念一段只给读屏看的前缀「小程序 发给 认证服务(同步调用):」,再念完整文案;自调用念「认证服务 发给自己(同步调用):」;注释念「注释(认证服务):」或「注释(小程序 与 短信服务 之间):」。
- 箭头、生命线、可见序号在
aria-hidden的装饰层里,同一信息不会念两遍。没有任何内容只放在 hover 提示里。 - 前缀文案跟随
ConfigProvider的语言。 - 自动化检查(axe、单测)覆盖了结构和名称;真实读屏器(VoiceOver / NVDA)的朗读体验仍需人工确认。
不支持
这是只读图,不包含:拖拽编排、循环 / 条件 / 可选等分组框(alt / loop / opt)、嵌套片段、激活条、消息点选、自动逐条播放(逐步讲解请自己用 activeId 驱动)、从文本(如 Mermaid)解析、导出图片。
禁忌 / 坑
- 不要靠坐标或时间戳排序——组件只认数组顺序,先排好再传。
- 一条消息跨的列越少,文案可用宽度越窄;很长的说明放进注释或图外。
- 最右一列的自调用文案只有半列宽,必要时调大
minColumnWidth或把那个参与者往左挪。 - 客户端组件:读
ConfigProvider的文案用到了 Context,还会量一次自己是否溢出,不能在 server 组件里当静态件用。
相关
Playground
- 小程序用户端
- 认证服务
- 短信服务
- 小程序 发给 认证服务(同步调用):请求验证码
- 认证服务 发给 短信服务(异步消息):发送短信
- 注释(认证服务):同一手机号 60 秒内只发一次
- 认证服务 发给 小程序(返回):已发送
- 小程序 发给 认证服务(同步调用):提交验证码
- 认证服务 发给自己(同步调用):签发令牌
- 认证服务 发给 小程序(返回):登录成功
<SequenceDiagram
participants={participants}
messages={messages}
/>