暂时更改一部分Skill

This commit is contained in:
chfei committed 2026-10-27 19:01:56 +08:00
1 parent 84b28f9672
commit 6d4629e4ac
53 files changed
+5293 -10

No files matched your search

+73
View File
@@ -0,0 +1,73 @@
---
name: max-common-wpf
description: 在 Windows WPF 项目中接入和使用 MAX.Common.WPF 的控件、转换器、附加行为、枚举绑定、视图生命周期、防抖和虚拟化功能。适用于明确使用 MAX.Common.WPF 或已引用该库的界面开发;不适用于 WinUI、Avalonia 或 MAUI。
---
# MAX.Common.WPF 功能使用
根据消费项目需求使用现有 WPF 能力。此 Skill 可独立复制使用,不要求安装其他 Skill,也不包含 NuGet 包或原始库源码。
## 接入与参考版本
- 先检查 `.csproj`、集中版本配置、App.xaml 资源字典和既有样式,不改变项目的应用框架或依赖管理方式。
- 基于 2026-10-27 源码快照:`MAX.Common.WPF` 1.4.23,依赖 `MAX.Common` 1.4.17;目标为 `net472;net48;net481;net6.0-windows;net7.0-windows;net8.0-windows;net9.0-windows;net10.0-windows`。这些是参考版本,不代表最新发布版本。
- 优先使用项目现有兼容版本。新接入时选与项目 TFM 匹配的包资产,现代 .NET 项目设置 `<UseWPF>true</UseWPF>` 并使用 Windows TFM;不要将普通 netstandard 类库改成 WPF。
- 普通项目通过 `PackageReference Include="MAX.Common.WPF" Version="1.4.23"` 接入,集中包管理按现有模式拆分版本。MAX.Common 由包依赖传入,通常无需重复添加;MAX.Core、通知系统与 IoC 不属于本 Skill 必需依赖。
## 功能定位
按任务读取 [功能索引](references/features.md)。具体命名空间、属性和方法在 [常用 API 声明](references/api.md) 中按类型搜索。声明摘录没有完整方法体;行为不明确时查看当前安装包 XML 文档、反射或可用源码,再以编译和运行验证。消费项目没有原仓库也应能使用本指南。
## XAML 资源入口
程序集声明了 `xmlns:wpf="MAX.WPF"`。控件样式和共享转换器位于 `Resources/Generic.xaml`,不要猜成 `Themes/Generic.xaml`。需要这些资源时,在现有 Application.Resources 的 MergedDictionaries 中合并一次:
```xml
<ResourceDictionary Source="/MAX.Common.WPF;component/Resources/Generic.xaml"/>
```
页面最小示例(绑定属性由页面的 DataContext 提供):
```xml
<StackPanel xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:wpf="MAX.WPF">
<StackPanel.Resources>
<wpf:Boolean2VisibilityConverter x:Key="ShowWhenTrue"/>
</StackPanel.Resources>
<wpf:NumberBox Minimum="0" Maximum="100" Increment="1"
Value="{Binding Amount, Mode=TwoWay}"/>
<TextBlock Text="处理中"
Visibility="{Binding IsBusy, Converter={StaticResource ShowWhenTrue}}"/>
</StackPanel>
```
不要假设所有转换器都已登记为全局资源;可以显式实例化所需转换器。`Boolean2VisibilityConverter` 的 false 和非 bool 输入返回 Collapsed。
## 常见集成约束
- 枚举选择优先使用 `EnumBindingMarkupExtension` 配合 `EnumBindingExtension.SelectedEnum`;`EnumBindingComboBox` 已标记 Obsolete。标记扩展返回 `EnumBindingItem`(Display、Value),不是裸枚举列表;显示与选择路径需要对应包装对象。
- `ViewModelBase` 继承 `MAX.Common.Models.BindModelBase`。只有需要视图事件与 Loaded / LoadedOnce / Unloaded 钩子时才采用;不要替换现有框架的基类。通过 `AssignView(view)` 关联一次稳定视图后才能使用其 Dispatcher。
- `ViewModelExtension.AutoAssignViewModel` 仅监听启用后的 DataContextChanged,不会立即处理已经设置的 DataContext;需要先启用再设置 DataContext,或显式 AssignView。基类没有提供完整的换视图解绑流程,不要把同一实例反复关联不同视图。
- `DebounceDispatcher.Debounce(TimeSpan, Action)` 基于 DispatcherTimer,应从 UI 线程调用并复用实例;不能每次输入都创建新实例。
- `AsyncDebouncer.Invoke(Func<Task>)` 通过 Task.Run 执行回调,UI 更新要回到 Dispatcher。新调用取消等待,不会取消已经开始的业务任务;回调内处理业务异常,搜索结果另行防止旧请求覆盖新请求。它没有可 await 的 InvokeAsync 或公开 Cancel/Dispose API。
- `DispatcherHelper.RunInDispatcher` 在非目标线程同步 Invoke;省略 Dispatcher 的重载依赖 `Application.Current`。不要在 UI 线程同步等待同时需要 Dispatcher 的后台任务。
- 虚拟化依赖有限可视区域、滚动宿主和 ItemsPanel 配置。`VirtualizingItemsControl` 默认使用 VirtualizingStackPanel,需要换行时显式设置 VirtualizingWrapPanel。不能仅添加面板便承诺大数据性能。
- 通用命令在 `MAX.Common.Commands`,不是 WPF.Commands。MethodCommand<T> / AsyncMethodCommand<T> 的 T 需引用类型或可空值类型,状态变化手动 RaiseCanExecuteChanged;异步命令委托需自行处理业务异常。
## 枚举绑定示例
已有 `xmlns:local` 指向业务枚举命名空间、`SelectedStatus` 是 `Status` 属性时:
```xml
<ComboBox ItemsSource="{wpf:EnumBindingMarkup EnumType={x:Type local:Status}}"
DisplayMemberPath="Display"
SelectedValuePath="Value"
wpf:EnumBindingExtension.SelectedEnum="{Binding SelectedStatus, Mode=TwoWay}"/>
```
允许空选项时使用 AllowNull 并让业务属性可空;自定义显示通过扩展的 Converter 提供,勿假设自动读取所有枚举描述标记。
## 验证与交付
构建实际消费项目的目标框架。运行窗口检查资源解析、DataContext、双向绑定、命令、UI 线程和卸载后的行为。触及虚拟化时用实际数据与滚动验证;触及防抖时检查连续输入和结果乱序。仅编译不能证明 XAML 资源与运行时绑定正确。交付时列出改动文件、包版本和实际验证情况,可按需继续代码审查。
@@ -0,0 +1,3 @@
interface:
display_name: "MAX.Common.WPF"
short_description: "复用 MAX.Common.WPF 的控件、绑定、行为、防抖与虚拟化能力"
@@ -0,0 +1,345 @@
# 常用 API 声明参考
来源:MAX.Common.WPF,2026-10-27 工作区源码快照。
按下方主题或文件名搜索。仅摘录选定文件的 public / protected 声明;省略方法体、初始化表达式与 XML 注释。这是定位参考,不是可直接编译的 C#,不保证包含嵌套类型的完整可见性上下文。行为说明见 SKILL.md;目标包版本不同时以实际包为准。
目录:控件与布局、枚举、视图与绑定、线程与防抖、虚拟化与转换器
## 控件与布局
### Controls/NumberBox.cs
命名空间:`MAX.Common.WPF.Controls`
```csharp
public class NumberBox : TextBox
public NumberBox()
protected Button UpButton
protected Button DownButton
public override void OnApplyTemplate()
protected virtual void DataObjectPasting(object sender, DataObjectPastingEventArgs e)
protected virtual void OnValueChanged(PayloadRoutedEventArgs<double> e)
public event EventHandler<PayloadRoutedEventArgs<double>> ValueChanged
public double Value
public double Maximum
public double Minimum
public double Increment
public int? DecimalPlaces
public string ValueFormat
public bool ShowUpDownButton
```
### Controls/TitleContent.cs
命名空间:`MAX.Common.WPF.Controls`
```csharp
public class TitleContent : ContentControl
public object Title
public double TitleWidth
public HorizontalAlignment TitleHorizontalAlignment
public VerticalAlignment TitleVerticalAlignment
public TitlePlacementType Placement
public Thickness TopTitlePadding
public Thickness LeftTitlePadding
public TitleContent()
```
### Controls/BoolContent.cs
命名空间:`MAX.Common.WPF.Controls`
```csharp
public class BoolContent : Control
public object TrueContent
public object FalseContent
public bool Bool
public CornerRadius CornerRadius
```
### Controls/SpacingStackPanel.cs
命名空间:`MAX.Common.WPF.Controls`
```csharp
public class SpacingStackPanel : Panel
public Orientation Orientation
public bool ChildWrapping
public double HorizontalSpacing
public double VerticalSpacing
public double ItemWidth
public double ItemHeight
public HorizontalAlignment? ItemHorizontalAlignment
public VerticalAlignment? ItemVerticalAlignment
```
### Controls/SpacingUniformGrid.cs
命名空间:`MAX.Common.WPF.Controls`
```csharp
public class SpacingUniformGrid : Panel
public int Rows
public int Columns
public double RowSpacing
public double ColumnSpacing
```
### Controls/AutoColumnsUniformGrid.cs
命名空间:`MAX.Common.WPF.Controls`
```csharp
public class AutoColumnsUniformGrid : UniformGrid
public double CellMinWidth
public int MinColumns
public int MaxColumns
```
### Controls/ButtonPopup.cs
命名空间:`MAX.Common.WPF.Controls`
```csharp
public class ButtonPopup : CustomPopup
public ButtonBase SourceButton
public ICommand OnClickOpenCommand
public ButtonPopup() : base()
```
### Controls/NotifyIcon.cs
命名空间:`MAX.Common.WPF.Controls`
```csharp
public class NotifyIcon : FrameworkElement, IDisposable
public static string WindowClassNamePrefix
public NotifyIcon()
public void Initialize()
public static void ShowBalloonTip(string title, string content, NotifyIconInfoType infoType, string token)
public void ShowBalloonTip(string title, string content, NotifyIconInfoType infoType)
public void Dispose()
public void CloseContextControl()
public string Token
public string Text
public ImageSource Icon
public object ContextContent
public TimeSpan BlinkInterval
public bool IsBlink
public event RoutedEventHandler Click
public event RoutedEventHandler MouseDoubleClick
```
## 枚举、视图与绑定
### MarkupExtensions/EnumBindingMarkupExtension.cs
命名空间:`MAX.Common.WPF.MarkupExtensions`
```csharp
public class EnumBindingMarkupExtension : MarkupExtension
public IValueConverter Converter
public object ConverterParameter
public Type EnumType
public bool AllowNull
public object NullDisplay
public bool DisplayNullLast
public EnumBindingMarkupExtension()
public EnumBindingMarkupExtension(Type enumType)
public override object ProvideValue(IServiceProvider serviceProvider)
public class EnumBindingItem
public object Display
public object Value
public override string ToString()
public override bool Equals(object obj)
public override int GetHashCode()
```
### Extensions/EnumBindingExtension.cs
命名空间:`MAX.Common.WPF.Extensions`
```csharp
public static class EnumBindingExtension
public static void SetSelectedEnum(DependencyObject element, object value)
public static object GetSelectedEnum(DependencyObject element)
```
### Extensions/ViewModelExtension.cs
命名空间:`MAX.Common.WPF.Extensions`
```csharp
public class ViewModelExtension
public static bool GetAutoAssignViewModel(DependencyObject obj)
public static void SetAutoAssignViewModel(DependencyObject obj, bool value)
```
### Extensions/BindingProxies.cs
命名空间:`MAX.Common.WPF.Extensions`
```csharp
public abstract class BindingProxyBase<T> : Freezable
public T Data
public class BindingProxy : BindingProxyBase<object>
public class BooleanProxy : BindingProxyBase<bool>
```
### Extensions/TextBoxExtension.cs
命名空间:`MAX.Common.WPF.Extensions`
```csharp
public static class TextBoxExtension
public static bool GetHandleEnterToNextFocus(DependencyObject obj)
public static void SetHandleEnterToNextFocus(DependencyObject obj, bool value)
public static bool GetHandleEscapeToUndoText(DependencyObject obj)
public static void SetHandleEscapeToUndoText(DependencyObject obj, bool value)
```
### Extensions/ButtonExtension.cs
命名空间:`MAX.Common.WPF.Extensions`
```csharp
public static class ButtonExtension
public static bool GetIsChecked(DependencyObject obj)
public static void SetIsChecked(DependencyObject obj, bool value)
public static bool GetSetPreviewClick(DependencyObject obj)
public static void SetSetPreviewClick(DependencyObject obj, bool value)
```
## 线程与防抖
### Helpers/DispatcherHelper.cs
命名空间:`MAX.Common.WPF.Helpers`
```csharp
public static class DispatcherHelper
public static void RunInDispatcher(Dispatcher dispatcher, Action action)
public static Dispatcher AppDispatcher
public static void RunInDispatcher(Action action)
```
### Utilities/DebounceDispatcher.cs
命名空间:`MAX.Common.WPF.Utilities`
```csharp
public class DebounceDispatcher
public void Debounce(TimeSpan delay, Action action)
```
### Utilities/AsyncDebouncer.cs
命名空间:`MAX.Common.WPF.Utilities`
```csharp
public class AsyncDebouncer(int delayMilliseconds = 300)
public void Invoke(Func<Task> action)
```
### Utilities/Timers/TimerControllerBase.cs
命名空间:`MAX.Common.WPF.Utilities.Timers`
```csharp
public abstract class TimerControllerBase : IDisposable
public abstract void Dispose()
```
### Utilities/Timers/DispatcherTimerController.cs
命名空间:`MAX.Common.WPF.Utilities.Timers`
```csharp
public class DispatcherTimerController : TimerControllerBase
public event TypedEventHandler<DispatcherTimerController, Exception> ExceptionOccurred
public DispatcherTimerController(DispatcherPriority dispatcherPriority, TimeSpan interval, Func<Task> actionAsync, Dispatcher dispatcher = null) : this(dispatcherPriority, interval, dispatcher)
public DispatcherTimerController(DispatcherPriority dispatcherPriority, TimeSpan interval, Action action, Dispatcher dispatcher = null) : this(dispatcherPriority, interval, dispatcher)
public virtual void OnException(Exception exception)
public virtual void Start()
public virtual void Stop()
public override void Dispose()
```
## 虚拟化与转换器
### Virtualization/VirtualizingItemsControl.cs
命名空间:`MAX.Common.WPF.Virtualization`
```csharp
public class VirtualizingItemsControl : ItemsControl
public VirtualizingItemsControl()
```
### Virtualization/VirtualizingWrapPanel.cs
命名空间:`MAX.Common.WPF.Virtualization`
```csharp
public class VirtualizingWrapPanel : VirtualizingPanelBase
public Orientation Orientation
public Size ItemSize
public bool AllowDifferentSizedItems
public IItemSizeProvider? ItemSizeProvider
public ItemAlignment ItemAlignment
public SpacingMode SpacingMode
public bool StretchItems
public bool IsGridLayoutEnabled
public void ClearItemSizeCache()
```
### Virtualization/IItemSizeProvider.cs
命名空间:`MAX.Common.WPF.Virtualization`
```csharp
public interface IItemSizeProvider
```
### Converters/Boolean2VisibilityConverter.cs
命名空间:`MAX.Common.WPF.Converters`
```csharp
public class Boolean2VisibilityConverter : IValueConverter
public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
```
### Converters/EnumDisplayConverter.cs
命名空间:`MAX.Common.WPF.Converters`
```csharp
public class EnumDisplayConverter : IValueConverter
public static EnumDisplayManagerBase EnumDisplayManager
public EnumDisplayManagerBase SelfEnumDisplayManager
public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
```
### Converters/FormatConverter.cs
命名空间:`MAX.Common.WPF.Converters`
```csharp
public class FormatConverter : IMultiValueConverter
public object Convert(object[] values, Type targetType, object parameter, CultureInfo culture)
public object[] ConvertBack(object value, Type[] targetTypes, object parameter, CultureInfo culture)
```
### Converters/StringJoinConverter.cs
命名空间:`MAX.Common.WPF.Converters`
```csharp
public class StringJoinConverter : IValueConverter
public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
```
@@ -0,0 +1,32 @@
# WPF 功能索引
参考版本:MAX.Common.WPF 1.4.23。以下均以 `MAX.Common.WPF` 为根命名空间。只选任务需要的能力,常用成员见同目录 api.md。
| 需求 | 类型 / 命名空间 | 使用要点 |
| --- | --- | --- |
| 数值输入 | Controls.NumberBox | Value 为 double;Minimum、Maximum、Increment、DecimalPlaces、ValueFormat、ShowUpDownButton;模板资源在 Resources/Generic.xaml |
| 标题与条件内容 | Controls.TitleContent、BoolContent | TitleContent 有 Placement 等布局属性;BoolContent 用 Bool、TrueContent、FalseContent |
| 间距布局 | Controls.SpacingStackPanel、SpacingUniformGrid、AutoColumnsUniformGrid | 区分面板间距与子元素 Margin,按声明配置 |
| 图标与链接 | Controls.FontIcon、HyperlinkEx | FontIcon 继承 TextBlock,具体字体和字形必须与项目资源一致 |
| 按钮与弹出层 | Controls.MenuButton、ButtonPopup、CustomPopup、ClippingBorder | 按实际属性处理关闭、焦点和裁切,不猜测通用 Popup 行为 |
| 托盘图标 | Controls.NotifyIcon;Enums.NotifyIconInfoType | 涉及 Win32 资源与应用生命周期,检查实际清理 API |
| DataGrid | Controls.DataGridExtended;Extensions.DataGridExtension;Helpers.DataGridHelper | 先区分扩展控件、附加属性和普通 helper |
| 标准控件附加行为 | Extensions.TextBoxExtension、ButtonExtension、ListBoxExtension、TreeViewExtension、SelectorExtension、ScrollViewerExtension、ProgressBarExtension、ToolTipExtension | 搜索对应 Get/Set 方法确认附加属性名称、默认值与事件机制 |
| 通用控件行为 | Extensions.ControlExtension(Context / DragDrop / Focus / Keyboard / Layout / Loaded / Mouse 分文件)、WindowExtension、GridLayoutHelper | 使用实际 API 名称,不把文件名当作附加属性名 |
| 上下文菜单和绑定代理 | Extensions.ContextMenuExtension、ContextMenuListener、BindingProxy / BooleanProxy、CommandProxy;Models.ContextMenuModel;ViewModels.ContextMenuViewModel | Popup/ContextMenu 不在普通可视树,核对 DataContext 来源 |
| 枚举选择与显示 | MarkupExtensions.EnumBindingMarkupExtension;Extensions.EnumBindingExtension;Converters.EnumDisplayConverter;Utilities.EnumDisplayManagerWPF | ItemsSource 返回包装对象;旧 EnumBindingComboBox 已弃用 |
| 布尔、空值与可见性 | Converters.Boolean2VisibilityConverter、Boolean2VisibilityReConverter、Object2VisibilityConverter、String2VisibilityConverter、IListToVisibilityConverter、BooleanArr2VisibilityConverter 等 | 各 Converter 对 null、空串、集合的定义不同,核对实现;多值转换器需 MultiBinding |
| 格式、颜色、尺寸转换 | Converters.FileSizeDisplayConverter、DateTimeFormatConverter、FormatConverter、StringJoinConverter、ColorToBrushConverter、ContrastBrushConverter、ThicknessSplitConverter、CornerRadiusSplitConverter 等 | 按 IValueConverter / IMultiValueConverter 及 ConvertBack 支持情况选择绑定模式 |
| 视图生命周期 | ViewModels.ViewModelBase;Extensions.ViewModelExtension | LoadedOnce / Loaded / Unloaded;关联视图并非 IoC 自动创建 ViewModel |
| UI 调度与防抖 | Helpers.DispatcherHelper;Utilities.DebounceDispatcher、AsyncDebouncer | UI Dispatcher 与后台 Task.Run 的回调线程不同 |
| 定时控制 | Utilities.Timers.DispatcherTimerController、SystemTimerController、ThreadingTimerController | 依据 UI 访问要求选类型,并核对停止与释放方法 |
| 虚拟化列表和换行 | Virtualization.VirtualizingItemsControl、VirtualizingWrapPanel、VirtualizingWrapPanelWithItemExpansion、IItemSizeProvider | 保持有限视口与滚动配置;不同尺寸和展开项需单独验证 |
| 窗口、快捷键与系统 | Helpers.WindowHelper、WindowHotKeyActionsHelper、KeyboardHelper、SystemHelper、SecurityHelper、FileActionHelper;Utilities.WindowActivator、JobObject | Windows 特定能力,按 HWND/资源生命周期使用 |
| 视觉树、颜色、图标 | Helpers.ViewHelper、ViewDebugHelper、ColorHelper、IconHelper、Vector2Helper | 与普通 MAX.Common 数据类型和工具区分 |
| 属性监听与筛选 | Utilities.PropertyChangeNotifier、AttachedCommandRegister;Models.CollectionSearchFilter、ControlTokenManager、AppDiagnosticsModel | 阅读订阅、解除和集合更新约定 |
## 资源和版本核对
同一 `MAX.WPF` XML 命名空间映射了 Controls、Converters、Extensions、MarkupExtensions、Virtualization 等 CLR 命名空间;C# using 仍需写真实 CLR 命名空间。资源字典中显式定义了 NumberBox、TitleContent、BoolContent 样式以及多个转换器,不能推断其他控件具有同样的默认样式加载机制。
需要索引未列的成员时,搜索已安装包 XML 文档或反射公共成员;不要根据相似 UI 库推测 API。