WPF|快速添加新手引导功能（支持MVVM）

dotnet编程大全

专注C# WPF编程，dotnet编程大全

阅读导航

前言

案例一
案例二
案例三（本文介绍的方式）

如何使用？
控件如何开发的？
总结

1. 前言

案例一

站长分享过眾尋大佬的一篇 WPF 简易新手引导一文，新手引导的效果挺不错的，如下图：

该文给出的代码未使用 MVVM 的开发方式，提示框使用的用户控件、蒙版窗体样式与后台代码未分离，但给大家分享了开发新手引导功能的一个参考。

案例二

开源项目 AIStudio.Wpf.Controls，它的新手引导效果如下：

此开源项目也有参考上文（WPF 简易新手引导），并且重构为 MVVM 版本，方便绑定使用。

并且提示框显示的位置还跟随目标控件在主窗体中的位置灵活变换，不至于显示在蒙版窗体之外，如下图所示：

当目标控件右侧空间足够显示引导提示框时，引导提示框就显示在目标控件右侧；在右侧空间不足时，则将引导提示框显示在目标控件左侧：

案例三（本文介绍的方式）

站长根据上面的开源项目 AIStudio.Wpf.Controls 做了一个自己的版本 Dotnet9WPFControls，去掉了上一步按钮、增加标题绑定、下一步按钮内容绑定、提示框样式修改等，效果如下：

后面段落就介绍怎么使用 Dotnet9WPFControls 添加新手引导功能，并简单提及这个自定义控件的开发细节，主要原理还是看上文 WPF 简易新手引导哈。

希望对有需要给自己的项目添加新手引导功能的朋友有一定帮助，通过此文你也能修改出满足自己需求的效果。

2. 如何使用？

2.1 创建一个WPF项目

使用 .NET 6|7 创建一个名为 "NewbieGuideDemo" 的 WPF 解决方案：

2.2 引入nuget包

添加Nuget包1： Dotnet9WPFControls

该包提供引导控件及其样式，记得勾选“包括预发行版”，然后点击安装。

添加Nuget包2： Prism.DryIoc

使用该包，主要是使用 Prism 封装的一些 MVVM、IOC 功能，方便协助开发。

添加上述两个Nuget包后，项目工程文件定义如下：


             <ProjectSdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net6.0-windows</TargetFramework>
<Nullable>enable</Nullable>
<UseWPF>true</UseWPF>
</PropertyGroup>
<ItemGroup>
<PackageReferenceInclude="Dotnet9WPFControls"Version="0.1.0-preview.2"/>
<PackageReferenceInclude="Prism.DryIoc"Version="8.1.97"/>
</ItemGroup>
</Project>

2.3 添加样式文件

打开 App.xaml 文件，引入 Dotnet9WPFControls 默认主题文件：


             <prism:PrismApplication
x:Class="NewbieGuideDemo.App"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:prism="http://prismlibrary.com/">
<prism:PrismApplication.Resources>
<ResourceDictionary>
<ResourceDictionary.MergedDictionaries>
<ResourceDictionarySource="pack://application:,,,/Dotnet9WPFControls;component/Themes/Dotnet9WPFControls.xaml"/>
</ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
</prism:PrismApplication.Resources>
</prism:PrismApplication>

注意上面的根节点 <prism:PrismApplication /> ，同时修改 App.xaml.cs 文件，这里不做过多说明，具体使用请参考 Prism：


             usingPrism.DryIoc;
usingPrism.Ioc;
usingSystem.Windows;
namespaceNewbieGuideDemo
publicpartialclassApp:PrismApplication
protectedoverridevoidRegisterTypes(IContainerRegistrycontainerRegistry)
protectedoverrideWindowCreateShell()
returnContainer.Resolve<MainWindow>();

2.4 定义引导信息

给主窗体 MainWindow 添加一个 ViewModel 类： MainWindowViewModel.cs ：


             usingDotnet9WPFControls.Controls;
usingPrism.Mvvm;
usingSystem.Collections.Generic;
namespaceNewbieGuideDemo
publicclassMainWindowViewModel:BindableBase
privateGuideInfo?_guide;
publicGuideInfoGuide=>
_guide??=newGuideInfo("快速添加新手引导","这样添加新手引导，或许比较优雅");
publicList<GuideInfo>Guides=>new(){Guide};

在上面的 ViewModel 中，定义了一个引导属性 Guide ，这个属性是与提示框绑定展示：

第一个参数定义了引导提示框的标题 “快速添加新手引导”
第二个参数定义了引导提示框的提示内容 “这样添加新手引导，或许比较优雅”

第二个属性 Guides , 是一个引导信息列表，可绑定多个引导信息，点击按钮即会查看下一个引导，本示例为了演示，只写了一个引导。

2.5 界面绑定引导信息

先贴上 MainWindow.xaml 所有代码：


             <Window
