ratatui-flow
中文 | English
ratatui 的节点图 / 流程图 widget —— 在终端里布局“框 + 箭头”的有向无环图(DAG),支持连接线自动布线、节点按内容自适应尺寸,以及结构化的诊断信息。
╭src────────────╮ ╭parse───────╮ ╭xform─────────────╮
│Source ├──┬─────┥Parse ╞═════╡Transform ├──╮
│/data/input.csv│ │ │header row ├─╮╭──┤normalize -> [0,1]│ │
╰───────────────╯ │ ╰────────────╯ ││ ╰──────────────────╯ │
│ ╭valid──────────╮ ││ │
╰──┤Validate ├─│╯ ╰── ...
╰───────────────╯
特性
- 自动布局 节点图(DAG):放置节点、避免重叠、布线连接。
- 连接自动布线:基于网格搜索,每条连接可单独设置线型 / 颜色 / 样式。
- 节点按内容自适应尺寸:
NodeLayout::from_content按文本显示宽度计算(通过unicode-width,正确处理 CJK / emoji 等宽字符)。 - 优雅降级:环、越界的节点引用、过小的画布都不会 panic,而是优雅处理并通过
Diagnostic上报。 - 最小化、封闭的公共 API:
NodeGraph、NodeGraphView、Viewport、NodeLayout、Connection、LineType(外加Diagnostic);内部布局类型不对外暴露。 - 原生视口 / 滚动:图在
calculate()时一次性渲染到离屏 canvas,之后用NodeGraphView(blit 滚动窗口)+split_viewport(拿节点内容的屏幕坐标 rect)即可平移/滚动,无需每帧重算布局。
快速开始
Cargo.toml:
[]
= { = "0.30", = false }
= "0.1"
use Paragraph;
use ;
let nodes = vec!;
// from/to 用稳定身份 NodeId/PortId(usize 可 .into() 隐式转换)
let conns = vec!;
let mut graph = new;
graph.calculate;
// 上报非致命问题(不可达节点、布线失败……)
for d in graph.diagnostics
用 ratatui 渲染:
// zones[i] 是第 i 个节点的内部内容区域
let zones = graph.split;
for in zones.into_iter.enumerate
f.render_stateful_widget;
示例
viewport 演示了库原生的视口 API:NodeGraphView(blit 滚动后的边框/端口/连线)+ split_viewport(拿节点内容的屏幕坐标 rect)。整张图在 calculate() 时渲染到离屏 canvas 一次,之后滚动只是改 Viewport 的 offset。操作:hjkl / 方向键滚动、PgUp/PgDn、Home、q/Esc 退出。
视口 / 滚动
当图比屏幕大时,用库原生的视口 API。整张图(边框/端口/连线,不含节点内容)在 calculate() 时一次性渲染到内部离屏 canvas;之后每帧只需:
split_viewport(area, &viewport)拿到每个节点内容的屏幕坐标 rect(已按 offset 平移并裁剪到area;不可见为 0×0);- 渲染
NodeGraphView(把 canvas 的可见窗口按 offset blit 到屏幕)。
use ;
use ;
// 图比屏幕大;calculate() 时整图画到离屏 canvas 一次
let mut graph = new;
graph.calculate;
let mut viewport = new; // offset = (0, 0)
// ... 事件循环里按方向键改 viewport.offset.0 / .1 ...
// 每帧:
let zones = graph.split_viewport;
for in zones.iter.enumerate
f.render_widget; // 边框/连线
NodeGraphView 持有 &graph,所以不需要每帧 clone 图;布局/布线从不重算。
诊断
calculate() 之后调用 graph.diagnostics() 获取 &[Diagnostic]:
| 变体 | 含义 |
|---|---|
UnplacedNode { node } |
节点从任何根都不可达(例如位于纯环中),未被放置 |
InvalidConnectionRef { from_node, to_node } |
连接引用了越界的节点索引,已跳过 |
RoutingFailed { from_node, from_port, to_node, to_port } |
连接无法布线,降级为别名字符显示 |
API 概览
| 条目 | 用途 |
|---|---|
NodeGraph |
持有节点 + 连接;new / calculate / split / split_viewport / diagnostics + 实现 ratatui StatefulWidget。calculate() 时整图(边框/端口/连线)渲染到内部离屏 canvas。 |
NodeGraphView |
一个 ratatui Widget:按 Viewport 的 offset 把 canvas 的可见窗口 blit 到屏幕(仅边框/端口/连线,不含节点内容)。 |
Viewport |
视口在 canvas 中的左上角 offset (x, y);传给 split_viewport 与 NodeGraphView。 |
NodeLayout |
单个节点的渲染信息;new((w,h)) 或 from_content(text) + builder。 |
Connection |
new(from_node, from_port, to_node, to_port) + with_line_type / with_line_style。 |
LineType |
Plain / Rounded / Double / Thick。 |
Diagnostic |
可观测的布局 / 布线问题。 |
致谢
ratatui-flow 是 tui-nodes(作者 jaxter184)的 fork,在此基础上去除 panic、补齐测试、收紧公共 API,并加入结构化诊断与内容自适应尺寸。
许可证
MIT(见 LICENSE)。