TiXL Graph 窗口完全指南：节点画布、磁力吸附连线与复制/断开工作流

TiXL Graph 窗口完全指南：节点画布、磁力吸附连线与复制/断开工作流

【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3

TiXL（tooll3）的Graph 窗口是整个项目搭建的核心画布：你在其中放置算子（Operator）、把输入与输出接线成实时渲染的节点网络。本文以官方参考文档 Graph.md 为主线，结合编辑器源码深入剖析画布交互的底层实现，读完你将掌握 Graph 窗口的完整操作方式——从磁力吸附的连线习惯、Ctrl+D系列复制技巧，到抖动断开与"断开节点零渲染开销"的实战策略。

Graph 窗口：TiXL 项目构建的主画布

Graph 窗口的角色在文档中被一句话点明："you build a project by placing operators and wiring their inputs and outputs together"——放置算子、接线，这就是 TiXL 项目构建的全部基础动作。它对应编辑器中负责节点图渲染与交互的MagGraph子系统（Editor/Gui/MagGraph），其核心画布实现为MagGraphView。

进入/深入一个算子的图，有两条最常用的路径：

• 打开算子钻入子图：文档所说的 "Open an operator to dive into its graph" 即导航进入某个算子的内部构图。在源码的默认键位中，选中节点后按I（OpenOperator）、退出用U（CloseOperator），见 FactoryKeyMap.cs；同时支持基于导航历史的"后退/前进"，对应Alt+←/Alt+→（NavigateBackwards/NavigateForward）。
• 双击空白处浏览并添加新算子：文档指出 "double-click empty space to browse and add new ones"。其背后是 SymbolBrowsing.cs 绘制的符号浏览器——按类别与命名空间组织、经UpdateLibPage()生成的"精选符号总览"，再配合右键上下文菜单（GraphContextMenu.cs）完成放置。

这两条路径构成了 Graph 窗口的"纵向钻取"（深入子图）与"横向扩展"（新增节点）双向工作流。

磁力吸附：垂直堆栈与水平对齐（Alt+A）

垂直堆栈：自上而下可读的算子链

文档强调算子之间会磁力吸附（"Operators snap together magnetically"），因此一条算子链自上而下排布，读起来就像一份栈结构。这个行为在源码中有精确实现：MagItemMovement内部的Snapping类在拖拽过程中持续测试节点对的吸附可能性（MagItemMovement.Snapping.cs）：

• 垂直吸附：当输出项的 0 号输出线与输入项的 0 号输入线（主出→主入）对准时触发，形成文档所述的"像栈一样"的纵向链条；
• 水平吸附：任何类型兼容的输出线对输入线触发，用于把相关算子横向并排；
• 吸附阈值：IsSnapped => BestDistance < MagGraphItem.LineHeight * (IsInsertion ? 0.35 : 0.5f)——即两条线锚点距离小于半行高即"吸住"，插入场景（在既有连线中间插入算子）的阈值更严格（0.35 行高）。

拖拽过程的完整调用链位于 MagItemMovement.cs：UpdateDragging()先检测抖动，再HandleSnappedDragging()处理吸附，吸附成立后走TryCreateNewConnectionFromSnap()（新建连线）或TrySplitInsert()（插入式拆分既有连线）。

水平对齐：Alt+A 整理连线

垂直堆栈读起来像栈，但如果关联算子都纵向堆叠，连线会拉得很长。文档给出的习惯是用水平吸附（Alt+A）对齐相关算子，让连接线保持整洁。这里的 Alt+A 在源码中对应UserActions.AlignSelectionLeft（FactoryKeyMap.cs），当选中节点数大于 1 且处于默认交互状态时触发Modifications.AlignSelectionToLeft()（KeyboardActions.cs），把选中算子统一左对齐。

复制：Ctrl+D 与 Ctrl+Shift+D 的差异

文档点出的两个高频复制习惯，在键位表（FactoryKeyMap.cs）与处理逻辑（KeyboardActions.cs）中一一对应：

