企业官网建设流程全解析

TiXL Help 窗口完全指南：即时悬停预览、上下文文档与视频学习资源

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

TiXL 编辑器内置的 Help（帮助）窗口是一个随选随显的上下文文档面板：你悬停或选中哪个算子，它就立刻在停靠面板里展示该算子的说明、参数与相关视频资源，全程零延迟、不打断创作流。本文基于仓库中的手动测试文档 .tests-manual/help-window.md 编写，并对照 HelpWindow.cs 等源码深入讲解其交互模型、历史机制与数据来源，读完你可以完整掌握 Help 窗口的全部操作方式，并理解它在编辑器内部的实现原理。

Help 窗口是什么

Help 窗口是 TiXL 编辑器内置的随行指南：它显示你最后一次选中或点击的算子（operator）或 UI 主题（UI topic）的文档，并且在悬停预览开关打开时，实时预览鼠标所指的任何目标。每一次上下文切换都会进入一条带去重逻辑的前进/后退历史；你还可以直接跳到讲解某个算子的视频片段；Learn标签页则展示当前版本的最新发布说明。

该功能最初是作为面向新手的"探索器"提出的（对应 实现计划 中记录的 issue #102）：悬停节点即可看到言简意赅的定义，让用户在不打断工作流的前提下熟悉节点图。最终实现为一个可停靠面板：无延迟地展示工具提示内容，叠加算子文档，以及文档索引中的交叉引用（算子 → 聚会视频片段、示例）。

从源码注释可以确认它的定位：

A dockable context-doc panel: it shows the documentation of the current help context — the last explicitly selected operator orui:topic — rendering its description, parameters, links, and the ranked "Discussed in meet-ups" resources.

窗口默认标题为Help，默认尺寸 420×600（见 HelpWindow.cs 的构造函数），可在主菜单栏的Windows菜单中打开。

打开 Help 窗口

操作步骤：在主菜单栏打开Windows菜单，点击Help。

预期结果：

• 出现一个标题为Help的窗口。如果它以浮动形式出现，可将其停靠到 Parameter 窗口 旁边。
• 头部显示两个标签页Help和Learn，其中Help为激活状态。
• 头部右侧显示‹›历史箭头，以及一个悬停预览开关图标（默认激活）。
• 在没有悬停或选中任何目标时，正文显示提示语"Hover or select an operator to see its description."（悬停预览开启时）或"Select an operator to see its description."（关闭时）。这两条文案分别对应 HelpWindow.cs 中的空状态分支。

窗口类带有[HelpUiID("HelpWindow")]特性（见 HelpUiIDAttribute.cs），意味着它本身也是一个可被ui:链接指向的 UI 主题；窗口注册在WindowManager中统一管理显示与布局。

悬停预览（Hover Preview）：零延迟的文档速览

操作步骤：保持 Help 窗口可见，在 Graph 窗口 中把鼠标在不同算子上方移动（不要点击）。

预期结果：

• Help 正文随指针跨越每个算子即时更新，没有任何悬停延迟。
• 正文显示该算子的名称、描述和参数详情。
• 当指针离开所有算子后，正文回退到上次选中的主题（或空状态提示语）。

实现原理：HoveredHelpTarget 逐帧代理

"无延迟"并非玄学，而是由 HoveredHelpTarget.cs 这个逐帧代理（broker）实现的：

• 图编辑器（MagGraphCanvas.DrawNode）和符号库（SymbolLibrary.DrawSymbolItemInstance）等"生产者"在每帧把鼠标悬停的算子/主题写入HoveredHelpTarget.SetOperator(...)/SetTopic(...)；
• 记录值带上了写入时的帧号，读取端（TryGetHovered）允许一帧的陈旧，从而容忍生产者与 Help 窗口之间任意的绘制顺序，不引入硬性的依赖关系；
• Help 窗口在GetTopicToShow()中优先取用悬停目标，悬停结束（超过一帧未更新）则回退到历史上下文（HelpWindow.cs）。

