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 editor's 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, flags=re.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 ⊂ Timeline	"show 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()] = tid）；
parent在最终输出topics.json时会被规范化为"ui:<parent>"形式（无 parent 则为null）；
生成topics.json时若发现references/topics/ui/<Id>.md文件存在，会记录docFile指针，供编辑器惰性加载正文（见后文）。

主题注册表全览：51 个`ui:`主题

以下是原文档登记的全部主题，按功能领域归类（term / id / 关键别名与 classes 摘要）：

编辑器主画布与交互

主题 term	id	关键点
Graph	`Graph`	别名 MagGraph、GraphCanvas、Operator Graph；classes:`GraphWindow`,`MagGraphView`
Timeline	`Timeline`	classes:`TimeLineCanvas`
Dope sheet	`DopeSheet`	parent: Timeline；classes:`DopeSheetArea`
Animation area	`AnimationArea`	parent: Timeline；classes:`TimelineDetailsArea`
Curve editor	`CurveEditor`	parent: Timeline；别名 Curve area；classes:`TimelineCurveEditor`
Control bar	`ControlBar`	别名 tool bar；classes:`TimeControls`
Sections	`Annotations`	别名 annotations, frames；classes:`MagGraphSection`
Gizmo	`Gizmo`	classes:`TransformGizmoHandling`

窗口与面板

主题 term	id	关键点
Parameter window	`ParameterWindow`	别名 Parameter View；classes:`ParameterWindow`
Output Window	`OutputWindow`	classes:`OutputWindow`
Settings	`Settings`	别名 Settings Window, User Settings；classes:`SettingsWindow`
Project Settings	`ProjectSettings`	别名 Composition settings；classes:`ProjectSettingsWindow`
Variation window	`VariationWindow`	classes:`VariationsWindow`
Search window	`SearchWindow`	别名 Control F, Find；classes:`SearchDialog`
Performance monitor	`PerformanceMonitor`	别名 performance window, performance graph；classes:`PerformanceWindow`
Control view	`ControlView`	classes:`SnapshotControlView`
Console log	`ConsoleLog`	别名 log window, console window；classes:`ConsoleLogWindow`
Project panel	`ProjectPanel`	别名 project list, home；classes:`ProjectsPanel`
IO view	`IoView`	classes:`IoViewWindow`
Splash screen	`SplashScreen`	classes:`SplashScreen`
Welcome window	`WelcomeWindow`	无 classes 字段
Welcome alpha window	`WelcomeAlphaWindow`	classes:`WelcomeAlphaWindow`

渲染与资源

主题 term	id	关键点
Render settings	`RenderSettings`	classes:`RenderWindow`
Output settings	`OutputSettings`	classes:`OutputWindowState`
Shader graph	`ShaderGraph`	classes:`ShaderGraphNode`
Shader node	`ShaderNode`	parent: ShaderGraph；classes:`ShaderGraphNode`
Field	`Field`	别名 SDF, distance field, value field；classes:`ShaderGraphNode`
Asset	`Asset`	别名 Assets；classes:`Asset`
Asset Library	`AssetLibrary`	classes:`AssetLibrary`
Symbol Library	`SymbolLibrary`	classes:`SymbolLibrary`
Symbol browser	`SymbolBrowser`	classes:`PlaceholderCreation`

核心概念对象

主题 term	id	关键点
Symbol	`Symbol`	classes:`Symbol`
Composition	`Composition`	classes:`Instance`
User Project	`UserProject`	classes:`EditableSymbolProject`
Operator Settings	`OperatorSettings`	别名 Operator names；classes:`ParameterSettings`
Evaluation context	`EvaluationContext`	别名 context, variables；classes:`EvaluationContext`
Time overrides	`TimeOverrides`	classes:`EvaluationContext`
Local time	`LocalTime`	parent: EvaluationContext
Play back time	`PlaybackTime`	parent: EvaluationContext；classes:`Playback`
Idle motion	`IdleMotion`	classes:`Playback`

学习与引导系统

主题 term	id	关键点
SkillQuest	`SkillQuest`	别名 Skill Quest tutorials, Tutorials；classes:`SkillTraining`
Skill Quest Level	`SkillQuestLevel`	parent: SkillQuest；classes:`QuestLevel`
Skill Map	`SkillMap`	parent: SkillQuest；别名 Skill Quest Map；classes:`SkillMapData`

小型编辑控件

主题 term	id	关键点
Gradient editor	`GradientEditor`	classes:`GradientEditor`
Color editor	`ColorEditor`	classes:`ColorEditPopup`
Infinity slider	`InfinitySlider`	classes:`InfinitySliderOverlay`
Parameter popup	`ParameterPopup`	classes:`ParameterPopUp`
Focus mode	`FocusMode`	classes:`LayoutHandling`

播放与音频

主题 term	id	关键点
Player	`Player`	无 classes 字段
Player exporter	`PlayerExporter`	parent: Player；classes:`PlayerExporter`
Audio input	`AudioInput`	classes:`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/，纯仓库内运行，不触碰 git）：
- videos.json— 视频元数据（id、类型、日期、标题、时长、摘要、focusesOn）；
- topics.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 | passing；style∈scripted | answer | discussion | experiment；purpose∈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介绍了磁吸式连线、Ctrl+D 复制（Ctrl+Shift+D 保留连接）、断开/重连、以及"未连接的操作符不消耗渲染性能"的实践建议；
.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、Shift+K 清空、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:主题的登记、解析与深链：

格式：## term+id/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），仅供参考

企业官网建设流程全解析