WPF-Control开源项目系列教程

一 吃透WPF控件内核

1. WPF视觉树继承体系全解析
2. Window和ContentControl
3. 用户控件 (UserControl) 和自定义控件 (CustomControl) 的区别
4. WPF之控件模板 (ControlTemplate)
5. WPF之视觉状态 (VisualStateManager)

二 安装使用-WPF-Control-Base

Demo	学习内容	核心代码
Demo1	最基础的使用方式	直接引用控件，了解命名空间
Demo2	基础控件的 ResourceKey	Style="{DynamicResource {x:Static h:ButtonKeys.Accent}}"
Demo3	公用基础 ResourceKey	Background="{DynamicResource {x:Static h:BrushKeys.BackgroundDefault}}"
Demo4	最简单的 MainWindow	继承 ApplicationBase 和 h:MainWindow
Demo5	主题设置 + 配置保存	services.AddTheme()、services.AddXmlSerialize()
Demo6	框架对话框	services.AddMessageDialog()
Demo7	配置页面	services.AddSetting()、services.AddSettingViewPrenter()
Demo8	启动页面	services.AddStart()
Demo9	登录页面	services.AddIdentity()

1. 安装使用-WPF-Control-最基础的使用方式
2. HeBianGu.Demo.Demo2-基础控件的 ResourceKey
3. HeBianGu.Demo.Demo3-公用基础 ResourceKey
4. HeBianGu.Demo.Demo4-最简单的 MainWindow
5. HeBianGu.Demo.Demo5-主题设置 + 配置保存
6. HeBianGu.Demo.Demo6-框架对话框
7. HeBianGu.Demo.Demo7- 配置页面
8. HeBianGu.Demo.Demo8-启动页面
9. HeBianGu.Demo.Demo9-登录页面
10. HeBianGu.Demo.Demo10-登录
11. HeBianGu.Demo.Demo11-新手向导
12. HeBianGu.Demo.Demo30-页面跳转

三 WPF-Control-Base

WPF-ControlBase 不只是控件库，而是一套可以搭建完整 WPF 桌面软件的框架体系。

这个项目本质上是一个大型 WPF 控件与应用框架集合，包含：

• 基础库：MVVM、命令、依赖注入、附加属性、转换器、主题资源。
• 通用控件库：系统控件样式、自定义控件、窗口基类、应用基类。
• 独立控件：图表、消息、属性面板、分页表格、Dock、抽屉、步骤条、大屏、图片播放器等。
• 服务模块：动画、MVC、MVP、验证、标记扩展、命令、配置。
• 系统模块：登录、设置、日志、升级、项目管理、仓储、打印、加密、通知等。
• 数据模块：SQLite、SQL Server、仓储基础设施。
• 示例应用：Main、Manager、Chart、Music、Office、Map、Screen 等。

1 项目整体认识

WPF-ControlBase-master 可以分成三层理解：

层级	作用	对应目录
地基层	MVVM、命令、IOC、资源、主题、附加属性	Source/Base
控件层	通用样式、高级控件、窗口控件	Source/General、Source/Control、Source/Window
应用层	系统能力、数据库、完整应用示例	Source/System、Source/Data、Source/Application

2 目录结构总览

根目录：

WPF-ControlBase-master
├─ Document              # 文档资源和图片
├─ Solution              # Visual Studio 解决方案
├─ Source                # 全部源码
├─ Directory.Build.Props # 全局构建配置
├─ README.md             # 项目介绍
└─ LICENSE

Source 是核心：

Source
├─ Base             # 基础库
├─ Common           # 通用工具
├─ Control          # 独立控件库
├─ Data             # 数据库和仓储
├─ General          # 通用控件库
├─ Service          # 服务能力
├─ System           # 系统业务能力
├─ Window           # 窗口模块
├─ Application      # 完整应用示例
├─ ApplicationNuget # NuGet 应用示例
├─ Demo             # 小 Demo
└─ Template         # 项目模板

记住一句话：

Base 打地基，General 做通用 UI，Control 放高级控件，Service/System/Data 提供能力，Application 负责把它们组装成软件。

---

