WPF|快速添加新手引導功能（支持MVVM）-有解無憂

閱讀導航

前言

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

如何使用？
控制元件如何開發的？
總結

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包后，專案工程檔案定義如下：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net6.0-windows</TargetFramework>
    <Nullable>enable</Nullable>
    <UseWPF>true</UseWPF>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Dotnet9WPFControls" Version="0.1.0-preview.2" />
    <PackageReference Include="Prism.DryIoc" Version="8.1.97" />
  </ItemGroup>

</Project>

2.3 添加樣式檔案

打開 App.xaml 檔案，引入 Dotnet9WPFControls 默認主題檔案：

<prism:PrismApplication
    x:
    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>
                <ResourceDictionary Source="pack://application:,,,/Dotnet9WPFControls;component/Themes/Dotnet9WPFControls.xaml" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </prism:PrismApplication.Resources>
</prism:PrismApplication>

注意上面的根節點 <prism:PrismApplication />，同時修改App.xaml.cs檔案，這里不做過多說明，具體使用請參考 Prism：

using Prism.DryIoc;
using Prism.Ioc;
using System.Windows;

namespace NewbieGuideDemo
{
    public partial class App : PrismApplication
    {
        protected override void RegisterTypes(IContainerRegistry containerRegistry)
        {
        }

        protected override Window CreateShell()
        {
            return Container.Resolve<MainWindow>();
        }
    }
}

2.4 定義引導資訊

給主表單 MainWindow 添加一個 ViewModel 類：MainWindowViewModel.cs：

using Dotnet9WPFControls.Controls;
using Prism.Mvvm;
using System.Collections.Generic;

namespace NewbieGuideDemo
{
    public class MainWindowViewModel : BindableBase
    {
        private GuideInfo? _guide;

        public GuideInfo Guide =>
            _guide ??= new GuideInfo("快速添加新手引導", "這樣添加新手引導，或許比較優雅");

        public List<GuideInfo> Guides => new() {Guide};
    }
}

在上面的 ViewModel 中，定義了一個引導屬性 Guide，這個屬性是與提示框系結展示：

第一個引數定義了引導提示框的標題 “快速添加新手引導”
第二個引數定義了引導提示框的提示內容 “這樣添加新手引導，或許比較優雅”

第二個屬性 Guides, 是一個引導資訊串列，可系結多個引導資訊，點擊按鈕即會查看下一個引導，本示例為了演示，只寫了一個引導，

2.5 界面系結引導資訊

先貼上 MainWindow.xaml 所有代碼：

<Window
    x:
    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="Dotnet9 WPF新手引導功能"  Height="450"
    prism:ViewModelLocator.AutoWireViewModel="True"
    AllowsTransparency="True" Background="Transparent" WindowStyle="None" 
    WindowStartupLocation="CenterScreen"
    mc:Ignorable="d">
    <Window.Resources>
        <dotnet9:BindControlToGuideConverter x:Key="BindControlToGuideConverter" />
    </Window.Resources>
    <Border
        Background="White" BorderBrush="#ccc" BorderThickness="1" MouseLeftButtonDown="Border_MouseDown">
        <Grid>
            <Button HorizontalAlignment="Center" VerticalAlignment="Center" Content="點擊測驗新手引導">
                <dotnet9:GuideHelper.GuideInfo>
                    <MultiBinding Converter="{StaticResource BindControlToGuideConverter}">
                        <Binding RelativeSource="{RelativeSource Self}" />
                        <Binding Path="Guide" />
                    </MultiBinding>
                </dotnet9:GuideHelper.GuideInfo>
                <i:Interaction.Triggers>
                    <i:EventTrigger EventName="Click">
                        <i:ChangePropertyAction PropertyName="Display" TargetName="GuideControl" Value="https://www.cnblogs.com/Dotnet9-com/archive/2022/05/28/True" />
                    </i:EventTrigger>
                </i:Interaction.Triggers>
            </Button>

            <dotnet9:GuideControl x:Name="GuideControl" Guides="{Binding Guides}">
                <i:Interaction.Triggers>
                    <i:EventTrigger EventName="Loaded">
                        <i:ChangePropertyAction PropertyName="Display" Value="https://www.cnblogs.com/Dotnet9-com/archive/2022/05/28/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:GuideControl x:Name="GuideControl" Guides="{Binding Guides}">
        <i:Interaction.Triggers>
            <i:EventTrigger EventName="Loaded">
                <i:ChangePropertyAction PropertyName="Display" Value="https://www.cnblogs.com/Dotnet9-com/archive/2022/05/28/True" />
            </i:EventTrigger>
        </i:Interaction.Triggers>
    </dotnet9:GuideControl>
</Grid>

將引導控制元件加到 Grid 容器最后，意圖是讓引導控制元件顯示在所有控制元件的最上層（同一層級添加了多個控制元件，如果位置重疊，那么后加入的控制元件會顯示在先添加的控制元件上方，呈現遮擋效果）；
系結了前面 MainWindowViewModel 中定義的引導資訊串列 Guides，點擊下一步按鈕（本文顯示為我知道了）時，會按串列添加順序切換引導資訊；
使用 i:Interaction.Triggers實作控制元件加載完成時，自動顯示引導提示資訊，見上面的示例三效果；

b：系結目標控制元件與引導屬性

目標控制元件的引導屬性與目標控制元件參考系結，引導界面顯示時通過目標控制元件計算出目標控制元件的位置和大小，準確將目標控制元件標識出來，引導提示框定位也才能正確設定：

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

