76 lines
4.5 KiB
Markdown
76 lines
4.5 KiB
Markdown
# 接入与验证
|
|
|
|
## 项目与版本
|
|
|
|
在使用方的 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)
|