feat(skills): add HandyControl WPF component skills
Build / build (push) Canceled after 0s

This commit is contained in:
chfei committed 2026-10-27 09:12:40 +08:00
1 parent 72d9b295a0
commit 5d81c475c8
335 files changed
+7359

No files matched your search

+75
View File
@@ -0,0 +1,75 @@
# 接入与验证
## 项目与版本
在使用方的 WPF 项目引用 `HandyControl`。保留项目已有版本;新项目先根据目标框架确认兼容的包版本,不自动升级其他依赖。本仓库 `src/Net_GE45/HandyControl_Net_GE45/HandyControl_Net_GE45.csproj` 的版本字段是源码版本依据,不代表 NuGet 当前最新版本。
SDK 项目必须设置 `UseWPF=true`,现代 .NET 使用 Windows TFM,例如 `net8.0-windows`;不要为接入控件擅自改变已有目标框架。旧 .NET Framework 项目沿用已有项目格式。添加引用可使用 `dotnet add <项目.csproj> package HandyControl --version <已确认版本>`,尖括号为待替换参数。
## 应用资源
将下面的字典合并到现有 `Application.Resources`,保留应用已有资源。先加载皮肤,再加载控件主题。不要引用 HandyControlDemo 的主题文件,它们包含示例工程专用资源。
```xml
<Application.Resources>
<ResourceDictionary>
<ResourceDictionary.MergedDictionaries>
<ResourceDictionary Source="pack://application:,,,/HandyControl;component/Themes/SkinDefault.xaml"/>
<ResourceDictionary Source="pack://application:,,,/HandyControl;component/Themes/Theme.xaml"/>
</ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
</Application.Resources>
```
在视图根元素声明:
```xml
xmlns:hc="https://handyorg.github.io/handycontrol"
```
例如在已有窗口中:
```xml
<StackPanel Margin="24">
<TextBox hc:InfoElement.Placeholder="名称"
Style="{StaticResource TextBoxExtend}"
Text="{Binding Name, UpdateSourceTrigger=PropertyChanged}"/>
<hc:NumericUpDown Margin="0,12,0,0" Minimum="0" Maximum="100"
Increment="1" Value="{Binding Quantity, Mode=TwoWay}"/>
<Button Margin="0,12,0,0" Content="保存" Command="{Binding SaveCommand}"
Style="{StaticResource ButtonPrimary}"/>
</StackPanel>
```
Name、Quantity 和 SaveCommand 由使用方 DataContext 提供,变化通知采用项目已有机制。不要为了示例额外引入 MVVM 框架。
## 类型、绑定与模板
- `Button`、`DataGrid` 等可直接使用原生 WPF 类型配合样式,不要凭名称创造 `hc:Button` 或 `hc:DataGrid`。
- `hc:TextBox`、`hc:ComboBox`、`hc:Window` 等确实存在,但与原生类型功能不同。C# 同名类型用全名或 alias。
- `InfoElement`、`TitleElement`、`BorderElement`、`IconElement` 等是附加属性宿主;是否有效取决于实际模板。查 `Controls/Attach` 和 `Themes/Styles`,不能凭其他厂商 API 猜测属性。
- 事件参数不都使用 WPF 的 `OldValue` / `NewValue`;例如 NumericUpDown.ValueChanged 使用 `FunctionEventArgs<double>.Info`。
- 自定义模板保留源码 `TemplatePart` 声明的 `PART_*`,并确认模板需要的命令绑定和资源。
## 验证与排错
先构建使用方项目,例如 `dotnet build <项目.csproj> -f <目标框架>`。本库多目标项目应显式选定目标框架,不为文档改动无差别构建全部历史框架。
构建通过后,在 Windows 上打开实际窗口,检查资源加载、初始值、绑定更新、空数据、边界和销毁后的事件订阅。编译成功不能证明动态资源与绑定在运行时有效。
| 症状 | 检查位置 |
|---|---|
| 找不到 hc 类型 | 包引用、TFM、XAML 命名空间、AssemblyInfo.XmlnsDefinition、类型是否属于 Avalonia |
| 控件无模板或资源未找到 | App.xaml 的皮肤/主题顺序、重复字典、资源键大小写、Style.TargetType |
| ViewModel 没有更新 | DataContext、绑定错误输出、Mode、UpdateSourceTrigger、属性变化通知 |
| Dialog 不显示 | 活动窗口、AdornerDecorator,或 token 对应的 DialogContainer |
| Growl 不显示/显示错窗口 | 宿主 Panel、GrowlParent/Token、调用范围和 Dispatcher |
## 源码依据
路径均相对于 HandyControl 仓库根目录。在仓库外可以访问对应链接;对已发布版本应切换到匹配 tag 或提交,避免把 master 新成员用于旧包。
- [快速开始](https://github.com/HandyOrg/HandyControl/blob/master/doc/source/handycontrol/quick_start/index.md)
- [WPF 项目](https://github.com/HandyOrg/HandyControl/blob/master/src/Net_GE45/HandyControl_Net_GE45/HandyControl_Net_GE45.csproj)
- [命名空间映射](https://github.com/HandyOrg/HandyControl/blob/master/src/Shared/HandyControl_Shared/Properties/AssemblyInfo.cs)
- [官方 Demo 资源配置](https://github.com/HandyOrg/HandyControl/blob/master/src/Shared/HandyControlDemo_Shared/App.xaml)
+19
View File
@@ -0,0 +1,19 @@
# 原生 WPF 控件样式
这里处理 `System.Windows.Controls` 的原生类型。需要扩展控件功能时才选 `HandyControl.Controls` 下的类型。先按实际 CLR 类型选择样式,不能将一个同名扩展类型的样式套在原生类型上。
```xml
<StackPanel>
<Button Content="保存" Style="{StaticResource ButtonPrimary}"
Command="{Binding SaveCommand}"/>
<TextBox Margin="0,12,0,0" Style="{StaticResource TextBoxExtend}"
hc:InfoElement.Title="用户名" hc:InfoElement.Placeholder="请输入用户名"
Text="{Binding UserName, UpdateSourceTrigger=PropertyChanged}"/>
</StackPanel>
```
片段依赖 App.xaml 的皮肤和主题字典、hc 命名空间,以及使用方 DataContext。原生 PasswordBox 不提供可直接按 TextBox 方式绑定的 Text 属性;需要密码绑定时按实际控件方案实现。
附加属性来自 `Controls/Attach`:检查 InfoElement、TitleElement、BorderElement、IconElement 等的 Get/Set 方法和对应模板的使用位置。设置附加属性不代表任意模板都会展示它。
下面的显式 Style 键从本仓库各原生控件样式源文件生成;不是所有键都适用于控件本身(例如某些键针对子元素),使用前在源文件核对 TargetType。隐式样式和 BasedOn 链不在本清单展开。
+41
View File
@@ -0,0 +1,41 @@
# 皮肤、主题与资源
## 静态字典方案
`SkinDefault.xaml`、`SkinDark.xaml`、`SkinViolet.xaml` 是皮肤字典;`Theme.xaml` 提供控件主题。先合并一个皮肤,再合并主题,应用自己的覆盖资源置于其后。通过 `DynamicResource` 引用需要随皮肤变化的颜色和画刷,例如 `PrimaryBrush`、`RegionBrush`;显式样式键通常用 `StaticResource`。
```xml
<ResourceDictionary.MergedDictionaries>
<ResourceDictionary Source="pack://application:,,,/HandyControl;component/Themes/SkinDark.xaml"/>
<ResourceDictionary Source="pack://application:,,,/HandyControl;component/Themes/Theme.xaml"/>
</ResourceDictionary.MergedDictionaries>
```
这是现有 ResourceDictionary 内的片段,不应额外嵌套 Application.Resources。运行时更换静态皮肤时替换由应用持有的那一个皮肤字典,保留其他字典和顺序,不清空全部 MergedDictionaries。
## Theme 对象方案
当前源码还提供 `HandyControl.Themes.Theme : ResourceDictionary`,其 `Skin` 为 `HandyControl.Data.SkinType`;可以用 Theme 对象管理皮肤。采用此方案时先读取 `Themes/Theme.cs` 的构造和更新逻辑,避免同时再加载一套静态主题字典。
```xml
<ResourceDictionary.MergedDictionaries>
<hc:Theme Skin="Dark"/>
</ResourceDictionary.MergedDictionaries>
```
`hc` 对应 `https://handyorg.github.io/handycontrol`。修改 Theme 实例的 Skin 需要保留对该实例的引用;自动跟随系统、强调色等能力以实际版本的 Theme 源码属性为准。
## 调整外观
先找到控件对应的 `Themes/Styles/<控件>.xaml`,核对 x:Key、TargetType、BasedOn 和 TemplateBinding。能通过公开属性或附加属性完成的改动优先使用这些接口;确需重写模板时保留必需的 PART_* 名称。
本仓库 `Themes/Theme.xaml` 由 `XamlCombine.exe` 和 `Theme_GE45.txt` / `Theme_40.txt` 合并。修改相应样式源文件及必要的清单,再按项目构建流程生成;不要把合并文件当作唯一维护入口。使用方项目通常只需要覆盖自己的资源。
先检查工作区已有修改,尤其颜色和主题文件,避免覆盖用户的定制。验证浅色、深色切换时检查文本对比度、禁用态、弹出层及局部资源覆盖;无法运行 UI 时说明限制。
## 源码依据
- [Theme 实现](https://github.com/HandyOrg/HandyControl/blob/master/src/Shared/HandyControl_Shared/Themes/Theme.cs)
- [皮肤枚举](https://github.com/HandyOrg/HandyControl/blob/master/src/Shared/HandyControl_Shared/Data/Enum/SkinType.cs)
- [样式源目录](https://github.com/HandyOrg/HandyControl/tree/master/src/Shared/HandyControl_Shared/Themes/Styles)
- [主题合并清单](https://github.com/HandyOrg/HandyControl/blob/master/src/Shared/HandyControl_Shared/Themes/Theme_GE45.txt)