mgzhenhong.ASW2.WpfControls 2.1.3

ASW.WpfControls

📖 项目简介

ASW.WpfControls 是一个专业的 WPF 自定义控件库，提供了丰富的高质量、可定制的用户界面控件。这些控件经过精心设计和优化，具备现代化的外观、流畅的交互体验和强大的功能，能够显著提升 WPF 应用程序的用户体验和开发效率。

✨ 核心特性

🎨 现代化控件

• InputBox: 增强的输入框，支持水印、验证、密码模式等
• NumericBox: 专业的数值输入控件，支持格式化、范围限制
• MultiSelectComboBox: 多选下拉框，支持复选框和搜索
• SelectableTextBlock: 可选择文本块，支持文本选择和复制
• Switcher: 开关控件，现代化的布尔值输入组件

📝 数据展示控件

• LogList: 专业的日志显示控件，支持实时滚动和搜索
• LogItem: 日志项控件，支持不同级别的日志显示
• Icon: 矢量图标控件，支持字体图标和SVG图标
• CustomBorder: 自定义边框控件，支持复杂的边框样式

🎯 交互控件

• LinkButton: 链接按钮，支持多种链接样式
• CustomMenuItem: 自定义菜单项，增强的上下文菜单支持
• UserControls: 复合用户控件集合，提供完整的业务组件

🎨 主题系统

• 现代化主题: 11个预定义主题样式
• 深色/浅色模式: 完整的主题切换支持
• 自定义主题: 支持完全自定义的主题系统
• 响应式设计: 支持不同DPI和分辨率的适配

🚀 快速开始

安装

# Package Manager
Install-Package mgzhenhong.ASW.WpfControls

# .NET CLI
dotnet add package mgzhenhong.ASW.WpfControls

# PackageReference
<PackageReference Include="mgzhenhong.ASW.WpfControls" Version="x.x.x" />

引用资源

<Application x:Class="MyApp.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="pack://application:,,,/ASW.WpfControls;component/Themes/Generic.xaml" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

XAML命名空间

<Window x:Class="MyApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:aswc="clr-namespace:ASW.WpfControls;assembly=ASW.WpfControls">
    
</Window>

📚 控件详细指南

InputBox - 增强输入框

<aswc:InputBox Placeholder="请输入用户名"
               Text="{Binding UserName}" />


<aswc:InputBox Placeholder="请输入密码"
               IsPasswordMode="True"
               PasswordChar="●"
               Text="{Binding Password}" />


<aswc:InputBox Placeholder="请输入描述..."
               TextWrapping="Wrap"
               AcceptsReturn="True"
               MinHeight="100" />

NumericBox - 数值输入框

<aswc:NumericBox Value="{Binding Age}"
                 Minimum="0"
                 Maximum="150"
                 AllowDecimal="False" />


<aswc:NumericBox Value="{Binding Price}"
                 Minimum="0"
                 DecimalPlaces="2"
                 Format="C" />

MultiSelectComboBox - 多选下拉框

<aswc:MultiSelectComboBox ItemsSource="{Binding Categories}"
                          SelectedItems="{Binding SelectedCategories}"
                          DisplayMemberPath="Name" />


<aswc:MultiSelectComboBox ItemsSource="{Binding Users}"
                          SelectedItems="{Binding SelectedUsers}"
                          IsSearchable="True"
                          SearchWatermark="搜索用户..." />

SelectableTextBlock - 可选择文本

<aswc:SelectableTextBlock Text="{Binding LongText}"
                          TextWrapping="Wrap"
                          IsReadOnly="True" />


<aswc:SelectableTextBlock Text="{Binding LogContent}"
                          FontFamily="Consolas"
                          IsReadOnly="True">
    <aswc:SelectableTextBlock.ContextMenu>
        <ContextMenu>
            <MenuItem Header="复制" Command="ApplicationCommands.Copy" />
            <MenuItem Header="全选" Command="ApplicationCommands.SelectAll" />
        </ContextMenu>
    </aswc:SelectableTextBlock.ContextMenu>
</aswc:SelectableTextBlock>

Switcher - 开关控件

<aswc:Switcher IsChecked="{Binding IsEnabled}"
               OnContent="启用"
               OffContent="禁用" />


<aswc:Switcher IsChecked="{Binding NotificationEnabled}"
               OnContent="🔔"
               OffContent="🔕"
               OnBackground="Green"
               OffBackground="Gray" />

LogList - 日志显示控件

<aswc:LogList LogItems="{Binding LogItems}"
              AutoScroll="True"
              MaxLogCount="1000"
              ShowTimestamp="True"
              ShowLogLevel="True" />


