TiXL 符号库 Reveal 指示器在 Symbol Library 中定位当前操作符与合成的高亮机制详解【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3Symbol Library Reveal Indicator 是 TiXL 4.3 新增的导航辅助功能当你在 Graph Window 中选中某个操作符时Symbol Library 的符号树会自动高亮该操作符当没有任何操作符被选中时高亮会自动回落到当前正在编辑的合成composition。本文基于官方手动测试集 .tests-manual/symbol-library-reveal.md结合 SymbolLibrary.cs 与 NamespaceTreeNode.cs 的实现源码完整讲解该功能的操作路径、验收标准与底层实现原理读者可以据此复现验证、理解其状态机设计并将其接入自己的项目工作流。功能定位与文档背景这份文档是什么仓库.tests-manual/目录下的每个 Markdown 文件都是一个手动测试集test set一组有序的步骤用于人工验证 TiXL 的某个特性。根据 .tests-manual/README.md 的约定每个测试集对应一个文件文件名与 frontmatter 中的id一致kebab-case每个步骤以## Step: 短标题开头包含**Action:**测试者操作与**Expected:**可观察的预期结果使用现在时、只写可观测结果。symbol-library-reveal.md的 frontmatter 元数据如下字段值含义idsymbol-library-reveal唯一标识与文件名一致added2026-08-16测试集首次添加日期ISO 格式added-in-version4.3该功能首次随 TiXL 4.3 发布scopesymbol-library宽泛的功能域标签tags[user, essential]user表示面向艺术家的验收路径essential表示功能主路径prerequisites3 条运行前置条件见下文其中tags遵循 README 定义的词汇表smoke60 秒内、每次构建都跑、essential功能主路径、edge边界情况/回归网、perf性能观察、flaky已知偶发。user意味着这套测试由不写代码的艺术家即可完整执行所有命名都使用屏幕上可见的名称如[RadialGradient]、Graph Window而非背后的文件或类名。前置条件运行该测试集前需满足一个可编辑的项目已在 Graph Window 中打开合成中至少包含一个操作符例如[RadialGradient]Symbol Library 窗口可见且其搜索框为空避免搜索过滤干扰树的展开/高亮状态。功能概述高亮跟随选择回落跟随合成根据文档开头的简介该功能的核心行为是Symbol Library 会高亮图graph当前指向的操作符如果包含该操作符的命名空间文件夹处于折叠状态则在该文件夹行的右缘显示一个闪烁的准星图标aim icon自 4.3 起当没有操作符被选中时高亮回落到当前合成current composition——这样你正在内部编辑的符号也能被定位到。也就是说高亮目标的优先级是单个选中的操作符 → 当前合成。这一二段式回落逻辑正是本功能的实现核心见下文源码分析。复现与验收五步走通完整测试集以下完整继承自官方测试集 symbol-library-reveal.md并补充了对应源码行为的说明。每一步都同时给出操作Action与验收标准Expected。Step 1高亮跟随选中的操作符操作在 Graph Window 中点击[RadialGradient]将其选中然后观察 Symbol Library。预期结果库树中的RadialGradient周围出现闪烁的轮廓约半秒后稳定为常亮轮廓如果包含它的Lib文件夹处于折叠状态则改为在该文件夹行右缘出现闪烁的准星图标悬停准星图标时tooltip 显示Reveal selected operator。实现对应这一步骤对应 SymbolLibrary.cs 中的UpdateSelectedSymbolHighlight()每帧从图选中状态提取唯一的操作符 ID变化时记录_lastSelectedSymbolId与_lastSelectionTime。闪烁动画由余弦函数驱动blinkFade -MathF.Cos(timeSinceChange * 15f) * (1f - fadeProgress) * 0.7f 0.75f其中fadeProgress Clamp01(timeSinceChange / 0.5f)让闪烁在约 0.5 秒内平滑衰减为常亮。符号行的高亮边框DrawSymbolItemInstance同样用MathUtils.Lerp(-MathF.Cos(...)*0.8f 0.2f, 1, fadeProgress)在 0.3 秒内完成淡入。Step 2无选中时高亮回落到合成操作在 Graph Window 中双击一个操作符进入它内部然后点击空的图背景使所有内容取消选中观察 Symbol Library。预期结果高亮移动到刚进入的符号——即图面包屑breadcrumb中显示名字的那个在取消选中瞬间闪烁重新启动一次然后稳定之前选中的操作符上不再保留任何高亮。实现对应这是TryGetSingleSelectedSymbolId()SymbolLibrary.cs的回落分支遍历当前NodeSelection若恰好只有一个SymbolUi.Child被选中则返回其Symbol.Id否则返回projectView?.CompositionInstance?.Symbol.Id——即当前合成的符号 ID。由于 ID 变化会重置_lastSelectionTime闪烁会如文档描述那样重启一次。Step 3从折叠文件夹中揭示合成操作在合成内部保持无选中状态点击 Symbol Library 搜索框右侧的Collapse All图标然后悬停折叠文件夹行上的准星图标并点击它。预期结果tooltip 显示的是Reveal current composition而非Reveal selected operator点击后命名空间路径被展开直达合成的符号并将其垂直居中滚动到树中可见被揭示的符号携带闪烁高亮任何文件夹行上都不再残留准星图标——把整棵树从头滚到尾确认被揭示符号的文件夹现已全部展开因此不应再有指向它的图标。实现对应tooltip 文案由 SymbolLibrary.cs 判定ProjectView.Focused?.CompositionInstance?.Symbol.Id selectedSymbolId为真时显示Reveal current composition。点击准星图标后L469-L474设置_expandToSymbolTriggered、_expandToSymbolTargetId与_scrollToSymbolId树的绘制循环里凡在目标路径上的节点都会被强制ImGui.SetNextItemOpen(true, ImGuiCond.Always)展开L402-L405而符号行自身通过ImGui.SetScrollHereY(0.5f)L842实现垂直居中滚动。准星图标仅在节点包含选中符号且未展开!isOpen containsSelectedL446时绘制路径展开后条件自然失效因此整棵树不再有准星。Step 4揭示落在符号自己的命名空间下操作记下面包屑中合成所显示的命名空间再次折叠整棵树点击准星图标观察被揭示的符号最终落在哪个文件夹下。预期结果符号被揭示在其自身命名空间对应的文件夹内而不是树中其他同名操作符所在的文件夹。实现对应路径查找的命名空间优先策略是关键。UpdatePathToFocusedSymbol() 先调用TryFindPathByNamespace()L305-L350从符号注册的Symbol.Namespace按.分段从根一路向下匹配子节点并验证到达的节点确实持有该符号 ID只有当这条命名空间路径走不通时才回退到递归搜索FindPathRecursive()L355-L373。源码注释解释了原因同一个符号 ID 可能被多个节点持有两个包注册了相同的 ID两次独立查找会得出不同的指向因此每帧只重建一次路径列表_pathToFocusedSymbol供准星图标与展开逻辑共享。Step 5多选时不显示任何指示操作在 Graph Window 中使用橡皮筋框选或Shift点击选中两个或更多操作符。预期结果Symbol Library 树中不显示高亮任何折叠文件夹行上都不显示准星图标点击空的图背景后恢复上一步的合成高亮。实现对应TryGetSingleSelectedSymbolId()在遍历选中集合时一旦发现第二个节点就立即返回nullL789-L790而UpdateSelectedSymbolHighlight()在selectedSymbolId为 null 时会把_lastSelectedSymbolId置空L763-L766从而同时熄灭高亮与准星。源码深潜高亮状态机与路径展开每帧状态更新流程DrawContent()每帧首先调用UpdateSelectedSymbolHighlight()L75再进入DrawView()绘制树。高亮状态由三个静态字段维护private static Guid? _lastSelectedSymbolId; // 当前高亮目标 private static double _lastSelectionTime; // 驱动闪烁动画的时间戳 private static bool _revealHighlightActive; // Reveal() 注入的高亮是否仍有效 private static Guid? _graphSelectionAtReveal; // Reveal 时的图选中快照UpdateSelectedSymbolHighlight()还处理一种特殊来源Reveal(Guid symbolId)L55-L67——当用户在帮助文档中点击操作符链接时库会展开到该符号并保持高亮即使图选中并未变化。这种文档注入的高亮通过_revealHighlightActive与_graphSelectionAtReveal快照维持直到图选中真正发生变化才让位。准星图标的绘制条件准星图标只出现在折叠的、且位于高亮路径上的命名空间节点上!isOpen containsSelected。它的点击区域是一个与行高相同的隐形按钮ImGui.InvisibleButton(Reveal, new Vector2(h))L451图标由Icons.DrawIconOnLastItem(Icon.Aim, color)绘制颜色基于UiColors.StatusActivated随闪烁相位衰减。树节点类型与文件夹映射NamespaceTreeNode.cs 定义了树的构建规则。每个节点带一个SymbolFolderTypes枚举L89-L97类型含义Undefined未分类Root树根User用户项目的根命名空间段UserSubNamespace用户项目下的子命名空间Project项目根对应一个项目文件夹ProjectSubNamespace项目下的子命名空间SortInOperator()L99-L158依据符号的命名空间分段建树并用RootNamespace.Split(.)判定每一段属于上述哪一类型。树的顶层项目按_rootProjectNamesLib.、Types.、Examples.、t3.L48-L53排序其余项目排在其后——这解释了为何Lib image generate下的RadialGradient始终出现在树的前部。该枚举同样被Reveal in Explorer系列菜单使用只有Project或ProjectSubNamespace类型的节点才映射到真实文件夹。相关功能Symbol Library 的文件系统揭示本文档聚焦的是树内定位而符号库还有一组配套的系统文件定位功能由兄弟测试集 symbol-library-reveal-in-explorer.mdtags: [dev, essential]面向开发者覆盖右键操作符选择Reveal Symbol in Explorer在文件浏览器中打开该操作符所在文件夹并预先选中其.cs源文件无源码的包则选中.t3操作符文件路径形如Lib\image\generate选择Reveal Project in Explorer打开项目根文件夹即持有Lib.csproj的目录不做文件预选右键命名空间行选择Reveal Namespace in Explorer打开该命名空间对应的文件夹右键项目根行则显示Reveal Project in Explorer因为它是项目根而非子命名空间分组行如user聚合所有用户项目的Reveal Namespace in Explorer置灰不可用——它不映射任何独立文件夹。这些菜单实现在 SymbolLibrary.cs命名空间节点与 L949-L959符号项中GetFileOfSymbol()L1202-L1214优先返回EditorSymbolPackage.TryGetSourceCodePath解析出的 C# 源文件路径否则回退为命名空间目录下的.t3文件RevealInExplorer()L1235-L1251对文件缺失的场景操作符尚在内存、文件尚未落盘自动回退到其所在目录。如何运行与验证打开 TiXL载入任意可编辑项目在 Graph Window 中放置至少一个操作符如[RadialGradient]通过窗口菜单打开 Symbol Library清空其搜索框依次执行上文五个 Step逐条核对**Expected:**项每步可在测试运行器中记录pass/fail/other后者的结果属于某次运行不写入测试文件见 .tests-manual/README.md 的Step outcomes一节验证Reveal Symbol/Project/Namespace in Explorer系列时按 symbol-library-reveal-in-explorer.md 的步骤操作并核对文件浏览器打开的路径与预选文件。需要留意的是本文描述的交互与行为以仓库当前实现为准对应 TiXL 4.3 起的功能动画时长0.5 秒闪烁衰减、0.3 秒边框淡入为源码中的硬编码常量后续版本如调整视觉节奏以对应版本源码与测试集更新为准。若你计划向仓库贡献涉及符号库 UI 的改动请遵循 .tests-manual/README.md 的流程约定任何改变用户可见 UI 或行为的 PR都必须同步扩展既有测试集或新增测试集。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考