17 KiB
常用 API 声明参考
来源:MAX.Common.WPF,2026-10-27 工作区源码快照。
按下方主题或文件名搜索。API 代码块仅摘录选定文件的 public / protected 声明;省略方法体、初始化表达式与 XML 注释。TitleContent 与 SpacingStackPanel 另附属性说明和 XAML 用法。这是定位参考,不是可直接编译的 C#,不保证包含嵌套类型的完整可见性上下文。通用集成约束见 SKILL.md;目标包版本不同时以实际包为准。
目录:控件与布局、枚举、视图与绑定、线程与防抖、虚拟化与转换器
控件与布局
以下 TitleContent 与 SpacingStackPanel 示例在视图根元素声明命名空间:
xmlns:max="clr-namespace:MAX.Common.WPF.Controls;assembly=MAX.Common.WPF"
Controls/NumberBox.cs
命名空间:MAX.Common.WPF.Controls
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
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. 最简用法(标题在上)
<max:TitleContent Title="用户名">
<TextBox />
</max:TitleContent>
2. 标题在左侧 + 固定标题宽度(表单场景)
<max:TitleContent Title="用户名"
Placement="Left"
TitleWidth="80"
TitleVerticalAlignment="Center"
LeftTitlePadding="0,0,8,0">
<TextBox />
</max:TitleContent>
3. 标题使用复杂 UIElement
<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
public class BoolContent : Control
public object TrueContent
public object FalseContent
public bool Bool
public CornerRadius CornerRadius
Controls/SpacingStackPanel.cs
命名空间:MAX.Common.WPF.Controls
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. 水平排列 + 子项水平间距(最常用)
<max:SpacingStackPanel Orientation="Horizontal" HorizontalSpacing="8">
<Button Content="确定" />
<Button Content="取消" />
<Button Content="应用" />
</max:SpacingStackPanel>
2. 垂直排列 + 行间距
<max:SpacingStackPanel Orientation="Vertical" VerticalSpacing="6">
<TextBlock Text="第一行" />
<TextBlock Text="第二行" />
<TextBlock Text="第三行" />
</max:SpacingStackPanel>
3. 自动换行(标签云 / 按钮流)
<max:SpacingStackPanel Orientation="Horizontal"
ChildWrapping="True"
HorizontalSpacing="8"
VerticalSpacing="8">
<Button Content="标签1" />
<Button Content="标签2" />
<Button Content="标签3" />
<!-- ... -->
</max:SpacingStackPanel>
4. 统一子项尺寸(等宽卡片网格)
<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. 控制子项对齐
<max:SpacingStackPanel Orientation="Horizontal"
HorizontalSpacing="8"
ItemVerticalAlignment="Center">
<TextBlock Text="姓名:" />
<TextBox Width="160" />
</max:SpacingStackPanel>
Controls/SpacingUniformGrid.cs
命名空间:MAX.Common.WPF.Controls
public class SpacingUniformGrid : Panel
public int Rows
public int Columns
public double RowSpacing
public double ColumnSpacing
Controls/AutoColumnsUniformGrid.cs
命名空间:MAX.Common.WPF.Controls
public class AutoColumnsUniformGrid : UniformGrid
public double CellMinWidth
public int MinColumns
public int MaxColumns
Controls/ButtonPopup.cs
命名空间:MAX.Common.WPF.Controls
public class ButtonPopup : CustomPopup
public ButtonBase SourceButton
public ICommand OnClickOpenCommand
public ButtonPopup() : base()
Controls/NotifyIcon.cs
命名空间:MAX.Common.WPF.Controls
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
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; }。在系统初始化、相关视图加载之前设置一次:
using MAX.Common.WPF.Converters;
using MAX.Common.WPF.Utilities;
EnumDisplayConverter.EnumDisplayManager = new EnumDisplayManagerWPF(null);
将赋值放进项目已有的启动初始化流程;若已配置自定义显示管理器,复用现有配置,不要重复覆盖。
Description 显示示例
using System.ComponentModel;
public enum EEE
{
[Description("管理员")]
Admin,
[Description("用户")]
User
}
xmlns:wpf="MAX.WPF",xmlns:local 指向枚举所在命名空间。在视图资源中注册库自带转换器,再将它传给标记扩展:
<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
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
public class ViewModelExtension
public static bool GetAutoAssignViewModel(DependencyObject obj)
public static void SetAutoAssignViewModel(DependencyObject obj, bool value)
Extensions/BindingProxies.cs
命名空间:MAX.Common.WPF.Extensions
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
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
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
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
public class DebounceDispatcher
public void Debounce(TimeSpan delay, Action action)
Utilities/AsyncDebouncer.cs
命名空间:MAX.Common.WPF.Utilities
public class AsyncDebouncer(int delayMilliseconds = 300)
public void Invoke(Func<Task> action)
Utilities/Timers/TimerControllerBase.cs
命名空间:MAX.Common.WPF.Utilities.Timers
public abstract class TimerControllerBase : IDisposable
public abstract void Dispose()
Utilities/Timers/DispatcherTimerController.cs
命名空间:MAX.Common.WPF.Utilities.Timers
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
public class VirtualizingItemsControl : ItemsControl
public VirtualizingItemsControl()
Virtualization/VirtualizingWrapPanel.cs
命名空间:MAX.Common.WPF.Virtualization
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
public interface IItemSizeProvider
Converters/Boolean2VisibilityConverter.cs
命名空间:MAX.Common.WPF.Converters
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
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
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
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)