接入与验证

项目与版本

在使用方的 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 的主题文件，它们包含示例工程专用资源。

<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>

在视图根元素声明：

xmlns:hc="https://handyorg.github.io/handycontrol"

例如在已有窗口中：

<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 新成员用于旧包。

4.5 KiB Raw Permalink Blame History