因为预览值从不进入历史，悬停浏览历史条目时也不会污染浏览轨迹。

关闭悬停预览开关

操作步骤：点击 Help 窗口头部的悬停预览图标将其关闭，然后在图中悬停算子、在符号库（Symbol Library）中悬停符号。

预期结果：

• Help 正文不再跟随悬停，停留在当前主题上。
• 符号库恢复显示它自己的描述工具提示（开关打开时该提示被省略，避免内容重复）。
• 该设置在编辑器重启后依然保留（写入UserSettings.Config.HelpHoverPreview）。做完测试后请把它重新打开，以便继续后续步骤。

实现细节：设置持久化与状态广播

开关由头部图标CustomComponents.ToggleTwoIconsButton(ref UserSettings.Config.HelpHoverPreview, ...)直接绑定用户设置（HelpWindow.cs），因此天然持久化。它还通过静态属性向外广播：

internal static bool HoverPreviewActive => IsOpen && UserSettings.Config.HelpHoverPreview;

符号库/符号浏览器和ui:链接在绘制自己的文档工具提示前会检查HoverPreviewActive（HelpWindow.cs），为真则省略自己的提示，避免"Help 窗口已经预览 + 自身工具提示"的双重内容。

跟随选中（Following the Selection）

操作步骤：在 Graph 窗口中点击一个算子将其选中，然后把鼠标移离所有算子（移到画布空白处）。

预期结果：

• 一旦指针不再位于其他算子上方，Help 正文就停留在当前选中的算子文档上。
• 选中另一个算子时，Help 正文切换到它并滚动回顶部（切换主题时调用ImGui.SetScrollY(0)，见 HelpWindow.cs）。

实现细节：图形选区即显式上下文

窗口每帧在UpdateContextFromGraphSelection()中读取当前图形选区：若选中了算子且其 SymbolId 与上次记录不同，就调用PushTopic(HelpTopic.ForOperator(symbolId))把它设为当前上下文；选区被清空则仅重置记录、不改变当前主题（HelpWindow.cs）。这与"最后显式操作胜出"（last explicit change wins）的交互模型一致。

符号库（Symbol Library）悬停与点击

操作步骤：打开 Symbol Library 窗口，不点击、仅把鼠标在树中的不同符号上移动；然后点击其中一个。

预期结果：

• Help 正文预览每个悬停符号的描述；在悬停预览开关打开期间，不出现单独的描述工具提示。
• 点击符号后，它成为 Help 窗口的当前主题（鼠标移开后依然保留）。
• 无论该算子当前是否出现在画布上，此行为都成立——符号库按符号 ID 直接解析主题，与画布实例无关。

符号缩略图（Symbol Thumbnail）

操作步骤：悬停或选中一个有缩略图的库算子（大多数带视觉输出的Lib算子都有）。

预期结果：

• 缩略图显示在 Help 正文顶部、算子名称与描述之上。
• 没有缩略图的算子直接从名称开始展示，不出现空隙或占位符。

从实现计划看，缩略图通过ThumbnailManager与PackageMeta提供（Plan_HelpWindow.md），有则显示、无则跳过，因此界面始终干净。

UI 主题链接（[ui:...]链接）

操作步骤：展示一个包含[ui:...]链接的文档（例如悬停 Guided Feature Tests 窗口的?文档图标，或 Learn 标签页中带蓝色 UI 主题链接的发布说明）。先悬停链接，再点击它。

预期结果：

• 悬停链接时，Help 窗口预览该主题的文档（悬停预览开关打开时不出现工具提示）。
• 点击后，Help 窗口展示该主题——标题、一个小的 "UI topic" 标签和文档正文——并且如果目标窗口已关闭会自动打开/聚焦它。

实现细节：ui:主题解析链

HelpTopic是一个可值比较的 record struct，同时支持两种主题：算子（按 SymbolId）与ui:主题（按键名），统一作为历史条目使用（HelpTopic.cs）。点击ui:链接或文档图标时调用HelpWindow.ShowTopic(topic, showWindow: true)，它会把主题压入历史并让窗口Config.Visible = true且请求焦点（HelpWindow.cs）。

