TiXL 操作符创建实战指南从 Symbol Browser 快速上手到手动测试集解读【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3本文以仓库.tests-manual/creating-operators.md手动测试集为骨架结合.tests-manual/README.md的格式规范、Editor/Gui/Graph/Legacy/Interaction/SymbolBrowser.cs与Operators/Lib/Symbols/image/generate/basic/RadialGradient.cs的源码实现系统讲解 TiXL实时动态图形创作工具中最核心、最高频的操作——在 Graph Window 中创建操作符并深入解读这份测试即教程文档的编写约定与底层原理。读完本文你既能独立完成打开 Symbol Browser → 搜索 → 放置的完整创建流程也能理解其背后的搜索过滤、实例化机制与手动测试集的撰写规则。文档定位一份可执行的操作符创建测试集creating-operators.md位于 .tests-manual/ 目录属于 TiXL 仓库中面向人工运行的验证流程Manual Test Sets之一。如 .tests-manual/README.md 所述每个文件定义一个test set测试集——一组有序的steps步骤用于验证某个功能或流程。它们以纯 Markdown 书写任何贡献者无需工具即可跟随执行同时 frontmatter文件头元数据采用结构化字段为未来编辑器内运行器in-editor runner的解析与驱动预留了接口。该测试集自身的 frontmatter 信息如下字段值含义idcreating-operatorskebab-case 唯一标识与文件名一致titleCreating Operators人类可读标题将显示在运行器 UI 中added2026-04-19ISO 日期驱动Recently added排序added-in-version4.2该测试集首次随 TiXL 4.2 版本发布scopegraph-window宽泛的功能区域标签tags[user, smoke, essential]运行器过滤用的标签prerequisites空项目已打开、Graph Window 可见执行前的准备条件related-help../.help/using/graph-window.md指向用户文档的深入阅读链接本文以仓库实际存在的文档重新组织文档开头还有一段关键自述This is the move youll make more than any other in TiXL——添加操作符是你在 TiXL 中做得最多的一件事。这也解释了为什么该测试集被打上smoke每次构建都运行的冒烟测试与essential功能主路径标签。前置条件在执行本测试集之前需要满足一个空项目已经打开An empty project is openGraph Window 可见The Graph Window is visible。这两条保证测试者从一个干净、确定的初始状态出发避免选中节点、已有布局等因素干扰后续断言。步骤一打开 Symbol Browser操作Action在 [Graph Window] 获得焦点的情况下按下Tab键。预期结果Expected[Symbol Browser]符号浏览器打开其搜索框已聚焦且为空——你可以立即开始输入。源码佐证Tab 触发与 Symbol Browser 的定位从键盘层面看.help/docs/using/KeyboardShortcuts.md 的默认快捷键表中明确列出动作按键Add New Operator添加新操作符TabContext search type name也就是说Tab 键被绑定为添加新操作符的全局触发键。在源码层面Editor/Gui/Graph/Legacy/Interaction/SymbolBrowser.cs 的Draw()方法中可以看到其触发逻辑if (!IsOpen) { var hasFocus ImGui.IsWindowFocused(ImGuiFocusedFlags.ChildWindows); var anythingActive ImGui.IsAnyItemActive(); if (!hasFocus || anythingActive || !ImGui.IsKeyReleased(Key.Tab.ToImGuiKey())) return; ... ConnectionMaker.StartOperation(_graphView, Add operator); var screenPos ImGui.GetIO().MousePos new Vector2(-4, -20); var canvasPosition canvas.InverseTransformPositionFloat(screenPos); OpenAt(canvasPosition, null, null, false); }这段代码揭示了几个实现细节仅在窗口未打开时响应 TabIsOpen为 false 时才进入判断需要 Graph Window 处于焦点ImGui.IsWindowFocused与IsAnyItemActive保证了Graph Window 聚焦时这一前置条件在鼠标位置附近创建浏览器通过ImGui.GetIO().MousePos取得鼠标屏幕坐标再逆变换为画布坐标调用OpenAt(...)在鼠标位置打开 Symbol Browser它本质上是 T2 时代 CreateOperatorWindow 的延续类的注释明确指出它是GraphView上新节点的占位符具备搜索功能可连接到其他节点。此外OpenAt()SymbolBrowser.cs还会做边界处理如果浏览器打开位置太靠近画布边缘会自动平移画布FitAreaOnCanvas避免浏览器被挤出可视区域——这就是测试中Graph Window 可见即可稳定复现的保证之一。步骤二按名称查找操作符操作Action在 Symbol Browser 打开的状态下输入RG搜索是大小写不敏感的且支持部分名称匹配。预期结果Expected结果列表被过滤为名称中包含这些字母的操作符[RadialGradient]出现在列表中。过滤机制的源码视角Symbol Browser 的过滤逻辑围绕一个内部_filter对象展开。从OpenAt()SymbolBrowser.cs可见其关键状态_filter.FilterInputType filterInputType; _filter.FilterOutputType filterOutputType; _filter.SearchString startingSearchString; _filter.OnlyMultiInputs onlyMultiInputs; _filter.UpdateIfNecessary(_components.NodeSelection, forceUpdate: true);也就是说浏览器在打开时不仅接受纯文本搜索串还能按输入类型、输出类型、是否仅多输入进行过滤——这为从某个已有节点的输出端口拖出连线时自动筛选可连接的运算符提供了支撑连接模式下会调用ConnectionMaker.StartOperation以Add operator命名。对于本测试集关心的按名称搜索文档明确声明的行为是大小写不敏感 部分名称匹配。因此输入RG可以命中RadialGradientrg同样可以。为什么是 RadialGradientRadialGradient是仓库内置的标准图像生成操作符源码位于 Operators/Lib/Symbols/image/generate/basic/RadialGradient.cs。该类继承自InstanceRadialGradient通过 GUID 特性标注唯一标识[Guid(82ad8911-c930-4851-803d-3f24422445bc)] internal sealed class RadialGradient : InstanceRadialGradient { [Output(Guid 9785937a-2b8f-4b2e-92ac-98ec067a40f2)] public readonly SlotTexture2D TextureOutput new(); [Input(Guid 54bca43c-fc2b-4a40-b991-8b76e35eee01)] public readonly InputSlotT3.Core.DataTypes.Texture2D Image new InputSlotT3.Core.DataTypes.Texture2D(); ... }这展示了 TiXL 操作符的典型结构InputSlotT声明输入Image、Gradient、Width、Stretch、Offset、Center、Noise、BlendMode、Resolution 等SlotT声明输出TextureOutput。每个输入输出都带有一个全局唯一的 GUID——如 .help/docs/getting-started/Concepts.md 所解释的TiXL 大量使用 GUID 在对象之间建立引用这使得重命名符号或参数不会破坏任何既有连接。选择 RadialGradient 作为测试目标并非偶然它的名称足够独特输入RG即可命中且在基础图像生成image/generate/basic命名空间中是新用户最可能实际用到的操作符之一。步骤三创建操作符操作Action在搜索结果可见的情况下用上/下方向键高亮[RadialGradient]然后按Return回车或用鼠标点击该条目将其放置到图上。预期结果Expected一个[RadialGradient]操作符出现在图中光标位置新操作符处于选中状态其输入显示在Parameter Window参数窗口中Symbol Browser自动关闭。一次操作引发的连锁状态变化这一步骤验证了四个可观察结果恰好对应创建操作的完整生命周期放置位置OpenAt(positionOnCanvas, ...)记录PosOnCanvas新节点将出现在调用Tab时鼠标所在的光标位置选中状态创建后节点自动成为当前选择_selectedSymbolUi被设置为匹配列表首项见 SymbolBrowser.cs参数窗口联动选中节点后其输入槽如 RadialGradient 的 Gradient、Center、Noise 等随之在 Parameter Window 中显示用户可立即调整浏览器关闭放置成功后IsOpen被置回 false搜索界面退场焦点交还画布。文档建议优先使用键盘触发而非鼠标拖拽见.tests-manual/README.md的 Authoring tips因为键盘描述更无歧义、更易复现——这也是本步骤把方向键 Return 作为主路径、鼠标点击作为并行备选的原因。理解 TiXL 的核心概念Operator / Symbol / Instance创建操作符之所以是用得最多的动作是因为Operator 是 TiXL 中一切的中心构建块。按 .help/docs/getting-started/Concepts.md 的说明Operator操作符——一切的核心构建块在描述这个东西是什么时常被称为Symbol符号——Symbol 定义了操作符包括子操作符实例及其参数、实例之间的连接、输入输出定义、描述、动画等在讨论某个符号在另一个操作符内部的使用时常被称为Instance实例——实例的参数决定了符号如何被使用。关键特性可嵌套操作符可以包含其他操作符可复用修改一个 Symbol 后其所有实例立即更新可生成代码操作符可以创建代码如 Shader在视觉编程社区中ops、nodes、patches 都是 Operator 的同义词。而操作符的命名也暗含约束因为操作符标题在内部被用作 C# 类名所以不能包含空格或特殊字符、不能以数字开头如MyFirstDemo✔、My Demo✘、1stProject✘。你通过 Symbol Browser 搜索到的每一个名字背后都是一个经过合法命名的 C# 类——这正是上面RadialGradient源码中internal sealed class RadialGradient : InstanceRadialGradient的形式。注意其命名空间Lib.image.generate.basic遵循 Concepts.md 的规范层级用.分隔、以小写字母开头、无空格与特殊字符——命名空间决定了操作符在 TiXL 操作符库中的存储位置以及 AppMenu → Add 中的分组方式。手动测试集的编写规范一份可机器解析的 Markdown理解这份文档的怎么读还要理解它怎么写。.tests-manual/README.md提供了完整的格式约定这也是creating-operators.md结构之所以如此的原因frontmatter 字段约定字段必填说明id✅kebab-case、唯一、与文件名一致title✅人类可读标题显示在运行器 UIscope建议宽泛功能区域自由标签tags可选供运行器过滤added新集合必填ISO 日期YYYY-MM-DD驱动Recently added排序added-in-version新集合必填首次随附的 TiXLmajor.minor如4.2prerequisites可选自由文本的准备条件related-help可选指向.help/的深入阅读相对链接Step 结构约定每个步骤以## Step: 简短祈使句标题开头标题将显示为运行器副标题如 Step 3/12 — Creating an operator因此应写成被验证的事情而非按键本身**Action:**—— 给测试者的操作指令用引导新用户的散文语气书写如 With the search results visible, use the cursor up/down keys to highlight[RadialGradient].仅当步骤真正并行时才用项目符号如要么点击、要么按 Enter避免逐按键列点导致像清单而非导览**Expected:**—— 用现在时书写、只写可观察结果每条独立断言可用项目符号禁止should probably式模糊表述——结果模糊就拆分步骤**Context:**可选遗留字段——一句话交代测试者所处状态新集合应把上下文折叠进**Action:**的首句运行器为兼容旧集仍会解析该字段。标签词汇表与受众标签虽是自由形式但规范建议统一使用短核心词汇便于运行器提供合理过滤smoke—— 60 秒以内每次构建都运行essential—— 功能的主要快乐路径edge—— 边界情况、回归网络perf—— 对性能敏感的观察步骤flaky—— 已知间歇性失败的测试修复前保留。每个测试集还必须恰好携带一个受众标签user—— 艺术家验证自己在 TiXL 中真正会做的事加载项目、设置音源、录制、导出用平实语言、以屏幕所见命名而非背后的文件/格式/类dev—— 贡献者验证编辑器内部或构建工作流创建操作符、图编辑的撤销/重做、构建失败消息等保留技术细节。creating-operators.md的标签为[user, smoke, essential]说明它被归类为艺术家也能完成的、每次构建必跑的冒烟级主路径。有趣的是README 举例时把creating operators列为dev的典型场景而本测试集选择了user视角——判定标准是谁来运行它只要非编程背景的艺术家能照着跑完就归为user。运行结果如何记录测试集文件本身不存储每步结果。运行时可记录的结果为pass/fail/other可附带自由文本评论这些结果属于某一次运行而非测试定义本身——因此创建操作符这样的测试可以被反复执行而不污染定义文件。何时添加或更新测试集README 明确规定了一条与.help/一致的项目规则任何改动用户可见 UI 或行为的 PR必须在同一 PR 内扩展现有测试集或新增一个。功能计划.agentic/Plans/应链接到对应测试集而不是复制步骤被覆盖功能移除时陈旧测试也随之删除。写作技巧方面规范还强调为从未用过 TiXL 的人写作——明确命名菜单、按钮与窗口每个步骤只做一个可观察变化需要检查两件不相关的事就拆成两步避免绝对坐标点击 200,400改用名称Graph Window、Parameter Window、[RadialGradient]键盘触发优先于鼠标拖拽更易无歧义描述若步骤依赖先前状态需在**Context:**中说明——因为运行器支持部分运行时步骤不一定会从头到尾执行。从放置操作符到深入使用延伸阅读路径完成创建只是起点。围绕creating-operators.md验证的流程仓库还提供了大量可直接继续深入的材料概念基础.help/docs/getting-started/Concepts.md —— Operator/Symbol/Instance、命名规范、命名空间、GUID、界面配色语义橙色时间相关、蓝色驱动/链接、绿色快照可控、品红需注意快捷键全景.help/docs/using/KeyboardShortcuts.md —— Tab 之外的播放控制J/K/L、撤销重做CtrlZ / CtrlShiftZ、复制粘贴、书签、布局等同类测试集创建操作符之后紧随其后的典型操作链都有对应测试集例如 .tests-manual/undo-redo-graph-edits.md图编辑撤销/重做、.tests-manual/duplicate-with-connections.md带连接复制、.tests-manual/graph-sections.md图分区——它们共同构成了 TiXL 图编辑工作流的人工回归网络手动测试集总览.tests-manual/README.md —— 完整格式规范、标签约定与维护流程。小结creating-operators.md虽然只有三个步骤却精准覆盖了 TiXL 最高频操作——创建操作符——的完整链路Tab唤起 Symbol Browser、输入部分名称大小写不敏感过滤、方向键 回车放置、参数窗口联动、浏览器自动关闭。将其与 SymbolBrowser.cs 的触发与过滤逻辑、RadialGradient.cs 的类结构、.tests-manual/README.md 的格式规范对照阅读既能让你快速上手 TiXL 的核心交互也能理解这份测试即文档是如何被设计为既可供新人跟随、又可供未来运行器解析的双重身份。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考