<aswc:LogList LogItems="{Binding LogItems}"
              Background="Black"
              Foreground="White"
              FontFamily="Consolas" />

Icon - 图标控件

<aswc:Icon IconFont="{StaticResource SegoeUISymbol}"
           IconCode="&#xE74D;"
           Foreground="Blue"
           Width="24"
           Height="24" />


<aswc:Icon SvgSource="pack://application:,,,/Resources/Icons/home.svg"
           Width="32"
           Height="32" />

🎨 主题系统

使用预定义主题

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            
            <ResourceDictionary Source="pack://application:,,,/ASW.WpfControls;component/Themes/Generic.xaml" />
            
            
            
            
            
            
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

动态主题切换

public class ThemeManager
{
    private static readonly Dictionary<string, string> ThemeUris = new()
    {
        { "Default", "pack://application:,,,/ASW.WpfControls;component/Themes/Generic.xaml" },
        { "Dark", "pack://application:,,,/ASW.WpfControls;component/Themes/DarkTheme.xaml" },
        { "Light", "pack://application:,,,/ASW.WpfControls;component/Themes/LightTheme.xaml" }
    };
    
    public static void ApplyTheme(string themeName)
    {
        if (!ThemeUris.ContainsKey(themeName)) return;
        
        var app = Application.Current;
        var themeUri = new Uri(ThemeUris[themeName]);
        
        // 移除现有主题
        var existingTheme = app.Resources.MergedDictionaries
            .FirstOrDefault(d => d.Source?.ToString().Contains("ASW.WpfControls") == true);
        
        if (existingTheme != null) {
            app.Resources.MergedDictionaries.Remove(existingTheme);
        }
        
        // 应用新主题
        app.Resources.MergedDictionaries.Add(new ResourceDictionary { Source = themeUri });
    }
}

🔧 高级功能

数据绑定和验证

public class UserViewModel : INotifyPropertyChanged, IDataErrorInfo
{
    private string userName;
    private string email;
    
    public string UserName
    {
        get => userName;
        set { userName = value; OnPropertyChanged(); }
    }
    
    public string Email
    {
        get => email;
        set { email = value; OnPropertyChanged(); }
    }
    
    // 数据验证
    public string this[string columnName]
    {
        get
        {
            switch (columnName)
            {
                case nameof(UserName):
                    if (string.IsNullOrWhiteSpace(UserName))
                        return "用户名不能为空";
                    break;
                    
                case nameof(Email):
                    if (!string.IsNullOrEmpty(Email) && !IsValidEmail(Email))
                        return "邮箱格式不正确";
                    break;
            }
            return null;
        }
    }
    
    public string Error => null;
    
    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged([CallerMemberName] string name = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
    }
}

📊 性能特点

控件性能

控件渲染: ~5ms 初始化
数据绑定: ~1ms 更新延迟
主题切换: ~50ms 全局切换
内存占用: ~200KB 基础占用

虚拟化支持

<aswc:LogList LogItems="{Binding LogItems}"
              VirtualizingStackPanel.IsVirtualizing="True"
              VirtualizingStackPanel.VirtualizationMode="Recycling"
              MaxLogCount="10000" />

🐛 故障排除

常见问题

Q: 控件样式不生效？

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceDictionary Source="pack://application:,,,/ASW.WpfControls;component/Themes/Generic.xaml" />
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

Q: 数据绑定失败？

// 确保实现了INotifyPropertyChanged
public event PropertyChangedEventHandler PropertyChanged;
protected void OnPropertyChanged([CallerMemberName] string name = null)
{
    PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
}

Q: 主题切换无效？

// 确保在UI线程中执行主题切换
Application.Current.Dispatcher.Invoke(() => ThemeManager.ApplyTheme("Dark"));

💡 最佳实践

性能优化

// 1. 缓存控件实例
private static readonly Dictionary<string, UserControl> ControlCache = new();

// 2. 使用虚拟化
<aswc:LogList VirtualizingStackPanel.IsVirtualizing="True" />

// 3. 延迟加载
<aswc:MultiSelectComboBox IsVirtualizing="True" LoadOnDemand="True" />

代码组织

// 创建自定义控件基类
public abstract class CustomControlBase : UserControl
{
    static CustomControlBase()
    {
        DefaultStyleKeyProperty.OverrideMetadata(
            typeof(CustomControlBase),
            new FrameworkPropertyMetadata(typeof(CustomControlBase)));
    }
}

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目。

📄 许可证

本项目基于 MIT 许可证开源。详见 LICENSE 文件。

🔗 相关项目

• ASW.Wpf - WPF扩展库
• ASW.Utility - 通用工具库
• ASW.Windows - Windows系统工具