ZenUI.Wpf 0.1.0-preview.12

<p align="center"> <img src="https://raw.githubusercontent.com/XiaQueNet/ZenUI-WPF/main/assets/brand/zenui-logo.png" alt="ZenUI for WPF" width="570" /> </p>

<p align="center"> 面向 .NET Framework 4.6.2 及以上版本与现代 .NET 8 WPF 的控件库和通用转换器。 </p>

ZenUI 以克制、清晰的 Zen Style 改善 WPF 控件的默认体验，同时保留原生属性、事件、命令、键盘操作和可访问性契约。

核心能力

• 提供 Button、TextBox、DataGrid、DatePicker、DateTimePicker 等常用 WPF 控件。
• 内置 Light、Dark、HighContrast 主题，支持运行时切换。
• 提供 Compact、Standard、Comfortable 三档界面密度。
• 使用语义化设计 Token，应用无需复制模板即可覆盖颜色与尺寸。
• 覆盖悬停、按下、焦点、选中、禁用、只读和验证错误等交互状态。
• 提供 net462、net471、net472、net5.0-windows 与 net8.0-windows 资产；正式支持 .NET Framework 4.6.2 及以上版本与 .NET 8 及以上版本，并为已停止维护的 .NET 5/6/7 提供兼容资产。

安装

按需安装控件库或转换器包：

dotnet add package ZenUI.Wpf
dotnet add package ZenUI.Wpf.Converters

两个包互不依赖，可以单独安装。

快速开始

引入稳定的 XAML 命名空间后即可使用控件，默认样式会由 Themes/Generic.xaml 自动加载：

<Window
    xmlns:zen="https://zenui.mnorg.cn/xaml/wpf">
    <StackPanel>
        <zen:ZenTextBox Watermark="请输入内容" />
        <zen:ZenButton Content="保存" Variant="Primary" />
        <zen:ZenSwitch IsChecked="True" />
        <zen:ZenLoading IsLoading="True" LoadingText="正在加载…" />
        <zen:ZenAlert Content="保存成功" Severity="Success" />
    </StackPanel>
</Window>

应用需要直接使用 ZenUI Token 或具名样式时，可以显式合并默认主题：

<ResourceDictionary Source="pack://application:,,,/ZenUI.Wpf;component/Themes/Generic.xaml" />

转换器包使用独立的 XAML 命名空间，无需在应用资源中注册实例：

<Window
    xmlns:zc="https://zenui.mnorg.cn/xaml/wpf/converters">
    <ProgressBar
        Visibility="{Binding IsLoading,
            Converter={zc:BoolToVisibilityConverter}}" />
</Window>

转换器包提供布尔值、空值、集合内容和数值比较到 Visibility 的转换，并统一支持结果反转以及 Collapsed、Hidden 配置。

组件

TextBox、PasswordBox、ComboBox 和 DataGrid 单元格支持 WPF Validation.HasError。Slider 支持水平与垂直方向，ProgressBar 支持垂直方向与 IsIndeterminate，ComboBox 支持 IsEditable。

主题与 Density

默认使用浅色主题。可以在运行时分别切换颜色主题和界面密度：

using ZenUI.Wpf.Theming;

ZenThemeManager.ApplyTheme(
    Application.Current.Resources,
    ZenTheme.Dark);

ZenDensityManager.ApplyDensity(
    Application.Current.Resources,
    ZenDensity.Compact);

主题管理器默认尊重并持续监听 Windows 高对比度设置。所有控件颜色均通过语义化 DynamicResource 获取，应用可以只覆盖单个 Token，不必复制完整控件模板。

完整用法参见主题、Density 定制与迁移指南。

设计原则

Zen Style 的核心不是简单减少元素，而是删除噪声、保留必要信息，并将必要信息呈现得从容、清晰：

• 优先使用留白、排版和对齐建立信息层级，避免装饰堆叠。
• 中性色承担主要结构，强调色只用于主要操作、焦点和明确状态。
• 动画只用于解释状态变化、操作反馈或空间关系。
• 次要能力按需呈现，不与当前任务争夺注意力。
• 极简不能牺牲可读性、可访问性、状态辨识或操作效率。

ZenUI 只调整 WPF 控件的默认值、主题资源和控件模板，不以视觉简化为由删除基类能力。非默认视觉通过依赖属性、设计 Token、具名样式或模板入口保留，并由自动化测试覆盖。

