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

@@ -0,0 +1,85 @@
# 扩展控件索引
每行对应可单独安装的 Skill。仅有原生样式需求时选择 handycontrol-wpf-native-styles。
| Skill | 控件 | 类型 |
|---|---|---|
| `handycontrol-wpf-animation-path` | [AnimationPath 动画路径](https://handyorg.github.io/handycontrol/extend_controls/animationPath/) | AnimationPath |
| `handycontrol-wpf-badge` | [Badge 标记](https://handyorg.github.io/handycontrol/extend_controls/badge/) | Badge |
| `handycontrol-wpf-blur-window` | [BlurWindow 背景模糊窗口](https://handyorg.github.io/handycontrol/extend_controls/blurWindow/) | BlurWindow |
| `handycontrol-wpf-button-group` | [ButtonGroup 按钮组](https://handyorg.github.io/handycontrol/extend_controls/buttonGroup/) | ButtonGroup |
| `handycontrol-wpf-calendar-with-clock` | [CalendarWithClock 带有时钟的日历](https://handyorg.github.io/handycontrol/extend_controls/calendarWithClock/) | CalendarWithClock |
| `handycontrol-wpf-card` | [Card 卡片](https://handyorg.github.io/handycontrol/extend_controls/card/) | Card |
| `handycontrol-wpf-carousel` | [Carousel 轮播](https://handyorg.github.io/handycontrol/extend_controls/carousel/) | Carousel |
| `handycontrol-wpf-chat-bubble` | [ChatBubble 对话气泡](https://handyorg.github.io/handycontrol/extend_controls/chatBubble/) | ChatBubble |
| `handycontrol-wpf-check-combo-box` | [CheckComboBox 复选组合框](https://handyorg.github.io/handycontrol/extend_controls/checkComboBox/) | CheckComboBox |
| `handycontrol-wpf-circle-panel` | [CirclePanel 圆形布局](https://handyorg.github.io/handycontrol/extend_controls/circlePanel/) | CirclePanel |
| `handycontrol-wpf-circle-progress-bar` | [CircleProgressBar 圆形进度条](https://handyorg.github.io/handycontrol/extend_controls/circleProgressBar/) | CircleProgressBar |
| `handycontrol-wpf-clock` | [Clock 时钟](https://handyorg.github.io/handycontrol/extend_controls/clock/) | Clock |
| `handycontrol-wpf-color-picker` | [ColorPicker 颜色拾取器](https://handyorg.github.io/handycontrol/extend_controls/colorPicker/) | ColorPicker |
| `handycontrol-wpf-combo-box` | [ComboBox 组合框](https://handyorg.github.io/handycontrol/extend_controls/comboBox/) | ComboBox |
| `handycontrol-wpf-compare-slider` | [CompareSlider 对比滑块](https://handyorg.github.io/handycontrol/extend_controls/compareSlider/) | CompareSlider |
| `handycontrol-wpf-context-menu-button` | [ContextMenuButton 上下文菜单按钮](https://handyorg.github.io/handycontrol/extend_controls/contextMenuButton/) | ContextMenuButton |
| `handycontrol-wpf-cover-flow` | [CoverFlow 封面流](https://handyorg.github.io/handycontrol/extend_controls/coverFlow/) | CoverFlow |
| `handycontrol-wpf-cover-view` | [CoverView 封面视图](https://handyorg.github.io/handycontrol/extend_controls/coverView/) | CoverView |
| `handycontrol-wpf-dashed-border` | [DashedBorder 虚线边框](https://handyorg.github.io/handycontrol/extend_controls/dashedBorder/) | DashedBorder |
| `handycontrol-wpf-date-picker` | [DatePicker 日期选择器](https://handyorg.github.io/handycontrol/extend_controls/datePicker/) | DatePicker |
| `handycontrol-wpf-date-time-picker` | [DateTimePicker 日期时间选择器](https://handyorg.github.io/handycontrol/extend_controls/dateTimePicker/) | DateTimePicker |
| `handycontrol-wpf-dialog` | [Dialog 对话框](https://handyorg.github.io/handycontrol/extend_controls/dialog/) | Dialog |
| `handycontrol-wpf-divider` | [Divider 分割线](https://handyorg.github.io/handycontrol/extend_controls/divider/) | Divider |
| `handycontrol-wpf-drawer` | [Drawer 抽屉](https://handyorg.github.io/handycontrol/extend_controls/drawer/) | Drawer |
| `handycontrol-wpf-flip-clock` | [FlipClock 翻页时钟](https://handyorg.github.io/handycontrol/extend_controls/flipClock/) | FlipClock |
| `handycontrol-wpf-floating-block` | [FloatingBlock 漂浮块](https://handyorg.github.io/handycontrol/extend_controls/floatingBlock/) | FloatingBlock |
| `handycontrol-wpf-gif-image` | [GifImage Gif图片](https://handyorg.github.io/handycontrol/extend_controls/gifImage/) | GifImage |
| `handycontrol-wpf-glow-window` | [GlowWindow 辉光窗口](https://handyorg.github.io/handycontrol/extend_controls/glowWindow/) | GlowWindow |
| `handycontrol-wpf-goto-top` | [GotoTop 回到顶部](https://handyorg.github.io/handycontrol/extend_controls/gotoTop/) | GotoTop |
| `handycontrol-wpf-gravatar` | [Gravatar 头像](https://handyorg.github.io/handycontrol/extend_controls/gravatar/) | Gravatar |
| `handycontrol-wpf-grid` | [Grid 栅格](https://handyorg.github.io/handycontrol/extend_controls/grid/) | Row, Col |
| `handycontrol-wpf-growl` | [Growl 信息通知](https://handyorg.github.io/handycontrol/extend_controls/growl/) | Growl |
| `handycontrol-wpf-honeycomb-panel` | [HoneycombPanel 蜂窝布局](https://handyorg.github.io/handycontrol/extend_controls/honeycombPanel/) | HoneycombPanel |
| `handycontrol-wpf-image-block` | [ImageBlock 图片块](https://handyorg.github.io/handycontrol/extend_controls/imageBlock/) | ImageBlock |
| `handycontrol-wpf-image-browser` | [ImageBrowser 图片浏览器](https://handyorg.github.io/handycontrol/extend_controls/imageBrowser/) | ImageBrowser |
| `handycontrol-wpf-image-selector` | [ImageSelector 图片选择器](https://handyorg.github.io/handycontrol/extend_controls/imageSelector/) | ImageSelector |
| `handycontrol-wpf-image-viewer` | [ImageViewer 图片视图](https://handyorg.github.io/handycontrol/extend_controls/imageViewer/) | ImageViewer |
| `handycontrol-wpf-loading` | [Loading 加载条](https://handyorg.github.io/handycontrol/extend_controls/loading/) | LoadingBase, LoadingLine, LoadingCircle |
| `handycontrol-wpf-magnifier` | [Magnifier 放大镜](https://handyorg.github.io/handycontrol/extend_controls/magnifier/) | Magnifier |
| `handycontrol-wpf-message-box` | [MessageBox 消息对话框](https://handyorg.github.io/handycontrol/extend_controls/messageBox/) | MessageBox |
| `handycontrol-wpf-notification` | [Notification 桌面通知](https://handyorg.github.io/handycontrol/extend_controls/notification/) | Notification |
| `handycontrol-wpf-notify-icon` | [NotifyIcon 托盘图标](https://handyorg.github.io/handycontrol/extend_controls/notifyIcon/) | NotifyIcon |
| `handycontrol-wpf-numeric-up-down` | [NumericUpDown 数值选择控件](https://handyorg.github.io/handycontrol/extend_controls/numericUpDown/) | NumericUpDown |
| `handycontrol-wpf-outline-text` | [OutlineText 轮廓文本](https://handyorg.github.io/handycontrol/extend_controls/outlineText/) | OutlineText |
| `handycontrol-wpf-pagination` | [Pagination 页码条](https://handyorg.github.io/handycontrol/extend_controls/pagination/) | Pagination |
| `handycontrol-wpf-password-box` | [PasswordBox 密码框](https://handyorg.github.io/handycontrol/extend_controls/passwordBox/) | PasswordBox |
| `handycontrol-wpf-pin-box` | [PinBox PIN码框](https://handyorg.github.io/handycontrol/extend_controls/pinBox/) | PinBox |
| `handycontrol-wpf-pop-tip` | [PopTip 气泡提示](https://handyorg.github.io/handycontrol/extend_controls/popTip/) | Poptip |
| `handycontrol-wpf-popup-window` | [PopupWindow 弹出窗口](https://handyorg.github.io/handycontrol/extend_controls/popupWindow/) | PopupWindow |
| `handycontrol-wpf-preview-slider` | [PreviewSlider 预览滑块](https://handyorg.github.io/handycontrol/extend_controls/previewSlider/) | PreviewSlider |
| `handycontrol-wpf-progress-button` | [ProgressButton 进度按钮](https://handyorg.github.io/handycontrol/extend_controls/progressButton/) | ProgressButton |
| `handycontrol-wpf-property-grid` | [PropertyGrid 属性编辑器](https://handyorg.github.io/handycontrol/extend_controls/propertyGrid/) | PropertyGrid, PlainTextPropertyEditor |
| `handycontrol-wpf-range-slider` | [RangeSlider 范围滑块](https://handyorg.github.io/handycontrol/extend_controls/rangeSlider/) | TwoWayRangeBase, RangeSlider |
| `handycontrol-wpf-rate` | [Rate 评分](https://handyorg.github.io/handycontrol/extend_controls/rate/) | SimpleItemsControl, RegularItemsControl, Rate |
| `handycontrol-wpf-relative-panel` | [RelativePanel 相对布局](https://handyorg.github.io/handycontrol/extend_controls/relativePanel/) | RelativePanel |
| `handycontrol-wpf-running-block` | [RunningBlock 滚动块](https://handyorg.github.io/handycontrol/extend_controls/runningBlock/) | RunningBlock |
| `handycontrol-wpf-screenshot` | [Screenshot 截图](https://handyorg.github.io/handycontrol/extend_controls/screenshot/) | Screenshot |
| `handycontrol-wpf-scroll-viewer` | [ScrollViewer 滚动视图](https://handyorg.github.io/handycontrol/extend_controls/scrollViewer/) | ScrollViewer |
| `handycontrol-wpf-search-bar` | [SearchBar 搜索栏](https://handyorg.github.io/handycontrol/extend_controls/searchBar/) | SearchBar |
| `handycontrol-wpf-shield` | [Shield 徽章](https://handyorg.github.io/handycontrol/extend_controls/shield/) | Shield |
| `handycontrol-wpf-side-menu` | [SideMenu 侧边菜单](https://handyorg.github.io/handycontrol/extend_controls/sideMenu/) | SimpleItemsControl, HeaderedSimpleItemsControl, SideMenu |
| `handycontrol-wpf-simple-items-control` | [SimpleItemsControl 简单项目控件](https://handyorg.github.io/handycontrol/extend_controls/simpleItemsControl/) | SimpleItemsControl |
| `handycontrol-wpf-simple-panel` | [SimplePanel 简单面板](https://handyorg.github.io/handycontrol/extend_controls/simplePanel/) | SimplePanel |
| `handycontrol-wpf-simple-text` | [SimpleText 简单文本](https://handyorg.github.io/handycontrol/extend_controls/simpleText/) | SimpleText |
| `handycontrol-wpf-split-button` | [SplitButton 分割按钮](https://handyorg.github.io/handycontrol/extend_controls/splitButton/) | SplitButton |
| `handycontrol-wpf-sprite` | [Sprite 精灵](https://handyorg.github.io/handycontrol/extend_controls/sprite/) | Sprite |
| `handycontrol-wpf-step-bar` | [StepBar 步骤条](https://handyorg.github.io/handycontrol/extend_controls/stepBar/) | StepBar |
| `handycontrol-wpf-tab-control` | [TabControl 选项卡控件](https://handyorg.github.io/handycontrol/extend_controls/tabControl/) | TabControl |
| `handycontrol-wpf-tag` | [Tag 标签](https://handyorg.github.io/handycontrol/extend_controls/tag/) | Tag |
| `handycontrol-wpf-text-box` | [TextBox 文本框](https://handyorg.github.io/handycontrol/extend_controls/textBox/) | TextBox |
| `handycontrol-wpf-time-bar` | [TimeBar 时间条](https://handyorg.github.io/handycontrol/extend_controls/timeBar/) | TimeBar |
| `handycontrol-wpf-time-picker` | [TimePicker 时间选择器](https://handyorg.github.io/handycontrol/extend_controls/timePicker/) | TimePicker |
| `handycontrol-wpf-toggle-block` | [ToggleBlock 切换块](https://handyorg.github.io/handycontrol/extend_controls/toggleBlock/) | ToggleBlock |
| `handycontrol-wpf-transfer` | [Transfer 穿梭框](https://handyorg.github.io/handycontrol/extend_controls/transfer/) | SimpleItemsControl, Transfer |
| `handycontrol-wpf-transitioning-content-control` | [TransitioningContentControl 内容过渡控件](https://handyorg.github.io/handycontrol/extend_controls/transitioningContentControl/) | TransitioningContentControl |
| `handycontrol-wpf-waterfall-panel` | [WaterfallPanel 瀑布流](https://handyorg.github.io/handycontrol/extend_controls/waterfallPanel/) | WaterfallPanel |
| `handycontrol-wpf-watermark` | [Watermark 水印](https://handyorg.github.io/handycontrol/extend_controls/watermark/) | Watermark |
| `handycontrol-wpf-wave-progress-bar` | [WaveProgressBar 波形进度条](https://handyorg.github.io/handycontrol/extend_controls/waveProgressBar/) | WaveProgressBar |
| `handycontrol-wpf-window` | [Window 窗口](https://handyorg.github.io/handycontrol/extend_controls/window/) | Window |
@@ -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)
@@ -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)