1
This commit is contained in:
1 parent
3135189ea3
commit
a003d90b0e
21 files changed
+754
-145
No files matched your search
@@ -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`
|
||||
|
||||
Reference in new issue
Block a user