TiXL 编辑器参考索引的核心数据源：ui-topics.md UI Topic Registry 全解析

TiXL 编辑器参考索引的核心数据源ui-topics.md UI Topic Registry 全解析【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3本文围绕 TiXL开源实时动态图形创作软件帮助系统的手工维护数据源.help/references/topics/ui-topics.md展开讲解它的文件格式规范、字段语义、与构建脚本analysis_to_index.py的配合流程以及它如何通过[HelpUiID]特性与编辑器 UI 代码建立锚点。读完本文你将掌握 TiXL 参考索引中ui:主题命名空间的设计原理并具备新增、维护 UI 主题注册项的完整实操能力。背景TiXL 的参考索引体系与ui:主题命名空间TiXL 的文档以.help/目录为唯一事实来源见.help/README.md其中参考索引reference index分为两半操作符索引由SymbolUi自动生成对应docs/operators/index.json与docs/operators/下按操作符拆分的大量.md文件属于「机器生成、勿手改」的部分UI 主题索引由本篇文章的主角ui-topics.md提供即文档中描述的theui:half of the reference index — the editors UI components and concepts, the mirror of the generated operator index。它把编辑器的窗口、画布、面板、弹窗以及概念性对象Symbol、Field、Evaluation Context 等登记成一组带稳定 ID 的主题topic。每个主题拥有一个形如ui:id的键。这套键被三类场景消费编辑器内帮助视图hover 提示、文档图标通过ui:id深链跳转到对应主题正文视频分析SRT 提取中的提及mention通过主题别名解析回正确主题源码中的[HelpUiID]特性把 UI 类与主题 ID 绑定供帮助和引导教程定位并高亮界面组件。因此ui-topics.md不是一份面向用户的阅读型文档而是一份机器可解析的元数据注册表原文档自述This file ismetadata only。文件格式规范一个##块一个主题ui-topics.md采用极其规整的格式每个主题以##二级标题开头标题文本即人类可读的术语名term紧随其后是若干行key: value形式的元数据字段字段之间以空行分隔下一个主题块。## Graph id: Graph synonyms: GraphWindow, GraphCanvas, Operator Graph, Magnetic Graph, MagGraph classes: GraphWindow, MagGraphView解析器parse_topics()位于.help/scripts/analysis_to_index.py通过re.split(r^##\s, text, flagsre.M)切块逐行匹配([A-Za-z]):\s*(.*)$提取字段字段名统一转为小写。若某个块没有显式id:则回退用pascal(term)从术语名推导如 Dope sheet →DopeSheet。字段语义详解id / synonyms / parent / classes字段必填语义消费方id:建议稳定的 PascalCase 键构成ui:id帮助深链、topics.json的键、[HelpUiID]的匹配目标synonyms:可选逗号分隔的别名列表是最关键的字段原文档称其为the load-bearing field让 SRT 提及如 dope sheet area、MagGraph能解析到正确主题别名对用户不可见parent:可选主题嵌套关系如 Dope sheet ⊂ Timelineshow more 分组与 hover 时的 where to find it 定位提示输出时会被改写为ui:parent形式classes:可选实现该组件的 C# 类名列表帮助与引导教程定位 UI 代码对概念类主题Symbol、Field 等仅作为文档锚点说明值得注意的细节来自.help/scripts/analysis_to_index.py的parse_topics()与build()synonyms会被拼入topic_lookup大小写不敏感地参与解析topic_lookup[syn.lower()] tidparent在最终输出topics.json时会被规范化为ui:parent形式无 parent 则为null生成topics.json时若发现references/topics/ui/Id.md文件存在会记录docFile指针供编辑器惰性加载正文见后文。主题注册表全览51 个ui:主题以下是原文档登记的全部主题按功能领域归类term / id / 关键别名与 classes 摘要编辑器主画布与交互主题 termid关键点GraphGraph别名 MagGraph、GraphCanvas、Operator Graphclasses:GraphWindow,MagGraphViewTimelineTimelineclasses:TimeLineCanvasDope sheetDopeSheetparent: Timelineclasses:DopeSheetAreaAnimation areaAnimationAreaparent: Timelineclasses:TimelineDetailsAreaCurve editorCurveEditorparent: Timeline别名 Curve areaclasses:TimelineCurveEditorControl barControlBar别名 tool barclasses:TimeControlsSectionsAnnotations别名 annotations, framesclasses:MagGraphSectionGizmoGizmoclasses:TransformGizmoHandling窗口与面板主题 termid关键点Parameter windowParameterWindow别名 Parameter Viewclasses:ParameterWindowOutput WindowOutputWindowclasses:OutputWindowSettingsSettings别名 Settings Window, User Settingsclasses:SettingsWindowProject SettingsProjectSettings别名 Composition settingsclasses:ProjectSettingsWindowVariation windowVariationWindowclasses:VariationsWindowSearch windowSearchWindow别名 Control F, Findclasses:SearchDialogPerformance monitorPerformanceMonitor别名 performance window, performance graphclasses:PerformanceWindowControl viewControlViewclasses:SnapshotControlViewConsole logConsoleLog别名 log window, console windowclasses:ConsoleLogWindowProject panelProjectPanel别名 project list, homeclasses:ProjectsPanelIO viewIoViewclasses:IoViewWindowSplash screenSplashScreenclasses:SplashScreenWelcome windowWelcomeWindow无 classes 字段Welcome alpha windowWelcomeAlphaWindowclasses:WelcomeAlphaWindow渲染与资源主题 termid关键点Render settingsRenderSettingsclasses:RenderWindowOutput settingsOutputSettingsclasses:OutputWindowStateShader graphShaderGraphclasses:ShaderGraphNodeShader nodeShaderNodeparent: ShaderGraphclasses:ShaderGraphNodeFieldField别名 SDF, distance field, value fieldclasses:ShaderGraphNodeAssetAsset别名 Assetsclasses:AssetAsset LibraryAssetLibraryclasses:AssetLibrarySymbol LibrarySymbolLibraryclasses:SymbolLibrarySymbol browserSymbolBrowserclasses:PlaceholderCreation核心概念对象主题 termid关键点SymbolSymbolclasses:SymbolCompositionCompositionclasses:InstanceUser ProjectUserProjectclasses:EditableSymbolProjectOperator SettingsOperatorSettings别名 Operator namesclasses:ParameterSettingsEvaluation contextEvaluationContext别名 context, variablesclasses:EvaluationContextTime overridesTimeOverridesclasses:EvaluationContextLocal timeLocalTimeparent: EvaluationContextPlay back timePlaybackTimeparent: EvaluationContextclasses:PlaybackIdle motionIdleMotionclasses:Playback学习与引导系统主题 termid关键点SkillQuestSkillQuest别名 Skill Quest tutorials, Tutorialsclasses:SkillTrainingSkill Quest LevelSkillQuestLevelparent: SkillQuestclasses:QuestLevelSkill MapSkillMapparent: SkillQuest别名 Skill Quest Mapclasses:SkillMapData小型编辑控件主题 termid关键点Gradient editorGradientEditorclasses:GradientEditorColor editorColorEditorclasses:ColorEditPopupInfinity sliderInfinitySliderclasses:InfinitySliderOverlayParameter popupParameterPopupclasses:ParameterPopUpFocus modeFocusModeclasses:LayoutHandling播放与音频主题 termid关键点PlayerPlayer无 classes 字段Player exporterPlayerExporterparent: Playerclasses:PlayerExporterAudio inputAudioInputclasses:WasapiAudioInput构建管线analysis_to_index.py 如何消费该文件ui-topics.md是「视频 → 文档」流水线的第三阶段输入。脚本.help/scripts/analysis_to_index.py的模块文档明确了它的定位Reads the committed per-video analyses plus the hand-authored UI-topic registry, and builds the reference indices the editor reads.它的输入与输出输入references/video-analysis/id.md每条视频的逐段分析references/topics/ui-topics.md输出写入references/indices/纯仓库内运行不触碰 gitvideos.json— 视频元数据id、类型、日期、标题、时长、摘要、focusesOntopics.json— 形如{topics: {ui:id: {term, parent, synonyms, classes, docFile}}}mentions.json— 策展后的参考索引按op:fullpath或ui:id键组织mentions.full.json— 未截断的完整存档。提及行的解析协议视频分析文件中的每一行提及遵循固定格式start[→end] [Op]/[ui:Id] · depth · style · purpose · conf% — note时间戳支持M:SS或H:MM:SS容忍,ms后缀start→end给出startSecond与duration标记[DrawPoints]/[ui:Timeline]由正则MARK_RE提取容忍[ui:ui:X]这类冗余前缀depth∈in-depth | explained | passingstyle∈scripted | answer | discussion | experimentpurpose∈Example | Comparison | Parameters | Gotcha | Concept | Performance | Tip置信度以N%形式记录破折号—之后的note是面向用户的文本note 内部可以再包含[Op]链接供帮助 UI 的自动链接器使用——但这些嵌套标记不计入提及。链接解析的三级回退keys_for(kind, name)展示了名称解析策略ui:前缀标记直接查topic_lookup含别名大小写不敏感裸标记[DrawPoints]先按操作符名查docs/operators/index.json的by_shortname含大小写不敏感的唯一回退应对提取器把IKChain、LoadOBJ这类缩写过度大写的情况若裸标记不是操作符则回退到主题注册表——这正是别名在发挥 load-bearing 的作用。评分与策展curation原始分析是穷举式的每个一闪而过的提及都会被记录会淹没真正值得链接的时刻。脚本据此设计了一个评分模型score durationFactor × depthWeight × styleWeight另有 purposeWeight 加权时长因子在 5–30 秒区间线性映射到 0..1深度权重in-depth: 2.0、explained: 1.5、passing: 0.5风格权重scripted: 2.0、answer: 2.0、discussion: 0.75、experiment: 0.4目的权重温和倾向「卡住时最先想找」的类型Example: 1.2、Comparison: 1.2、Parameters: 1.1、Gotcha: 1.1其余为 1.0 上下全局仅保留评分最高的前MAX_REFERENCES 500条设为None可关闭策展视频若在前置元数据中声明focusesOn: [Op], [ui:Topic]则该视频视为该主题的专属教程其多个时刻被折叠为一条参考并乘以FOCUS_BOOST 5.0提升到榜首同时该视频对其他主题的顺带提及会被丢弃。最终mentions.json内每个键下的参考按分数降序排列确保最佳时刻排在最前。帮助正文的分治docFile 指针与惰性加载原文档反复强调一条边界注册表文件本身只含元数据每个主题的正文hover 提示和文档图标展示的短文档存放在独立文件references/topics/ui/Id.md中。ui:Graph: { term: Graph, parent: null, synonyms: [GraphWindow, GraphCanvas, Operator Graph, Magnetic Graph, MagGraph], classes: [GraphWindow, MagGraphView], docFile: references/topics/ui/Graph.md }构建时parse_topics()检测到对应正文文件存在就在topics.json中记录docFile指针编辑器只在用户请求时才惰性加载该文件the editor loads that file lazily避免启动时读取 50 余个帮助文件。这些正文同样受格式约束——只能用编辑器 markdown 子集标题、加粗、行内代码、列表、[Op]/[ui:Topic]链接禁止图片和表格因为它们渲染在编辑器内的 markdown 视图中。以现有正文为例.help/references/topics/ui/Graph.md介绍了磁吸式连线、CtrlD 复制CtrlShiftD 保留连接、断开/重连、以及未连接的操作符不消耗渲染性能的实践建议.help/references/topics/ui/Timeline.md以[ui:DopeSheet|Dope sheet]这样的内链形式把 Timeline、Dope sheet、Animation area、Curve editor 串成一个导航结构.help/references/topics/ui/DopeSheet.md讲述了行式关键帧视图、auto-pin、ShiftK 清空、Alt 拖拽 warp point 重定时、跨参数复制粘贴等操作。ui:链接语法支持[ui:Id]与[ui:Id|显示文本]两种形式由帮助 UI 的自动链接器解析。[HelpUiID]从 UI 代码到 ui: 主题的锚点注册表里的classes:字段与源码锚点的对应靠的是编辑器命名空间下的HelpUiIDAttribute见.help外源码Editor/Gui/HelpUiIDAttribute.cs[AttributeUsage(AttributeTargets.Class, Inherited false)] internal sealed class HelpUiIDAttribute : Attribute { public string Id { get; } public HelpUiIDAttribute(string id) Id id; }原文档说明UI窗口window是未来[HelpUiID]特性的挂载点而概念Symbol、Field 等只作为文档锚点。源码中已有大量类携带该特性例如[HelpUiID(Graph)]→Editor/Gui/Graph/Window/GraphWindow.cs[HelpUiID(Timeline)]→Editor/Gui/Windows/TimeLine/TimeLineCanvas.cs[HelpUiID(DopeSheet)]→Editor/Gui/Windows/TimeLine/DopeSheetArea.cs[HelpUiID(CurveEditor)]→Editor/Gui/Windows/TimeLine/TimelineCurveEditor.cs[HelpUiID(PerformanceMonitor)]→Editor/Gui/Windows/Analyze/PerformanceWindow.cs[HelpUiID(SymbolBrowser)]→Editor/Gui/MagGraph/Interaction/PlaceholderCreation.cs特性值即注册表中ui:id的裸形式——[HelpUiID(Timeline)]对应ui:Timeline。该特性声明在T3.Editor.Gui命名空间内因此该命名空间下的类无需额外 using 即可使用。这为帮助系统与引导教程提供了一条从界面组件 → 注册表 → 帮助正文的完整链路。维护指南如何新增与更新一个 UI 主题综合原文档格式规范与脚本解析逻辑维护操作如下新增主题在ui-topics.md末尾或合适位置追加一个##块## New Feature Window id: NewFeatureWindow synonyms: New Feature, NFW parent: SomeParent classes: NewFeatureWindow要点id使用稳定的 PascalCase若省略解析器会用pascal(term)推导synonyms是解析成败的关键把视频中可能出现的口语说法、大小写变体都列进来会大小写不敏感匹配如无父主题可省略parent:行输出为null接着创建正文文件references/topics/ui/NewFeatureWindow.md内容限定在编辑器 markdown 子集内标题、加粗、代码、列表、[Op]/[ui:Topic]链接不要图片和表格若 UI 实现类在T3.Editor.Gui命名空间下可给类加上[HelpUiID(NewFeatureWindow)]特性建立锚点。更新正文直接编辑references/topics/ui/Id.md即可注册表无需改动——构建脚本只关心正文文件是否存在以决定docFile指针。重新生成索引仓库未提交analysis_to_index.py的产物时脚本输出nothing committed需要在改动后重新运行脚本重建references/indices/下的四个 JSON 文件。约束提醒操作符索引由docs/operators/自动生成切勿手改ui-topics.md与docs/operators/index.json分工明确前者只维护 UI 主题后者由SymbolUi派生。小结ui-topics.md以约 50 行格式规整的元数据块支撑起 TiXL 编辑器帮助系统中全部ui:主题的登记、解析与深链格式## termid/synonyms/parent/classes四字段机器可解析、人类可阅读解析analysis_to_index.py把它与视频分析合并产出videos.json、topics.json、mentions.json、mentions.full.json四个索引文件联动[HelpUiID]特性让源码类、注册表键、帮助正文三者一一对应分层元数据与正文分离正文按需惰性加载并严格限制在编辑器 markdown 子集内。理解这份文件就等于理解了 TiXL视频教程 → 提及分析 → 主题注册 → 编辑器内帮助这条完整的内容链路中手工与机器各自负责的边界。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考