This commit is contained in:
chfei committed 2026-11-10 16:33:51 +08:00
1 parent 3135189ea3
commit a003d90b0e
21 files changed
+754 -145

No files matched your search

+191 -1
View File
@@ -2,12 +2,18 @@
来源:MAX.Common.WPF,2026-10-27 工作区源码快照。
按下方主题或文件名搜索。仅摘录选定文件的 public / protected 声明;省略方法体、初始化表达式与 XML 注释。这是定位参考,不是可直接编译的 C#,不保证包含嵌套类型的完整可见性上下文。行为说明见 SKILL.md;目标包版本不同时以实际包为准。
按下方主题或文件名搜索。API 代码块仅摘录选定文件的 public / protected 声明;省略方法体、初始化表达式与 XML 注释。TitleContent 与 SpacingStackPanel 另附属性说明和 XAML 用法。这是定位参考,不是可直接编译的 C#,不保证包含嵌套类型的完整可见性上下文。通用集成约束见 SKILL.md;目标包版本不同时以实际包为准。
目录:控件与布局、枚举、视图与绑定、线程与防抖、虚拟化与转换器
## 控件与布局
以下 TitleContent 与 SpacingStackPanel 示例在视图根元素声明命名空间:
```xml
xmlns:max="clr-namespace:MAX.Common.WPF.Controls;assembly=MAX.Common.WPF"
```
### Controls/NumberBox.cs
命名空间:`MAX.Common.WPF.Controls`
@@ -46,6 +52,55 @@ public Thickness LeftTitlePadding
public TitleContent()
```
`TitleContent` 是一个"标题 + 内容"布局控件:在 `Content` 周围额外渲染一个 `Title`,并可通过 `Placement` 决定标题相对内容的位置,同时支持标题宽度、对齐方式与内边距的精细控制。
| 属性 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `Content` | `object` | — | 继承自 `ContentControl`,主内容 |
| `Title` | `object` | `null` | 标题内容(可放字符串、任意 UIElement) |
| `Placement` | `TitlePlacementType` | `Top` | 标题相对内容的位置 |
| `TitleWidth` | `double` | `NaN` | 标题宽度;`NaN` 表示自动(Auto) |
| `TitleHorizontalAlignment` | `HorizontalAlignment` | `Left` | 标题在自身区域内的水平对齐 |
| `TitleVerticalAlignment` | `VerticalAlignment` | `Top` | 标题在自身区域内的垂直对齐 |
| `TopTitlePadding` | `Thickness` | `(7,2,0,1)` | `Placement=Top` 时标题的内边距 |
| `LeftTitlePadding` | `Thickness` | `(0,0,6,0)` | `Placement=Left` 时标题的内边距 |
标题位置示例使用 Top 与 Left;其他枚举值以实际程序集为准,不根据 padding 属性名推断。
#### 1. 最简用法(标题在上)
```xml
<max:TitleContent Title="用户名">
<TextBox />
</max:TitleContent>
```
#### 2. 标题在左侧 + 固定标题宽度(表单场景)
```xml
<max:TitleContent Title="用户名"
Placement="Left"
TitleWidth="80"
TitleVerticalAlignment="Center"
LeftTitlePadding="0,0,8,0">
<TextBox />
</max:TitleContent>
```
#### 3. 标题使用复杂 UIElement
```xml
<max:TitleContent Placement="Top">
<max:TitleContent.Title>
<StackPanel Orientation="Horizontal">
<TextBlock Text="密码" />
<TextBlock Text="*" Foreground="Red" />
</StackPanel>
</max:TitleContent.Title>
<PasswordBox />
</max:TitleContent>
```
### Controls/BoolContent.cs
命名空间:`MAX.Common.WPF.Controls`
@@ -74,6 +129,87 @@ public HorizontalAlignment? ItemHorizontalAlignment
public VerticalAlignment? ItemVerticalAlignment
```
> `SpacingStackPanel` 是一个"带间距 + 可选自动换行 + 可选统一子项尺寸"的布局面板,可看作 `StackPanel` 的增强版:既支持 StackPanel 式的单向排列,也支持 `WrapPanel` 式的换行排列,并且可以在**每个子项之间**插入水平/垂直间距。
#### 核心属性速查
| 属性 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `Orientation` | `Orientation` | `Horizontal` | 排列方向(水平/垂直),影响"主轴"与间距的解释 |
| `ChildWrapping` | `bool` | `false` | 是否自动换行(类似 WrapPanel);`false` 时类似 StackPanel |
| `HorizontalSpacing` | `double` | `NaN`(视为 0) | 子项之间的水平间距;校验要求 `> 0` 或 `NaN` |
| `VerticalSpacing` | `double` | `NaN`(视为 0) | 子项之间的垂直间距;校验要求 `> 0` 或 `NaN` |
| `ItemWidth` | `double` | `NaN`(自动) | 统一子项宽度;示例使用数值宽度,不将其当作 GridLength 的星号尺寸 |
| `ItemHeight` | `double` | `NaN`(自动) | 统一子项高度 |
| `ItemHorizontalAlignment` | `HorizontalAlignment?` | `Stretch` | 强制设置所有子项的 `HorizontalAlignment` |
| `ItemVerticalAlignment` | `VerticalAlignment?` | `Stretch` | 强制设置所有子项的 `VerticalAlignment` |
> 关键点:`HorizontalSpacing`/`VerticalSpacing` 不是"主轴/交叉轴"间距,而是**屏幕坐标意义上的水平/垂直间距**。当 `Orientation=Horizontal` 时通常用 `HorizontalSpacing` 拉开子项;`Orientation=Vertical` 时通常用 `VerticalSpacing` 拉开子项。
#### XAML 基本用法
示例沿用本节开头的 max 命名空间声明。
##### 1. 水平排列 + 子项水平间距(最常用)
```xml
<max:SpacingStackPanel Orientation="Horizontal" HorizontalSpacing="8">
<Button Content="确定" />
<Button Content="取消" />
<Button Content="应用" />
</max:SpacingStackPanel>
```
##### 2. 垂直排列 + 行间距
```xml
<max:SpacingStackPanel Orientation="Vertical" VerticalSpacing="6">
<TextBlock Text="第一行" />
<TextBlock Text="第二行" />
<TextBlock Text="第三行" />
</max:SpacingStackPanel>
```
##### 3. 自动换行(标签云 / 按钮流)
```xml
<max:SpacingStackPanel Orientation="Horizontal"
ChildWrapping="True"
HorizontalSpacing="8"
VerticalSpacing="8">
<Button Content="标签1" />
<Button Content="标签2" />
<Button Content="标签3" />
<!-- ... -->
</max:SpacingStackPanel>
```
##### 4. 统一子项尺寸(等宽卡片网格)
```xml
<max:SpacingStackPanel Orientation="Horizontal"
ChildWrapping="True"
ItemWidth="120"
ItemHeight="80"
HorizontalSpacing="10"
VerticalSpacing="10">
<Border Background="#EEE" />
<Border Background="#EEE" />
<Border Background="#EEE" />
</max:SpacingStackPanel>
```
##### 5. 控制子项对齐
```xml
<max:SpacingStackPanel Orientation="Horizontal"
HorizontalSpacing="8"
ItemVerticalAlignment="Center">
<TextBlock Text="姓名:" />
<TextBox Width="160" />
</max:SpacingStackPanel>
```
### Controls/SpacingUniformGrid.cs
命名空间:`MAX.Common.WPF.Controls`
@@ -156,6 +292,60 @@ public override bool Equals(object obj)
public override int GetHashCode()
```
#### 显示名称与库自带转换器
MAX.Common.WPF 已提供 `EnumDisplayConverter`,枚举显示优先复用它,不必另写读取 Description 的转换器。`EnumBindingMarkupExtension` 不会自动使用这个转换器,必须通过 `Converter` 显式传入:
- `Value` 保存枚举值本身,例如 `EEE.Admin`。
- 未设置 `Converter` 时,`Display` 为枚举值的 `ToString()`,例如 `"Admin"`,不会由标记扩展直接读取 `Description`。
- 设置 `EnumDisplayConverter` 后,`Display` 由枚举显示管理器生成;界面仍绑定 `Display`,选中值绑定 `Value`。
#### 系统初始化
`EnumDisplayConverter` 提供全局静态属性 `public static EnumDisplayManagerBase EnumDisplayManager { get; set; }`。在系统初始化、相关视图加载之前设置一次:
```csharp
using MAX.Common.WPF.Converters;
using MAX.Common.WPF.Utilities;
EnumDisplayConverter.EnumDisplayManager = new EnumDisplayManagerWPF(null);
```
将赋值放进项目已有的启动初始化流程;若已配置自定义显示管理器,复用现有配置,不要重复覆盖。
#### Description 显示示例
```csharp
using System.ComponentModel;
public enum EEE
{
[Description("管理员")]
Admin,
[Description("用户")]
User
}
```
`xmlns:wpf="MAX.WPF"`,`xmlns:local` 指向枚举所在命名空间。在视图资源中注册库自带转换器,再将它传给标记扩展:
```xml
<UserControl.Resources>
<wpf:EnumDisplayConverter x:Key="EnumDisplayConverter" />
</UserControl.Resources>
<ComboBox
ItemsSource="{wpf:EnumBindingMarkup EnumType={x:Type local:EEE},
Converter={StaticResource EnumDisplayConverter}}"
DisplayMemberPath="Display"
SelectedValuePath="Value"
wpf:EnumBindingExtension.SelectedEnum="{Binding SelectedRole, Mode=TwoWay}" />
```
`SelectedRole` 是带属性变更通知的 `EEE` 属性。界面显示“管理员”“用户”,选中值仍为 `EEE.Admin` 或 `EEE.User`。只需要展示选项时,可以省略 `SelectedValuePath` 和 `SelectedEnum` 绑定。
允许空选项时设置 `AllowNull=True`,并让选中属性可空。`NullDisplay` 默认为空字符串;只有显式设置为 null 时,标记扩展才会尝试调用转换器生成空选项的显示内容。`DisplayNullLast` 控制空选项是否放在末尾。
### Extensions/EnumBindingExtension.cs
命名空间:`MAX.Common.WPF.Extensions`