这篇记录一下 CodeWF.AvaloniaControls新增的Guide引导控件，以及它在 Vex 里的实际落地。

新手引导这种控件，如果只讲属性和实现会比较抽象。它本质上是一个强交互控件：遮罩、高亮、卡片定位、菜单展开、TabItem 切换、目标控件延迟出现、弹层里继续定位目标，这些都需要先看画面，再看代码才容易理解。

先看 Vex 中的菜单类引导流程。完整的新手引导覆盖欢迎页、文件菜单、段落菜单、格式菜单、视图菜单、主题菜单、侧边栏、编辑区、预览区、状态栏和帮助菜单。下面这段 GIF 重点截取菜单和二级菜单步骤，能看到 Guide会在步骤切换时主动打开菜单，再高亮菜单里的MenuItem。

这段 GIF 已按当前 Vex 重新录制。文件菜单现在会按内容完整展开，导出入口和关闭入口可以一次看到，不再出现旧版下拉高度限制带来的菜单内滚动。

控件库 Demo 里也补了两个更小的例子，分别演示基础多步骤引导、封面内容、自定义操作按钮，以及非模态提示和文本进度指示器。

Guide的源码在这里：

https://github.com/dotnet9/CodeWF.AvaloniaControls/tree/main/src/CodeWF.AvaloniaControls/Controls/Guide

Vex 的落地代码主要在这里：

https://github.com/dotnet9/Vex/tree/main/src/Vex/Modules/Shell/Views/MainWindow.axamlhttps://github.com/dotnet9/Vex/tree/main/src/Vex/Modules/Shell/Views/MainWindow.axaml.cshttps://github.com/dotnet9/Vex/tree/main/src/Vex/Modules/Shell/Views/ShellTitleMenuView.axamlhttps://github.com/dotnet9/Vex/tree/main/src/Vex/Modules/Shell/Views/ShellTitleMenuView.axaml.cs为什么要做 Guide

Avalonia 里有 Popup、MenuItem、TabControl、Flyout这些基础控件，但它们不会直接组合成一个完整的新手引导流程。

一个真正能用在桌面软件里的引导控件，至少要处理这些问题：

多步骤流程：上一页、下一页、完成、关闭。

每一步绑定不同目标控件。

没有目标控件时居中显示说明。

有目标控件时绘制遮罩，并在目标周围挖出高亮区域。

引导卡片根据目标位置显示在上、下、左、右等方向。

目标在滚动区域内时自动滚动到可见位置。

目标控件晚一点才出现时，等待并重新定位。

目标在 Menu、Popup、Flyout这种弹层里时，也能正确高亮。

布局变化、窗口大小变化后，重新计算高亮区域。

我参考的是 AtomUI里的Tour漫游式引导控件。AtomUI 的Tour把主控件做成TemplatedControl，步骤抽象为ITourStepOption，再用弹层和遮罩层组合出引导效果。这个方向很适合 Avalonia。

CodeWF 的 Guide沿用了这个思路，但实现上更贴近桌面软件里的真实入口：

使用 GuideOverlay自绘遮罩和高亮区域。 使用 Popup显示引导卡片。 通过 GuideStep声明每一步，也支持StepsSource数据源。 通过 StepOpening和OpeningCommand支持动态业务动作。 通过 TargetResolveDelay等待菜单、TabItem、Popup 内容完成布局。 对弹层里的 MenuItem做额外处理，避免菜单 light-dismiss 影响“下一步”按钮。控件结构

Guide相关类型比较清晰：

Guide：主控件，管理打开关闭、当前步骤、遮罩、弹层和目标解析。 GuideStep：声明式步骤，用在 XAML 里。 GuideStepOption：代码创建步骤时使用。 IGuideStepOption：步骤统一接口。 GuideOverlay：负责绘制遮罩和目标高亮洞。 DefaultGuideIndicator：默认圆点进度指示器。 TextGuideIndicator：文本进度指示器，例如1 / 6。 GuidePlacementMode：卡片位置枚举。 GuideMissingTargetBehavior：目标缺失时居中、跳过或关闭。

主题文件在：

https://github.com/dotnet9/CodeWF.AvaloniaControls/tree/main/src/CodeWF.AvaloniaControls.Themes/Themes/Controls/Guide.axaml

模板里有三个关键弹层：

PART_MaskPopup：当前窗口上的遮罩。 PART_TargetMaskPopup：目标在其他弹层或TopLevel里时使用。 PART_Popup：引导卡片本身。

这个结构让业务侧只关心“要引导哪几个目标”，控件内部负责遮罩、定位、按钮、指示器和清理。

基础用法

最简单的用法是把 Guide放到页面根布局里，给每个GuideStep绑定目标控件：

打开引导：

BasicGuide.GoTo(0);BasicGuide.Show;

如果要做非模态提示，可以关闭遮罩，并把进度指示器换成文本：