Ctrl+Shift+D的接线保留逻辑值得细看，它实现在 Modifications.cs 的DuplicateWithConnections()中，规则非常考究：

• 外部输入 → 被复制的目标：外部源连入所选集合的连线，会在副本上重建，并保留原有多输入槽位索引；
• 被复制的源 → 外部多输入：副本的输出会追加到原连接之后（multiInputIndex + 1），把吸附在原输入线下方的节点顺势向下推，效果类似一次交互式"插入连线"；
• 外部单输入故意跳过：注释明确说明"adding the duplicate's output there would replace (steal) the original's connection"——单输入会被新连接顶替，所以DuplicateWithConnections特意不抢原节点的连接；
• 最终粘贴位置取当前鼠标位置（ImGui.GetMousePos()反变换到画布坐标）。

抖动断开与兼容重连

文档描述了一个独特的交互：抖动（shaking）算子使其断开，同时重连兼容的输入。这个"抖一抖就断开"在源码中的实现链路是（MagItemMovement.cs）：

1. 拖拽过程中_shakeDetector.TestDragForShake(ImGui.GetMousePos())检测到抖动；
2. 若拖拽项存在连线（_connectionsToDraggedItems.Count > 0），调用HandleShakeDisconnect()；
3. 最终执行NodeActions.DisconnectNodes(...)断开所选节点的所有连接。

拖拽松手（unsnap）时还有一整套断线与收拢处理：HandleUnsnapAndCollapse()删除拖拽过程中"脱开"的连线，并通过TryCollapseDisconnectedInputs()/DisconnectedInputWouldCollapseLine()判断某条输入线断开后是否应折叠隐藏（MagItemMovement.cs）——这正是"断开后画布自动整理"的底层机制。

除抖动外，还有两种等效断开方式：快捷键Alt+D（Disconnect，FactoryKeyMap.cs），以及选中节点后右键菜单中的 "Disconnect" 项（GraphContextMenu.cs）。

断开节点零渲染开销：放心保留备用节点

文档给出的重要结论："A disconnected operator costs nothing at render time, so it's safe to keep spare copies around until you wire them in."

从源码结构看，TiXL 的求值以连接关系为驱动：算子实例仅在构图求值遍历中被更新，未连入有效链路的算子不会参与渲染期计算（相关求值机制见 Core/Operator/EvaluationContext.cs 与 Instance.OperatorHelpers.cs）。因此把暂时用不到的算子留在画布上作为"备用零件"、之后接线启用，不会带来渲染开销，也省去反复新建算子的成本。与之配套的还有Shift+D（禁用）与Shift+B（旁路）切换，可用于临时停用而不必删除连线。

Graph 窗口快捷键速查表

以下键位均来自编辑器出厂键位表 FactoryKeyMap.cs，可在快捷键编辑器中重映射（动作枚举见 UserAction.cs）：

相关源码索引

• 官方参考文档：.help/references/topics/ui/Graph.md
• Graph 画布与交互核心：Editor/Gui/MagGraph/Ui/MagGraphView.cs、Editor/Gui/MagGraph/Interaction/MagItemMovement.cs
• 磁力吸附算法：Editor/Gui/MagGraph/Interaction/MagItemMovement.Snapping.cs
• 键盘动作分发：Editor/Gui/MagGraph/Interaction/KeyboardActions.cs
• 保留接线的复制实现：Editor/Gui/MagGraph/Interaction/Modifications.cs
• 符号浏览与放置：Editor/Gui/MagGraph/Interaction/SymbolBrowsing.cs、Editor/Gui/MagGraph/Interaction/GraphContextMenu.cs
• 出厂键位表与动作枚举：Editor/Gui/Interaction/Keyboard/FactoryKeyMap.cs、Editor/Gui/Interaction/UserAction.cs

实践建议：新建项目后先熟悉三条核心路径——双击空白处浏览放置算子建立纵向主链，Alt+A横向对齐相关节点收拢连线，Ctrl+Shift+D带着接线关系复制模块；暂时用不到的算子放心留在画布上，断开状态下不会产生任何渲染开销。

【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3