ui:主题的文档正文由UiTopicDocs.TryGet解析（HelpTopic.cs）：内嵌的.help/embedded/<id>.md片段优先，否则回退到topics.json索引中的共享文档；解析结果按会话缓存。正文渲染支持 URL 与[OpName]算子链接（DrawUiTopicDoc，见 HelpWindow.cs）。

文档图标（Documentation Icons）

操作步骤：悬停某个带?文档图标的窗口头部（例如 Guided Feature Tests），然后点击它。

预期结果：

• 悬停时在 Help 窗口预览该文档（悬停预览关闭时则显示工具提示）。
• 点击后文档显示在 Help 窗口中并聚焦该窗口。
• 没有内嵌文档的主题，图标会改为在浏览器中打开 wiki 页面——这是ui:主题解析失败的兜底路径。

"Discussed in meet-ups" 视频资源列表

操作步骤：悬停或选中一个在视频中被讲解过的算子（例如[RaymarchField]或[SelectPointsWidthSDF]）。

预期结果：

• 描述下方出现一个视频资源区，默认展示最多两行（源码中折叠上限由CollapsedCount控制，当前为 3，见 VideoResourceList.cs）。每行包含 ▶ 播放图标、加粗的视频类型、相关性标注，例如Tutorial(3min · In-depth · Experiment)；行内不显示年龄。
• 全大写的区段标题会根据实际视频类型自适应：全是教程时显示 "RELATED TUTORIALS"，全是聚会视频时显示 "DISCUSSED IN MEET-UPS"，混合时显示 "WATCH & LEARN"（SectionHeader，见 VideoResourceList.cs）。
• 悬停某行时，该行获得白色文字与柔和圆角高亮（与 Asset Library 文件夹行的样式一致）；同一时间只有一行高亮。
• 当资源多于折叠上限时，出现 "Show all N" 行展开完整列表，"Show less" 再次收起（展开状态在主题切换时由Reset()复位，见 VideoResourceList.cs）。
• 较旧的视频片段显示淡淡的右对齐提示 "predates current UI"（源码中的常量 cue，见 VideoResourceList.cs）。
• 资源区固定在面板底部（上方有一条淡色分隔线），描述与参数列表在其上方独立滚动；资源区与描述文本左对齐，而非面板左边缘。

实现细节：手写链接与自动提取片段的统一排序

资源列表并非只来自视频索引，而是把两类来源合并、统一按分数排序（BuildRows，见 VideoResourceList.cs）：

1. 自动提取的视频片段（来自mentions.json）；
2. 手工编写的符号链接（旧版 "Links:" 区，如 wiki 页、示例链接），它们带有一个聚焦提升（focus-style boost），因此在排序中通常排在前列。

如果一条手写链接指向的视频已被自动提取，则该链接会被去重丢弃，保留质量更高的提取条目。行数据模型LinkRow(Title, Url, Description, Icon)承载这些链接。

视频资源行：工具提示与打开视频

操作步骤：悬停某条 meet-up 资源行，然后点击它。

预期结果：

• 工具提示立即出现：左侧是缩略图（带播放徽标以及Tutorial 5:23的类型 + 全长标注）；右侧是类似5MIN ON YOUTUBE / SEP 2024的全大写元数据头（对应 VideoResourceList.cs 的注释格式）、加粗白色的视频标题（过长时以...截断），以及 "what you'll learn" 说明文字。
• 如果缩略图不可用，工具提示仅显示文字。
• 点击该行会在浏览器中打开视频，并跳转到该算子被讲解的时间点（URL 带&t=<startSecond>s参数）。

数据模型：mentions.json 与 videos.json

这些资源来自文档交叉引用索引（由视频分析流水线构建，存放在.help/references/indices/，由 HelpIndex.cs 加载并缓存）。核心数据模型：

