企业官网建设流程全解析

• AI 技能
• AI 插件
• 人工智能

复杂业务场景中的多步骤流程（如创建项目、分步配置、向导式部署）是桌面应用开发的常见痛点。本文基于开源仓库plugins/agentic-awesome-skills-claude/skills/avalonia-viewmodels-zafiro/中的技能文档，系统讲解如何在 Avalonia 应用中借助Zafiro工具包与ReactiveUI，通过SlimWizard与WizardBuilder以声明式方式定义步骤、编排导航逻辑并获取最终结果。阅读完本文，你将掌握向导的构建语法、四种导航规则的适用场景、与INavigator的集成方式，以及WithCompletionFinalStep/WithCommitFinalStep等收尾配置的最佳实践。

一、为什么需要 SlimWizard：多步骤流程的声明式解决思路

在传统的 Avalonia + ReactiveUI 应用中，多步骤流程往往靠手写状态机或大量布尔标志位（step1Visible、step2Visible……）驱动，代码随着步骤增多迅速变得难以维护：导航条件散落各处、返回逻辑重复实现、校验时机不统一。

Zafiro 的SlimWizard模式将这些问题收敛为一个声明式的步骤链：每一步对应一个 ViewModel，步骤之间的前进条件、跳转参数、最终结果都以链式 API 表达。正如该技能文档所强调的，SlimWizard的核心价值是让流程“可声明、可维护”，同时它自动处理 “Back” 返回命令，从而在不同流程之间提供一致的用户体验（见 wizards.md）。

该技能文档所属的整套技能（见 SKILL.md）将其列为五大核心原则之一：

1. 函数式响应式编程：基于ReactiveObject、WhenAnyValue管理状态；
2. 增强命令：使用IEnhancedCommand获得进度上报与名称/文本元数据；
3. 向导模式：用SlimWizard+WizardBuilder实现复杂流程；
4. 自动 Section 发现：[Section]特性注册 UI 分区；
5. 干净组合：DataTypeViewLocator映射 ViewModel 与 View。

其中向导模式正是本文要深入的主题，它与技能文档中的 ViewModel 命令体系（viewmodels.md）、导航基础设施（navigation_sections.md）天然互补：向导中的每一步 ViewModel 遵循同一套响应式命令与校验约定。

二、定义向导：WizardBuilder 链式语法详解

向导的骨架由WizardBuilder构建。每一步对应一个 ViewModel，StartWith给出第一步的工厂方法，Then负责串联后续步骤，且每一步可以读取前一步的结果作为参数。技能文档给出了一个完整示例：

SlimWizard<string> wizard = WizardBuilder .StartWith(() => new Step1ViewModel(data)) .NextUnit() .WhenValid() .Then(prevResult => new Step2ViewModel(prevResult)) .NextCommand(vm => vm.CustomNextCommand) .Then(result => new SuccessViewModel("Done!")) .Next((_, s) => s, "Finish") .WithCompletionFinalStep();

逐段拆解这段链式调用的含义：

注意泛型参数SlimWizard<string>：尖括号中的类型就是向导最终产出的结果类型。在这个例子里，整个过程最终返回一个string（“Done!”），而实际项目中它往往是一个领域模型、DTO 或保存指令。

2.1 步骤之间的数据传递

Then(prevResult => new Step2ViewModel(prevResult))这类写法揭示了SlimWizard的数据流设计：每一步的工厂函数接收上一步的返回值，从而把多步骤流程组织成一条类型安全的数据管道。这意味着：

• 步骤间传递的是强类型对象，而非object或全局状态；
• 向导结果类型（如SlimWizard<MyResult>）在编译期即可约束；
• 每一步 ViewModel 只关心自己需要的那部分数据，职责清晰。

这种设计让多步骤表单、配置流、创建流程等场景可以轻松表达“第 2 步依赖第 1 步的输入”这类常见诉求。

三、四种导航规则：何时前进由你决定

SlimWizard允许为每一步配置前进触发条件，这是声明式流程的核心灵活性所在。技能文档归纳了四种导航规则：

其中几个规则通常组合使用，例如示例中的.NextUnit().WhenValid()：既要求校验通过，又要求收到前进信号。这种组合语义让“按钮可点”与“数据合法”两件事被解耦表达，而不是在按钮的CanExecute里写满判断。

从实现角度看，NextCommand与技能文档中强调的IEnhancedCommand体系一脉相承（见 viewmodels.md）：CustomNextCommand本身就是一个由ReactiveCommand.Create/CreateFromTask创建并经.Enhance(...)包装的增强命令，它天然携带Name、Text等元数据，并可配合HandleErrorsWith把失败信息路由到NotificationService——命令失败时自然不会触发前进，错误处理也因此统一。