x:Class="NewbieGuideDemo.MainWindow"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:prism="http://prismlibrary.com/"
xmlns:i="http://schemas.microsoft.com/xaml/behaviors"
xmlns:dotnet9="https://dotnet9.com"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
Title="Dotnet9WPF新手引导功能"Width="800"Height="450"
prism:ViewModelLocator.AutoWireViewModel="True"
AllowsTransparency="True"Background="Transparent"WindowStyle="None"
WindowStartupLocation="CenterScreen"
mc:Ignorable="d">
<Window.Resources>
<dotnet9:BindControlToGuideConverterx:Key="BindControlToGuideConverter"/>
</Window.Resources>
<Border
Background="White"BorderBrush="#ccc"BorderThickness="1"MouseLeftButtonDown="Border_MouseDown">
<ButtonHorizontalAlignment="Center"VerticalAlignment="Center"Content="点击测试新手引导">
<dotnet9:GuideHelper.GuideInfo>
<MultiBindingConverter="{StaticResourceBindControlToGuideConverter}">
<BindingRelativeSource="{RelativeSourceSelf}"/>
<BindingPath="Guide"/>
</MultiBinding>
</dotnet9:GuideHelper.GuideInfo>
<i:Interaction.Triggers>
<i:EventTriggerEventName="Click">
<i:ChangePropertyActionPropertyName="Display"TargetName="GuideControl"Value="True"/>
</i:EventTrigger>
</i:Interaction.Triggers>
</Button>
<dotnet9:GuideControlx:Name="GuideControl"Guides="{BindingGuides}">
<i:Interaction.Triggers>
<i:EventTriggerEventName="Loaded">
<i:ChangePropertyActionPropertyName="Display"Value="True"/>
</i:EventTrigger>
</i:Interaction.Triggers>
</dotnet9:GuideControl>
</Grid>
</Border>
</Window>

下面快速过一遍。

2.5.1 引入的命名空间说明

看上面的代码，引入了 dotnet9 和 prism 、 i 三个命名空间：

dotnet9 命名空间

引入引导控件 GuideControl 及转换器 BindControlToGuideConverter 。

prism 命名空间

主要用途在 prism:ViewModelLocator.AutoWireViewModel="True" 这句代码，将视图 MainWindow.xaml 与 MainWindowViewModel.cs 进行绑定，有兴趣可以看 Prism 源码，了解视图是如何发现ViewModel的约定规则。

i 命名空间

主要用此命名空间下的触发器，事件触发属性更改。

2.5.2 几处关键代码简单说明

上面代码贴的是引导控件（自定义控件）的使用方式（ 站长注 ：Dotnet9WPFControls 中还有引导窗体的方式，本文不做说明，要不然太占篇幅了，请查看控件Demo GuideWindowView)。

a: 将引导控件加到容器最上层

先关注后面的几行代码：


             <Grid>
<!--这里省略业务控件布局-->
<dotnet9:GuideControlx:Name="GuideControl"Guides="{BindingGuides}">
<i:Interaction.Triggers>
<i:EventTriggerEventName="Loaded">
<i:ChangePropertyActionPropertyName="Display"Value="True"/>
</i:EventTrigger>
</i:Interaction.Triggers>
</dotnet9:GuideControl>
</Grid>

将引导控件加到 Grid 容器最后，意图是让引导控件显示在所有控件的最上层（同一层级添加了多个控件，如果位置重叠，那么后加入的控件会显示在先添加的控件上方，呈现遮挡效果）；
绑定了前面 MainWindowViewModel 中定义的引导信息列表 Guides ，点击下一步按钮（本文显示为 我知道了 ）时，会按列表添加顺序切换引导信息；
使用 i:Interaction.Triggers 实现控件加载完成时，自动显示引导提示信息，见上面的示例三效果；

b：绑定目标控件与引导属性

目标控件的引导属性与目标控件引用绑定 ，引导界面显示时通过目标控件计算出目标控件的位置和大小，准确将目标控件标识出来，引导提示框定位也才能正确设置：


             <dotnet9:BindControlToGuideConverterx:Key="BindControlToGuideConverter"/>


             <ButtonHorizontalAlignment="Center"VerticalAlignment="Center"Content="点击测试新手引导">
<dotnet9:GuideHelper.GuideInfo>
<MultiBindingConverter="{StaticResourceBindControlToGuideConverter}">
<BindingRelativeSource="{RelativeSourceSelf}"/>
<BindingPath="Guide"/>
</MultiBinding>
</dotnet9:GuideHelper.GuideInfo>
<i:Interaction.Triggers>
<i:EventTriggerEventName="Click">
<i:ChangePropertyActionPropertyName="Display"TargetName="GuideControl"Value="True"/>
</i:EventTrigger>
</i:Interaction.Triggers>
</Button>

如上代码引入 BindControlToGuideConverter 转换器 , 该转换器是个黏合类，将目标控件的引用添加到引导对象上，转换器具体定义如下：


             publicclassBindControlToGuideConverter:IMultiValueConverter
publicobject?Convert(object[]values,TypetargetType,objectparameter,CultureInfoculture)
if(values.Length<2)
returnnull;
varelement=values[0]asFrameworkElement;
varguide=values[1]asGuideInfo;
if(guide!=null)
guide.TargetControl=element;
returnguide;