TiXL Help 窗口完全指南即时悬停预览、上下文文档与视频学习资源【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3TiXL 编辑器内置的 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:链接在绘制自己的文档工具提示前会检查HoverPreviewActiveHelpWindow.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 LEARNSectionHeader见 VideoResourceList.cs。悬停某行时该行获得白色文字与柔和圆角高亮与 Asset Library 文件夹行的样式一致同一时间只有一行高亮。当资源多于折叠上限时出现 Show all N 行展开完整列表Show less 再次收起展开状态在主题切换时由Reset()复位见 VideoResourceList.cs。较旧的视频片段显示淡淡的右对齐提示 predates current UI源码中的常量 cue见 VideoResourceList.cs。资源区固定在面板底部上方有一条淡色分隔线描述与参数列表在其上方独立滚动资源区与描述文本左对齐而非面板左边缘。实现细节手写链接与自动提取片段的统一排序资源列表并非只来自视频索引而是把两类来源合并、统一按分数排序BuildRows见 VideoResourceList.cs自动提取的视频片段来自mentions.json手工编写的符号链接旧版 Links: 区如 wiki 页、示例链接它们带有一个聚焦提升focus-style boost因此在排序中通常排在前列。如果一条手写链接指向的视频已被自动提取则该链接会被去重丢弃保留质量更高的提取条目。行数据模型LinkRow(Title, Url, Description, Icon)承载这些链接。视频资源行工具提示与打开视频操作步骤悬停某条 meet-up 资源行然后点击它。预期结果工具提示立即出现左侧是缩略图带播放徽标以及Tutorial 5:23的类型 全长标注右侧是类似5MIN ON YOUTUBE / SEP 2024的全大写元数据头对应 VideoResourceList.cs 的注释格式、加粗白色的视频标题过长时以...截断以及 what youll learn 说明文字。如果缩略图不可用工具提示仅显示文字。点击该行会在浏览器中打开视频并跳转到该算子被讲解的时间点URL 带tstartSeconds参数。数据模型mentions.json 与 videos.json这些资源来自文档交叉引用索引由视频分析流水线构建存放在.help/references/indices/由 HelpIndex.cs 加载并缓存。核心数据模型OnlineVideoSegment单个讲解片段含VideoId、StartSecond、DurationSeconds、Url、相关性三轴Depthpassing/explained/in-depth、Stylescripted/answer/discussion/experiment、Confidence0–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 标签页接入的是已有的ReleaseNotesLoaderPlan_HelpWindow.md §Status有更新指示点has-updates dot属于后续阶段的功能当前版本尚未包含。手工测试要点速查结合本文所依据的 .tests-manual/help-window.md 手动测试文档可按以下顺序回归验证前置条件打开一个包含若干库算子的项目最好包含聚会视频中讲解过的算子如[SphereSDF]、[FastBlur]、[RaymarchField]测试项关键断言打开窗口Windows→Help出现Help/Learn双标签、‹›与悬停开关空状态文案正确悬停预览图内跨算子移动正文即时更新、无延迟离开后回退开关持久化关闭悬停预览后重启编辑器设置保留跟随选中选中算子并移开鼠标正文停留切换选中项滚动回顶部符号库悬停预览 点击固定主题开关打开时无重复工具提示缩略图有缩略图的算子顶部显示图片无缩略图的无空隙ui:链接悬停预览、点击导航并打开/聚焦目标窗口文档图标有内嵌文档的在 Help 中展示无内嵌文档的走浏览器 wiki视频资源标题自适应、行内无年龄、旧片段有 predates current UI 提示、Show all N 展开收起、底部固定资源工具提示缩略图 元数据头 标题截断 说明点击跳到视频对应时间点历史去重、中途跳出、箭头到尽头变暗Learn 标签显示发布说明无悬停干扰切回 Help 恢复总结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考