3.WPF附加属性（AttachedProperty）

---

WPF-Control-Base启动流程

---

MVVM：界面如何绑定数据和命令

---

4.HeBianGu.Base.WpfBase基础库

ServiceRegistry 依赖注入容器

## `ApplicationBase` 应用启动框架

## MVVM 与命令系统

## 主题与资源系统

## 附加属性 `Cattach`

HeBianGu.General.WpfControlLib 通用控件库

11.Control独立控件模块

12.Service 服务模块

13.Window 窗口模块

14.System系统模块

15.Data模块

16.Common模块

17.如何新建自己的应用

18.如何写自己的控件模块

---

四 WPF-Control

本教程面向从 0 学习 WPF-Control-main 的开发者。目标是先建立全局认知，再逐步理解 IOC、MVVM、应用基座、服务、模块、控件、主题、数据库和示例项目。

目录

1. 项目定位与学习路线
2. 根目录与解决方案结构
3. 核心架构思想
4. IOC 容器 H.Iocable
5. MVVM 与基础库
6. 应用启动基座 ApplicationBase
7. Services 服务体系
8. Modules 功能模块体系
9. Controls 控件体系
10. Themes 与 Styles 主题样式
11. Windows 与 Presenters
12. Extensions 扩展库
13. 数据库与仓储
14. Tests 示例项目学习法
15. 从 0 搭建自己的应用
16. 源码阅读方法与常见问题

---

1. 项目定位与学习路线

WPF-Control-main 不只是一个控件库，而是一套 WPF 企业级应用开发框架。它提供：

• 基础能力：MVVM、附加属性、值转换器、MarkupExtension、国际化。
• 应用框架：启动流程、异常处理、登录、启动页、主窗口、任务调度。
• IOC：基于 Microsoft.Extensions.DependencyInjection 的服务注册与获取。
• 控件库：表单、属性网格、图表、流程图、Dock、PDF、二维码、分页、过滤、树表、视频等。
• 主题样式：多套颜色主题、Bootstrap 风格、默认控件样式。
• 功能模块：登录、设置、主题、消息、关于、帮助、身份、项目、许可、升级。
• 服务体系：日志、消息、配置、序列化、项目、身份、撤销重做、邮件、路径。
• 数据库：Sqlite、SqlServer、Repository 仓储展示。

推荐学习顺序：

WPF 基础 -> XAML 样式资源 -> MVVM -> IOC -> ApplicationBase -> Services -> Modules -> Controls -> Themes -> Tests 示例 -> 自定义模块

---

2. 根目录与解决方案结构

根目录重点文件：

路径	作用
README.md	项目介绍、依赖、截图、文档链接。
Directory.Build.Props	全局构建配置，启用 WPF，目标 .NET 8 Windows，统一版本和 NuGet 信息。
Directory.Build.targets	全局 using，减少源码重复引用。
Solution/WPF-Control.sln	Visual Studio 解决方案。
Source	核心源码。
Document	截图、图标、文档资源。
docs	静态文档页面。

Directory.Build.Props 中的关键配置：

• UseWPF=true：所有项目默认启用 WPF。
• TargetFrameworks=net8.0-windows：目标 .NET 8 Windows。
• LangVersion=10.0：使用 C# 10。
• ImplicitUsings=enable：启用隐式 using。
• 统一版本号、作者、包描述和资源打包。

Source 下一级目录：

目录	通俗解释
App	真实应用示例。
ApplicationBases	应用基座组合。
Base	最底层基础库。
Common	公共接口和公共模型。
Components	组件封装。
Controls	控件库主体。
DataBases	数据库适配。
Datas	示例数据。
Extensions	各类扩展能力。
Modules	功能模块。
Presenters	展示器层。
Providers	基础提供者，尤其 IOC。
Services	服务接口与实现。
Styles	控件样式。
Templates	项目模板。
Tests	示例项目，学习入口。
Themes	颜色主题。
Windows	主窗口、对话框、Ribbon、Dock。

---

3. 核心架构思想

这个项目的架构可以用一句话概括：

控件负责显示，服务负责能力，模块负责组合，主题负责外观，ApplicationBase 负责生命周期，IOC 负责连接所有对象。

