SharpBoxesCore.Wpf 1.0.0

📦 SharpBoxesCore.Wpf

🔧 为 WPF MVVM 开发者打造的轻量级工具库
🌟 支持只读属性绑定、行为扩展、属性编辑控件
🚀 简洁 · 高效 · 无代码隐藏

📖 简介

SharpBoxesCore.Wpf 是一个专为 WPF + MVVM 架构设计的实用控件与扩展库。它解决了传统 WPF 开发中常见的痛点，如：

• 无法监听只读依赖属性（如 VerticalOffset）
• 缺少通用的属性编辑控件
• MVVM 中 UI 状态同步复杂

该库提供三大核心组件，帮助你构建更干净、更灵活、更可维护的 WPF 应用。

🧩 核心组件概览

🔧 详细功能说明

1. 🎛️ PropertyGrid 控件

一个功能完整的属性编辑器，支持运行时查看和修改对象属性。

✅ 功能特性

💡 使用示例

<Window xmlns:pg="http://schemas.sharpboxes.com/wpf/propertygrid">
    <pg:PropertyGrid 
        SelectedObject="{Binding SelectedItem}" 
        Margin="10" />
</Window>

📝 支持的属性特性

[Category("外观")]
[DisplayName("边框颜色")]
[Description("设置控件边框颜色")]
[PropertyOrder(1)]
public Color BorderColor { get; set; }

2. 🔗 ReadOnlyBinding 附加属性

一种声明式、简洁、现代化的方式，用于监听只读依赖属性的变化。

✅ 核心能力

• ✅ 监听任意 DependencyProperty（包括只读）
• ✅ 同步值到 ViewModel 属性
• ✅ 触发 ICommand 或 IAsyncCommand
• ✅ 支持 IValueConverter 转换
• ✅ 条件过滤：Predicate<object>
• ✅ 自动 await IAsyncCommand（兼容 CommunityToolkit.MVVM）

💡 使用示例

<ScrollViewer
    local:ReadOnlyBinding.Property="VerticalOffset"
    local:ReadOnlyBinding.TargetPropertyName="CurrentScroll"
    local:ReadOnlyBinding.Command="{Binding ScrollCommand}"
    local:ReadOnlyBinding.Converter="{StaticResource OffsetToText}"
    local:ReadOnlyBinding.Filter="{Binding ShouldNotifyFilter}" />

🧩 绑定流程

UI 属性变化 → (可选过滤) → (可选转换) → 更新 ViewModel 属性 + 执行命令

3. 🤖 BindReadOnlyPropertyBehavior 行为

一种面向对象、可复用的方式，用于监听只读属性变化，适合需要封装复杂逻辑的场景。

✅ 功能特性

💡 使用示例

<ScrollViewer x:Name="MyScroll" Height="300">
    <i:Interaction.Behaviors>
        <local:BindReadOnlyPropertyBehavior 
            Property="{x:Static ScrollViewer.VerticalOffsetProperty}"
            TargetPropertyName="CurrentScrollOffset"
            Command="{Binding ScrollCommand}"
            Converter="{StaticResource MyConverter}"
            Filter="{Binding LargeScrollFilter}" />
    </i:Interaction.Behaviors>
</ScrollViewer>

⚖️ ReadOnlyBinding vs Behavior

🎯 典型使用场景

⚙️ 依赖项

<PackageReference Include="CommunityToolkit.Mvvm" Version="8.4.0" />
<PackageReference Include="Microsoft.Xaml.Behaviors.Wpf" Version="1.1.135" />

💡 CommunityToolkit.Mvvm 用于 IAsyncCommand 支持
💡 Microsoft.Xaml.Behaviors.Wpf 用于 Behavior 支持

🖥️ 支持的框架

🧪 完整示例

ViewModel

[ObservableProperty]
private double _currentScroll;

[RelayCommand]
private async Task ScrollCommand(double offset)
{
    await Task.Delay(100);
    Debug.WriteLine($"滚动到: {offset}");
}

public Predicate<object> LargeScrollFilter => v => v is double d && d > 100;

XAML

<Window 
    xmlns:i="http://schemas.microsoft.com/xaml/behaviors"
    xmlns:local="clr-namespace:SharpBoxesCore.Wpf">

    
    <ScrollViewer
        local:ReadOnlyBinding.Property="VerticalOffset"
        local:ReadOnlyBinding.TargetPropertyName="CurrentScroll"
        local:ReadOnlyBinding.Command="{Binding ScrollCommand}" />

    
    <ScrollViewer x:Name="MyScroll">
        <i:Interaction.Behaviors>
            <local:BindReadOnlyPropertyBehavior 
                Property="{x:Static ScrollViewer.VerticalOffsetProperty}"
                TargetPropertyName="CurrentScroll"
                Command="{Binding ScrollCommand}" />
        </i:Interaction.Behaviors>
    </ScrollViewer>

    
    <pg:PropertyGrid SelectedObject="{Binding SelectedItem}" />

</Window>

📚 最佳实践

• ✅ 优先使用 ReadOnlyBinding 实现简单绑定
• ✅ 在复杂逻辑中使用 Behavior
• ✅ 为 PropertyGrid 的属性添加 Category 和 Description
• ✅ 使用 IAsyncCommand 避免 UI 冻结
• ✅ 在 OnDetaching 中清理监听，防止内存泄漏（库已自动处理）

📎 参考资料

• WPF 依赖属性系统
• CommunityToolkit.MVVM 文档
• Microsoft.Xaml.Behaviors.Wpf GitHub

📬 反馈与贡献

欢迎提交 Issue 或 Pull Request！

• GitHub: https://github.com/yourusername/SharpBoxesCore.Wpf
• 邮箱: support@sharpboxes.com

© 2025 SharpBoxes. All rights reserved.
Made with ❤️ for WPF developers.

✅ 一句话总结

SharpBoxesCore.Wpf = 属性编辑 + 只读绑定 + MVVM 友好 = 更高效的 WPF 开发体验