# 接入与验证

## 项目与版本

在使用方的 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)