分层关系：

App / Tests
  -> ApplicationBase
      -> Ioc
      -> Services
      -> Modules
      -> Themes / Styles
      -> Windows / Controls / Presenters

运行流程：

启动 App
  -> 创建 ServiceCollection
  -> ConfigureServices 注册模块和服务
  -> Ioc.Build 构建容器
  -> Configure 应用配置
  -> 加载多语言和主题
  -> 显示启动页
  -> 执行登录
  -> 创建并显示主窗口
  -> 用户操作控件
  -> Command / Presenter / Service 响应

---

4. IOC 容器 H.Iocable

位置：Source/Providers/H.Iocable

核心文件：

文件	作用
Ioc.cs	全局 IOC 容器入口。
IocExtension.cs	允许在 XAML 中通过 MarkupExtension 获取服务。
IocBindable.cs	可绑定的 IOC 对象。
IocThrowIfNone.cs	服务不存在时的异常处理。

Ioc 本质是对 Microsoft.Extensions.DependencyInjection 的封装。

5. MVVM与基础库

位置：Source/Base/H.Mvvm

主要内容：

模块	作用
BindableBase	实现 INotifyPropertyChanged。
Bindable	更完整的可绑定对象基类。
CommandBase	命令基类，实现 ICommand。
RelayCommand	常用命令封装。
RelayCommand<T>	泛型命令封装。

6. 应用启动基座 ApplicationBase

位置：Source/Extensions/H.Extensions.ApplicationBase/ApplicationBase.cs

ApplicationBase 继承 WPF 的 Application，是整个框架的发动机。它负责：

1. 设置应用关闭模式。
2. 注册应用路径服务。
3. 初始化全局异常处理。
4. 创建 ServiceCollection。
5. 调用 ConfigureServices。
6. 构建 IOC 容器。
7. 加载多语言。
8. 启动时调用 Configure。
9. 创建主窗口。
10. 加载主题。
11. 显示启动页。
12. 执行登录。
13. 显示主窗口。
14. 启动定时任务。
15. 退出时记录日志并停止任务。

7. Services 服务体系

位置：Source/Services

服务层负责“能力”，不直接关心 UI 细节。

服务项目	功能
H.Services.AppPath	应用路径，如程序目录、配置目录、数据目录。
H.Services.Common	公共服务接口，如数据库连接、主题加载、启动页、引导等。
H.Services.Identity	用户、角色、权限、登录、注册。
H.Services.Logger	日志服务接口和日志命令。
H.Services.Mail	邮件发送。
H.Services.Message	消息、对话框、通知、Snack。
H.Services.Operation	操作日志。
H.Services.Project	项目文件、新建、打开、保存。
H.Services.Revertible	撤销、重做。
H.Services.Serializable	JSON、XML、克隆、Web 序列化。
H.Services.Setting	设置项、设置页面、配置存取。

典型思路：

• 服务接口放在 Services。
• UI 展示放在 Modules 或 Presenters。
• 应用在 ConfigureServices 中注册具体实现。
• 运行时通过 Ioc.GetService<T>() 获取。

---

8. Modules功能模块体系

位置：Source/Modules

每个模块通常包含：

Extension.cs / Extention.cs   注册入口
Options.cs                    配置选项
Presenter.xaml                UI 展示器
Themes/Generic.xaml           默认样式
Resources.*.resx              多语言资源

9. Controls 控件体系

位置：Source/Controls

控件项目通常包含：

Control.xaml / Control.xaml.cs
Themes/Generic.xaml
Provider / Service / Presenter / Model

10. Themes 与 Styles

主题目录：Source/Themes

项目	说明
H.Theme	主题核心。
H.Themes.Colors.Accent	强调色。
H.Themes.Colors.Blue	蓝色。
H.Themes.Colors.Copper	铜色/复古。
H.Themes.Colors.Gray	灰色。
H.Themes.Colors.Industrial	工业风。
H.Themes.Colors.Mineral	矿物色。
H.Themes.Colors.Platform	Apple、FluentUI、MaterialDesign。
H.Themes.Colors.Purple	紫色。
H.Themes.Colors.Solid	纯色。
H.Themes.Colors.Technology	科技风。
H.Themes.Colors.Web	AntDesignPro、Bootstrap、LayUI、WeUI。

