536 lines
17 KiB
Markdown
536 lines
17 KiB
Markdown
# 常用 API 声明参考
|
||
|
||
来源:MAX.Common.WPF,2026-10-27 工作区源码快照。
|
||
|
||
按下方主题或文件名搜索。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`
|
||
|
||
```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()
|
||
```
|
||
|
||
`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`
|
||
|
||
```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
|
||
```
|
||
|
||
> `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`
|
||
|
||
```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()
|
||
```
|
||
|
||
#### 显示名称与库自带转换器
|
||
|
||
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`
|
||
|
||
```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)
|
||
```
|