公共 API、状态命名、模板契约、主题资源和可访问性的完整要求参见控件设计规范。

密码安全

ZenPasswordBox 不会把密码明文复制到依赖属性或 ViewModel。通过不携带明文的 PasswordChanged 事件获知变化，并仅在需要时读取和释放 SecurePassword：

private void PasswordBox_OnPasswordChanged(object sender, RoutedEventArgs e)
{
    var passwordBox = (ZenPasswordBox)sender;
    using (var password = passwordBox.SecurePassword)
    {
        // 立即验证 password，不要长期保存明文副本。
    }
}

示例与开发

• samples/ZenUI.Wpf.Gallery：控件目录，使用 Prism Region Navigation 和 MVVM。
• samples/ZenUI.Wpf.PosDemo：完整业务应用示例。

常用验证命令：

dotnet restore ZenUI.Wpf.slnx
dotnet build ZenUI.Wpf.slnx -c Release --no-restore
dotnet test --project tests/ZenUI.Wpf.Tests/ZenUI.Wpf.Tests.csproj -c Release -f net472 --max-parallel-test-modules 1 --no-build
dotnet test --project tests/ZenUI.Wpf.Converters.Tests/ZenUI.Wpf.Converters.Tests.csproj -c Release -f net472 --max-parallel-test-modules 1 --no-build

日常开发按组件测试、net472 单框架全量测试和全框架矩阵测试三个等级验证，具体触发条件参见测试规范。仓库在 Windows CI 中将编译器与 .NET 分析器警告视为错误；主分支 Push 验证 net472 与 .NET 10 for Windows，Pull Request 和发布流程通过完整测试矩阵逐版本验证 .NET Framework 4.6.2～4.8.1 与 .NET 8/9/10 for Windows，并在对应运行时上对 .NET 5/6/7 for Windows 执行兼容性契约测试和依赖漏洞扫描。正式发布包包含 net462、net471、net472、net5.0-windows 与 net8.0-windows 五套资产，并验证 NuGet/Symbol 包、多目标框架消费者安装以及多主题、多 Density、多 DPI 视觉快照。正式产物通过 .\scripts\pack-release.ps1 -Version <version> -Package <package-id> 生成；只发布有实际变更的包。

参与贡献

欢迎提交功能、修复和文档改进。开始开发前请阅读贡献指南：

• 从 main 创建短期分支，建议使用 feature/*、fix/*、docs/* 或 chore/*。
• Git 提交的标题和正文统一使用中文，并简洁说明实际变更。
• 新增或修改控件时，应保留 WPF 原有能力，并覆盖适用的交互状态、主题和可访问性契约。
• 提交前运行 Release 构建、自动化测试及相关打包检查，确保编译器和分析器警告为零。
• 新增或修改的公共 API 必须提供符合项目规范的 XML 文档注释。

文档

• 文档索引
• 快速开始
• 控件设计规范
• 主题 Token 规范
• 主题、Density 定制与迁移指南
• 测试规范
• C# 注释规范
• 贡献指南
• 变更记录

交流与反馈

<h3 align="center"> <a href="https://qun.qq.com/universal-share/share?ac=1&authKey=kkQCZjWfmhA%2FemIxl7g6kzW0mDbWArzaxhFQWWRm34mSvUdaYJK8X5mYacfvkaWP&busi_data=eyJncm91cENvZGUiOiI2NTA1OTAxNzYiLCJ0b2tlbiI6IkthNXNxYWdkRi9UbDdXdFZCeE1LRjNVT3l4ZSsyNDllYmdNeUtac2U1Z0J1VmlpN0NSVGFKZmdyeUVBY04xd2giLCJ1aW4iOiIxMDQwMTUzNjUzIn0%3D&data=wm78IvqFbkqW1duGxv6xP8Ny_iQXCLWcqSrPYm1rYeDUwUIbY8HwkEAVvMlEx-gYJNpqGKfwh8y9hIXGGQlXig&svctype=4&tempid=h5_group_info">👉 点击加入 ZenUI-WPF QQ 交流群</a> </h3>

<p align="center"> 群号：<code>650590176</code> </p>

<p align="center"> <img src="assets/community/qq-group-650590176-qr.png" alt="ZenUI-WPF QQ 交流群二维码，群号 650590176" width="360" /> </p>

License

ZenUI.Wpf 使用 MIT License。