<Button HorizontalAlignment="Center" VerticalAlignment="Center" Content="點擊測驗新手引導">
    <dotnet9:GuideHelper.GuideInfo>
        <MultiBinding Converter="{StaticResource BindControlToGuideConverter}">
            <Binding RelativeSource="{RelativeSource Self}" />
            <Binding Path="Guide" />
        </MultiBinding>
    </dotnet9:GuideHelper.GuideInfo>
    <i:Interaction.Triggers>
        <i:EventTrigger EventName="Click">
            <i:ChangePropertyAction PropertyName="Display" TargetName="GuideControl" Value="https://www.cnblogs.com/Dotnet9-com/archive/2022/05/28/True" />
        </i:EventTrigger>
    </i:Interaction.Triggers>
</Button>

如上代碼引入 BindControlToGuideConverter 轉換器, 該轉換器是個黏合類，將目標控制元件的參考添加到引導物件上，轉換器具體定義如下：

public class BindControlToGuideConverter : IMultiValueConverter
{
    public object? Convert(object[] values, Type targetType, object parameter, CultureInfo culture)
    {
        if (values.Length < 2)
        {
            return null;
        }

        var element = values[0] as FrameworkElement;
        var guide = values[1] as GuideInfo;
        if (guide != null)
        {
            guide.TargetControl = element;
        }

        return guide;
    }

    public object[] ConvertBack(object value, Type[] targetTypes, object parameter, CultureInfo culture)
    {
        throw new NotImplementedException();
    }
}

目標控制元件的參考賦值給引導物件的 TargetControl 屬性，

Demo代碼完畢，直接運行專案，效果如下，原始碼在這 NewbieGuideDemo：

3. 控制元件如何開發的？

關于原理，WPF 簡易新手引導這篇介紹的不錯，可以先看看，

關于本示例的實作方式，暫時不做太多說明，詳細請直接查看原始碼 Dotnet9WPFControls，本文后半截大概提一下，

代碼組織結構如下：

GuideInfo：定義引導資訊類，如標題、內容、下一步按鈕顯示內容，
GuideHintControl：引導提示框控制元件，顯示引導標題、引導內容、下一步按鈕，即 GuideInfo 系結的控制元件，
GuideControl：引導控制元件，用于目標控制元件無法獲取到自己的表單這種（即無法獲取在表單中的位置），比如您開發的程式為第三方程式插件這種，上面的代碼即是使用此引導控制元件實作的效果，
GuideWindow：引導表單，GuideControl 引導控制元件的相互補充，
GuideControlBase：引導控制元件輔助類
BindControlToGuideConverter：引導資訊與引導的目標控制元件系結轉換器
GuideHelper：引導幫助類，系結目標控制元件的引導資訊使用，外加一個顯示引導表單的靜態命令，
Guide.xaml：定義引導遮罩層(GuideControl 和 GuideWindow)、引導提示框(GuideHintControl)樣式的資源檔案，定義外觀請改這個檔案

重點：

a) GuideControlBase

GuideControlBase 是 GuideControl 和 GuideWindow 的輔助類，因為這兩個類實作的功能是類似的，所以封裝大部分功能在 GuideControlBase 中，比如將目標控制元件區域從遮罩層 Clip 出來，并將 GuideHintControl 提示框控制元件添加到遮罩層之上，顯示出新手引導的效果，

b) GuideControl 和 GuideWindow

GuideControl 是用于顯示在包含目標控制元件的容器內使用的，GuideControl放置的容器不一定是目標控制元件的直接容器，可以有嵌套，比如目標控制元件在ListBox子項ListBoxItem內，而引導控制元件GuideControl可以在ListBox的外層容器之上；

GuideWindow 用于貼在目標控制元件所在的表單上，GuideWindow 作為目標控制元件表單的子表單，Show()在目標控制元件表單上，不能使用ShowDialog()的方式（為啥？ShowDialog()會使除引導表單之外的表單處于無效狀態（disable）），

這兩種方式（GuideControl 和 GuideWindow）總體呈現效果是一樣的，目標控制元件所在的表單是自定義表單，Demo能正常顯示下面的效果，普通表單需要對目標控制元件 Clip 的位置和提示框的位置進行偏移處理，修改位置見 GuideControl 和 GuideWindow的方法 ShowGuide(FrameworkElement? targetControl, GuideInfo guide)，

控制元件帶的兩個新手引導Demo如下：

新手引導Demo一

GuideControl方式，站長推薦，即以控制元件的方式顯示新手引導，點擊看代碼：

新手引導Demo二

GuideWindow方式，即以子表單的方式顯示新手引導，點擊看代碼：

詳細開發不展開說了，一切都在代碼中，

4. 總結

前面寫了不少，其實不多，謝謝開源帶來的力量，

參考文章：WPF 簡易新手引導
參考開源專案：AIStudio.Wpf.Controls
本文Demo NewbieGuideDemo：Github、Gitee
Dotnet9Controls 新手引導Demo一原始碼：Github、Gitee
Dotnet9Controls 新手引導Demo二原始碼 GuideWindowView：Github、Gitee
Dotnet9Controls控制元件：Github、Gitee

時間如流水，只能流去不流回，

轉載請註明出處，本文鏈接：https://www.uj5u.com/net/482137.html

標籤：.NET技术

上一篇：C# WPF從后臺代碼生成行列可變的表格

下一篇：C# WPF從后臺代碼生成行列可變的表格