四、导航集成：用 INavigator 驱动向导

SlimWizard本身只负责定义流程，实际的页面切换交给 Zafiro 的导航抽象INavigator。技能文档给出了集成范式：

public async Task CreateSomething() { var wizard = BuildWizard(); var result = await wizard.Navigate(navigator); // Handle result }

要点解读：

• BuildWizard()内部用WizardBuilder组装出SlimWizard<TResult>；
• wizard.Navigate(navigator)是异步方法，向导运行时由navigator负责在每一步 ViewModel 之间切换视图；
• await返回的是向导最终结果，调用方在流程结束后统一处理，而不是在各步骤里散落地收集数据；
• “返回”导航由SlimWizard内部自动接管，因此每步都会获得一致的 Back 体验，调用方无需为每步单独实现回退逻辑。

INavigator同时是技能文档中通用导航的基础设施（见 navigation_sections.md），例如navigator.Navigate(() => new DetailsViewModel())这样的普通页面跳转与向导导航共用同一抽象，保持了整个应用的导航模型统一。

五、步骤收尾配置：Completion 与 Commit 的选择

向导最后一步如何处理，是很多实现容易含糊的地方。SlimWizard提供了两个收尾选项，语义差异非常明确：

• WithCompletionFinalStep()：最后一步完成即标记向导结束。适用于纯流程式向导——最后一步通常是“完成/摘要”页，展示结果或给出提示，不需要额外副作用。
• WithCommitFinalStep()：通常用于向导末尾执行最终“保存（Save）”或“部署（Deploy）”动作的场景。最后一步负责触发真正的业务提交（例如写入数据库、发布配置、启动部署流程），提交成功后才宣告完成。

选择依据很简单：如果向导的终点是“告知结果”，用Completion；如果终点是“执行动作”，用Commit。这两种配置与NextCommand天然搭配——例如 Commit 步骤可以绑定vm.SaveCommand作为前进条件，确保只有保存成功才能完成向导。

六、与整套技能的配合：让向导融入应用

向导并非孤立存在，在avalonia-viewmodels-zafiro技能体系中，它和其他四块内容构成完整的 ViewModel 开发范式：

1. 步骤 ViewModel 本身遵循 viewmodels.md 的规范：继承ReactiveObject、用[Reactive]源生成器特性声明属性、用WhenAnyValue派生计算属性、命令经.Enhance()包装并通过CompositeDisposable管理生命周期。向导每一步的“校验”与“命令”，底层依赖的就是这套约定。
2. 向导页面切换依赖 navigation_sections.md 中的INavigator；若向导以 Section 形式嵌入 Shell（如“创建”作为一个可切换分区），还可借助[Section]特性自动注册。
3. 向导内 ViewModel 的实例化与 View 映射由 composition.md 中的CompositionRoot+DataTypeViewLocator承接：在App.axaml的Application.DataTemplates中注册<DataTypeViewLocator />，在组合根里以合适的作用域注册各步骤 ViewModel，向导工厂通过 DI 解析依赖（必要时用ActivatorUtilities.CreateInstance手动实例化并注入依赖）。

技能文档还给出了一条落地参考：真实项目Angor中的CreateProjectFlowV2.cs即复杂 Wizard 构建的范例（见 SKILL.md），可作为进阶学习时对照的工程实现。

七、小结

SlimWizard模式把 Avalonia 多步骤流程从“手写状态机”提升为“声明式数据管道”：

• 构建：WizardBuilder.StartWith(...).Then(...)链式定义步骤与数据传递，泛型结果类型保证类型安全；
• 导航：NextUnit、NextCommand、WhenValid、Always四种规则按需组合，精确表达前进时机；
• 集成：通过INavigator异步驱动，Back 命令自动处理，调用方只需等待最终结果；
• 收尾：按业务语义选择WithCompletionFinalStep（告知结果）或WithCommitFinalStep（执行保存/部署动作）。

将这套模式与同技能文档中的响应式 ViewModel、增强命令、Section 导航与组合根一起使用，可以在 Avalonia 应用中构建出结构清晰、易于测试、可长期维护的向导式交互。相关技能文件完整保存在仓库plugins/agentic-awesome-skills-claude/skills/avalonia-viewmodels-zafiro/目录下（英文原版位于plugins/agentic-awesome-skills/skills/avalonia-viewmodels-zafiro/），包含 SKILL.md、viewmodels.md、wizards.md、navigation_sections.md、composition.md 五份文档，可随时查阅对照。

• AI 技能
• AI 插件
• 人工智能