样式目录：Source/Styles

项目	作用
H.Style	默认样式核心。
H.Styles.Bootstrap	Bootstrap 风格样式。

11. Windows 与 Presenters

Source/Windows：

项目	功能
H.Windows.Main	主窗口、窗口命令、窗口设置保存。
H.Windows.Dialog	对话窗口。
H.Windows.Dock	Dock 窗口。
H.Windows.Ribbon	Ribbon 窗口和 Ribbon 样式。

H.Windows.Ribbon 包含 RibbonButton、RibbonTab、RibbonGroup、RibbonGallery、RibbonWindow 等，适合 Office 风格应用。

Source/Presenters：

项目	功能
H.Presenters.Common	通用展示器。
H.Presenters.Repository	仓储数据展示器。
H.Presenters.Design	设计器展示器。

Presenter 可以理解为“业务化控件”：控件偏通用，Presenter 偏业务页面。

12. Extensions 扩展库

位置：Source/Extensions

分类速查：

类型	项目示例
应用/MVVM	H.Extensions.ApplicationBase、H.Extensions.Mvvm、H.Extensions.Command、H.Extensions.Behvaiors
数据/序列化	H.Extensions.DataBase、H.Extensions.DataBase.Repository、H.Extensions.XmlSerialize、H.Extensions.NewtonsoftJson
文件/路径/进程	H.Extensions.AppPath、H.Extensions.OpenFolderDialog、H.Extensions.Zip、H.Extensions.Process
UI/视觉	H.Extensions.Animations、H.Extensions.StoryBoard、H.Extensions.Color、H.Extensions.Geometry、H.Extensions.FontIcon
业务支持	H.Extensions.Excel、H.Extensions.Encryption、H.Extensions.Mail、H.Extensions.Http、H.Extensions.Validation、H.Extensions.Revertible

看扩展库时，优先找 Extension.cs 或 Extention.cs，它通常是使用入口。

13. 数据库与仓储

位置：Source/DataBases

项目	作用
H.DataBases.Share	数据库共享代码。
H.DataBases.Sqlite	Sqlite 支持。
H.DataBases.SqlServer	SQL Server 支持。

Repository 相关：

H.Extensions.DataBase.Repository
H.Presenters.Repository
H.Controls.RepositoryBox
H.Test.RepositoryPresenter

思路：

数据库模型 -> 仓储服务 -> Presenter -> RepositoryBox 页面

适合快速生成 CRUD 管理页面。

14. Tests 示例项目学习

位置：Source/Tests

建议按这个顺序运行：

示例项目	学习内容
H.Test.Controls	基础控件和样式。
H.Test.Mvvm	MVVM。
H.Test.ApplicationBase	应用基座。
H.Test.DefaultApplicationBase	默认应用组合。
H.Test.Message	消息弹窗。
H.Test.Setting	设置模块。
H.Test.Theme	主题切换。
H.Test.Login	登录模块。
H.Test.Form	自动表单。
H.Test.PropertyGrid	属性网格。
H.Test.Chart2D	图表。
H.Test.Diagram	流程图。
H.Test.Dock	Dock。
H.Test.Ribbon	Ribbon。
H.Test.RepositoryPresenter	仓储展示。
H.Test.Sqlite / H.Test.SqlServer	数据库。
H.Test.Project	项目管理。
H.Test.License	许可。
H.Test.Upgrade	升级。

运行建议：

1. 使用 Visual Studio 2022 打开 Solution/WPF-Control.sln。
2. 安装 .NET 8 SDK 和 WPF 桌面开发工作负载。
3. 选择单个 H.Test.* 项目作为启动项。
4. 不建议初学者一开始编译全部项目。
5. 看 Demo 时同步看 App.xaml.cs，重点看注册了哪些服务。

15. 从 0 搭建自己的应用

最小结构：

MyApp
  App.xaml
  App.xaml.cs
  MainWindow.xaml
  MainWindow.xaml.cs