• OnlineVideoSegment：单个讲解片段，含VideoId、StartSecond、DurationSeconds、Url、相关性三轴Depth（passing/explained/in-depth）、Style（scripted/answer/discussion/experiment）、Confidence（0–100），以及面向用户的Note（以"你将学到什么"的口吻撰写，可含用于展示的[OpName]链接）。
• VideoInfo：视频目录条目（Id、Type∈ meetup/tutorial/update、Date、Title、Url、DurationSeconds）。

注意两个时长是有意区分的：工具提示头部的5MIN是片段时长，而缩略图徽标里的5:23是视频全长，两者都展示、各有用途（Plan_HelpWindow.md §7）。缩略图按视频 ID 从.help/.tmp/video-thumbnails/<id>.jpg加载（VideoThumbnails负责 WIC → 纹理 → SRV 的转换与会话级缓存）；该目录在发布构建中尚不随二进制分发，因此缩略图目前主要在开发检出（dev checkout）中可见。

历史前进与后退（Back / Forward）

操作步骤：在图中依次选中三个不同算子，然后使用头部的‹和›箭头按钮。

预期结果：

• ‹后退到之前显示过的主题，›再次前进。
• 浏览历史时悬停其他算子只会产生预览——松开悬停即回到当前所在的历史条目。
• 在历史中途选中或点击新主题会"跳出"历史：新主题被显示并成为最新的历史条目。
• 重新选中已在历史中的主题不会产生重复条目。
• 到达历史开头或结尾时，箭头变暗且无任何操作。

实现细节：去重历史（NavigationHistory 风格）

PushTopic实现了一套去重规则（HelpWindow.cs），与UiModel.ProjectHandling.NavigationHistory的语义一致：

• 最新条目在索引 0；
• 新主题不在历史中 → 插入到最前；
• 新主题是当前条目的相邻条目→ 仅移动索引（保持列表顺序）；
• 新主题在更远处 → 将其移动到最前并跳到它。

而GetTopicToShow()保证悬停预览永不进入历史，所以在历史中漫游时悬停其他算子只是"借用"预览，松开即归还（HelpWindow.cs）。窗口内链接的悬停还有一个细节：IsDrawingContent为真时（即 Help 窗口正在绘制自身内容），窗口内部的文档链接保留自己的工具提示而不是触发悬停预览，避免"正文在光标下被换掉"导致的闪烁，点击导航则照常工作（HelpWindow.cs）。

Learn 标签页：发布说明

操作步骤：点击头部右侧的Learn标签。

预期结果：

• 正文显示当前版本的发布说明，格式美观，包含可点击的算子链接；如果该构建未附带发布说明，则显示"No release notes for this version yet."。
• 历史箭头和悬停预览开关隐藏；悬停算子不会改变 Learn 内容。
• 切回Help标签后恢复算子文档视图。

从实现计划看，Learn 标签页接入的是已有的ReleaseNotesLoader（Plan_HelpWindow.md §Status）；"有更新"指示点（has-updates dot）属于后续阶段的功能，当前版本尚未包含。

手工测试要点速查

结合本文所依据的 .tests-manual/help-window.md 手动测试文档，可按以下顺序回归验证（前置条件：打开一个包含若干库算子的项目，最好包含聚会视频中讲解过的算子，如[SphereSDF]、[FastBlur]、[RaymarchField]）：

总结

TiXL 的 Help 窗口把"查文档"从一次打断变成了一种可以随手完成的探索动作：无延迟的悬停预览由HoveredHelpTarget逐帧代理支撑，上下文 + 去重历史解决了"跟随选中"与"自由浏览"之间的矛盾，而mentions.json/videos.json/topics.json三类索引让算子文档、UI 主题与视频讲解片段交叉互联。无论你是刚上手 TiXL 的新用户，还是想为编辑器扩展帮助系统的开发者，都可以从 HelpWindow.cs 与 Editor/Gui/Help/ 目录下的实现中继续深入。

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