egui-snarl引脚完全自定义指南:用SnarlPin把输入框、按钮、图片放进Pin
egui-snarl引脚完全自定义指南:用SnarlPin把输入框、按钮、图片放进Pin
egui-snarl 是一个为 Rust 的 egui 构建的节点图(node-graph)UI 库,它的最大亮点之一,就是引脚(Pin)完全由开发者掌控:通过 SnarlPin trait 和 PinInfo 构建器,你可以把文本输入框、拖拽数值、按钮甚至图片直接放进 Pin 里,而不是被限制在一个小圆点上。本指南带你快速理解这套自定义机制,并学会在 3 个步骤内动手实践。
如上图所示,官方 demo 里每个 Pin 的内容都不一样:URL 输入框、可拖拽的数值、接收值显示、图片——全部塞在节点边缘的引脚区域里。这正是 egui-snarl 引脚自定义能力的直接体现。
先认识 Pin:节点图里的"接口"是什么
在节点图中,节点(Node)通过输入/输出引脚(Input/Output Pin)用连线(Wire)串联起来。egui-snarl 把节点内部划分为 5 个空间:顶部 Header、左侧输入引脚、中部 Body、右侧输出引脚、底部 Footer,具体见 README.md。
对 Pin 的"完全自定义"分为两层,分别对应两个核心类型(定义在 src/ui/pin.rs):
| 类型 | 作用 | 适合场景 |
|---|---|---|
PinInfo |
声明式配置:形状、填充色、描边、连线颜色与线型 | 90% 的日常需求 |
SnarlPin trait |
命令式绘制:完全接管 Pin 的绘制过程 | 需要异形/动画/特殊交互的 Pin |
Pin 的 UI 内容则由 SnarlViewer trait 决定。关键在这两个方法的签名:
fn show_input(&mut self, pin: &InPin, ui: &mut Ui, snarl: &mut Snarl<T>)
-> impl SnarlPin + 'static;
fn show_output(&mut self, pin: &OutPin, ui: &mut Ui, snarl: &mut Snarl<T>)
-> impl SnarlPin + 'static;
注意那个 ui: &mut Ui 参数——每一个 Pin 都会得到一块独立的 egui::Ui,你往里面放什么,Pin 就显示什么。这就是"把输入框、按钮、图片放进 Pin"的底层机制,没有任何限制(见 src/ui/viewer.rs)。
方式一:用 PinInfo 快速配置引脚外观
大多数情况下,你只需要一个漂亮的 Pin 形状和连线配色,这时用 PinInfo 即可。它提供 4 种内置形状:
PinInfo::circle()— 圆形(默认)PinInfo::triangle()— 三角形PinInfo::square()— 方形PinInfo::star()— 星形
再链式调用构建器微调,例如:
PinInfo::circle()
.with_fill(Color32::from_rgb(0x00, 0xb0, 0x00)) // 填充色
.with_stroke(Stroke::new(1.0, Color32::WHITE)) // 描边
.with_wire_color(Color32::YELLOW) // 连线颜色
.with_wire_style(WireStyle::AxisAligned { corner_radius: 10.0 });
所有字段都是 Option,未设置的会自动回退到 SnarlStyle 的全局默认值,所以你可以"只覆盖需要覆盖的部分"。
方式二:实现 SnarlPin trait 接管绘制
当内置 4 种形状不够用时(比如想要带渐变的六边形、呼吸闪烁的动画引脚),直接实现 SnarlPin trait:
pub trait SnarlPin {
fn draw(self, snarl_style: &SnarlStyle, style: &Style,
rect: Rect, painter: &Painter) -> PinWireInfo;
}
rect是 Pin 的交互区域,你的绘制应落在其中;- 返回的 PinWireInfo 告诉 egui-snarl 该 Pin 连线的颜色和线型;
- 0.7.1 起还可通过重写
pin_rect方法自定义 Pin 的位置与尺寸(见 CHANGELOG.md)。
PinInfo 本身就实现了 SnarlPin,所以两种方式可以混用:简单 Pin 返回 PinInfo,复杂 Pin 返回自己的类型。
实战:把输入框、按钮、图片放进 Pin
官方示例 examples/demo.rs 是最好的教材,里面演示了 4 种"Pin 内嵌 UI"玩法:
1. 文本输入框(TextEdit)放进 Pin —— ShowImage 节点的输入 Pin 是一个单行文本框,直接编辑图片 URL;一旦被连线,就自动切换为展示远程节点传来的字符串(examples/demo.rs):
let input = snarl[pin.id.node].string_in();
egui::TextEdit::singleline(input)
.clip_text(false)
.desired_width(0.0)
.show(ui);
PinInfo::circle().with_fill(STRING_COLOR)
2. 拖拽数值(DragValue)放进 Pin —— Number 节点的输出 Pin 就是一个可拖拽的数值控件(examples/demo.rs),连到下游后,下游 Pin 里用 ui.label 显示实时收到的值。
3. 按钮放进 Pin —— demo 的右键菜单(show_graph_menu)里全是按钮,同样的 ui.button(...) 写法放进 show_input/show_output 就是一枚"Pin 内按钮",配合 snarl.connect/disconnect 可以做出"点击 Pin 立即接线"的交互。
4. 图片放进 Pin —— Sink 节点收到图片 URL 时,直接在 Pin 里 ui.add(egui::Image::new(uri)) 渲染缩略图(examples/demo.rs)。
💡 小技巧:Pin 内容里"有连线/无连线"两种状态分别处理(检查 pin.remotes 是否为空),可以做出类似 Houdini、Blender 节点编辑器那样的智能引脚体验。
引脚布局与样式:让 Pin 长得更舒服
Pin 在节点内的摆放由 PinPlacement 控制:
Inside— Pin 在节点边框内(默认)Edge— Pin 中心落在边框线上(demo 采用的风格)Outside { margin }— Pin 完全挂在节点外侧
再配合 NodeLayoutKind(Coil 左右分栏 / Sandwich 上下堆叠)和 SnarlStyle 的 pin_size、pin_shape 等字段,整套引脚区的观感都可以全局调整。demo 里的完整配置可直接参考 default_style()。
最快上手步骤:3 步跑起来
-
获取项目:
git clone https://gitcode.com/gh_mirrors/eg/egui-snarl -
运行官方 demo(需要 serde 与 egui-probe 特性):
cargo run --example=demo --features="serde egui-probe"demo 源码在 examples/demo.rs,它展示了表达式节点、字符串节点、图片节点,以及上面提到的全部 Pin 自定义技巧。
-
动手改造:在 demo 的
DemoViewer里挑一个 Pin,把它换成按钮或下拉框——只需修改show_input/show_output里对ui的使用,返回的PinInfo不用动。
总结
egui-snarl 的引脚自定义体系可以概括为一句话:SnarlViewer::show_input/show_output 给你的 Ui 决定 Pin 里"放什么",返回的 impl SnarlPin 决定 Pin 本身"画成什么样"。
- 想快 → 用 PinInfo 配置形状与连线样式;
- 想深 → 实现 SnarlPin 完全接管绘制;
- 想做富交互 → 在 Pin 的
Ui里放输入框、按钮、图片,参考 examples/demo.rs。
无论是数据流编辑器、视觉编程工具还是流程编排界面,这套机制都能让你的节点图摆脱"一水儿小圆点"的千篇一律。
