WPF 数据绑定实战:基于 WPF-Samples Colors 示例构建系统颜色列表的展示、排序与编辑

原创2026-10-14 12:42:56778 阅读
文章标签:示例工程

WPF 数据绑定实战:基于 WPF-Samples Colors 示例构建系统颜色列表的展示、排序与编辑

导读

本文围绕 WPF-Samples 仓库中的 Showing System Colors Using Data Services Sample(位于 Data Binding/Colors)展开,该示例把 WPF 框架内置的系统颜色(Brushes 静态属性)作为数据源,通过数据绑定呈现为可交互的颜色列表:支持按多种属性排序、一键复制当前颜色生成新颜色,并用 Slider 实时编辑新颜色的 Alpha/RGB/HSV 属性。读完本文,你将掌握 INotifyPropertyChanged 数据模型、ObservableCollection 数据源、CollectionView 排序、IValueConverter 转换器以及 IsSynchronizedWithCurrentItem 联动选中等一整套 WPF 数据绑定实战技能。

一、示例概览与文件结构

原文档对该示例的功能定位只有一句话,但其背后蕴含了完整的数据绑定工程实践:

The sample displays a list of the system colors and lets you sort the list in several ways. You can also add new colors to the list and modify properties of the new colors.

即:展示系统颜色列表 → 多种方式排序 → 添加新颜色 → 修改新颜色属性。整个功能闭环全部由数据绑定驱动,界面(MainWindow.xaml)与逻辑(MainWindow.cs)几乎解耦,是一个典型的数据服务(Data Services)风格示例。

该示例目录结构如下:

文件 职责
ColorItem.cs 颜色数据模型,实现 INotifyPropertyChanged,维护 RGB/HSV 双向换算与亮度计算
ColorItemList.cs 数据源集合,通过反射加载 Brushes 的全部系统颜色
MainWindow.xaml 主界面:颜色列表、排序单选钮、RGB/HSV 编辑面板、色块预览
MainWindow.cs 排序切换与"New Color"按钮的事件处理
ByteToDoubleConverter.cs byte(0–255)与 double 之间的双向转换
DoubleToStringConverter.cs double 到字符串的格式化显示转换
LuminanceToBrushConverter.cs 根据亮度决定文字前景色(白/黑),保证对比度
SourceToBoolConverter.cs 将颜色来源(内置/用户定义)映射为"是否可编辑"
Colors.csproj SDK 风格项目文件
App.xaml 应用入口,StartupUri 指向 MainWindow.xaml

二、构建与运行

2.1 获取源码

原文档建议的获取方式是:不借助 Git,直接在仓库主页点击 "Download ZIP" 按钮下载当前版本的压缩包,解压后在 Visual Studio 2022 中打开使用(若仓库已是最新状态,其中包含本示例的 Colors.csproj 项目文件)。

2.2 部署示例

  • 在 Visual Studio 中打开解决方案后,选择 Build > Deploy Solution(生成 > 部署解决方案)即可完成部署。

2.3 调试与运行

  • 若要调试并运行:按 F5,或选择 Debug > Start Debugging;
  • 若要不调试直接运行:按 Ctrl+F5,或选择 Debug > Start Without Debugging。

2.4 项目配置说明

从 Colors.csproj 可以看到该示例当前采用 SDK 风格项目格式:

  • TargetFramework 为 net10.0-windows(Windows 目标框架,当前仓库已迁移至 .NET 10);
  • UseWpf 为 true,启用 WPF 工作负载;
  • OutputType 为 WinExe,作为 Windows 桌面应用程序输出;
  • EnableDefaultItems 为 false,由项目文件显式声明 ApplicationDefinition(App.xaml)、Page(MainWindow.xaml)与各 Compile 项;
  • RootNamespace 与 AssemblyName 均为 Colors。

说明:上述目标框架以当前仓库实际内容为准。若要本地编译运行,需安装与该目标框架匹配的 .NET SDK 及相应 Visual Studio 版本(原文档以 Visual Studio 2022 为例),并确保安装了"使用 WPF 开发"的工作负载。

三、数据模型:ColorItem

ColorItem.cs 是整个示例的数据核心,它继承了 INotifyPropertyChanged 接口,使每个属性变更都能自动通知绑定系统刷新界面。

3.1 颜色来源枚举

public enum Sources
{
    UserDefined,
    BuiltIn
};

Sources 区分颜色是用户新建(UserDefined)还是系统内置(BuiltIn)。该枚举是界面能否编辑某个颜色的判断依据(详见下文 SourceToBoolConverter)。

3.2 两种构造方式

  • 内置颜色构造(ColorItem.cs):接收名称与 SolidColorBrush,从 brush.Color 中取出 A/R/G/B 四个分量并调用 HsvFromRgb() 初始化 HSV 值,Source 标记为 BuiltIn;
  • 复制构造(ColorItem.cs):以现有 ColorItem 为基础复制全部分量,Source 标记为 UserDefined,名称固定为 "New Color",并基于原颜色新建 SolidColorBrush。这就是"New Color"按钮生成新颜色的底层逻辑。

3.3 属性与通知

模型公开了 Name、Alpha、Red、Green、Blue(均为 byte)、Hue(0–360)、Saturation(0–1)、Value(0–1,均为 double)、Luminance(double)以及 Brush(SolidColorBrush)。每个可写属性在 setter 中先触发 OnPropertyChanged,再根据依赖关系级联更新:

  • Alpha/Red/Green/Blue 变更后调用 HsvFromRgb(),把 RGB 换算为 HSV 并刷新 Brush;
  • Hue/Saturation/Value 变更后调用 RgbFromHsv(),把 HSV 换算回 RGB 并刷新 Brush(setter 内部还会把 Hue 限制在 [0, 360],Saturation/Value 限制在 [0, 1]);
  • 每个分量在换算结果发生变化时也会主动抛出对应属性的通知,保证 UI 上 RGB 与 HSV 两组滑块始终互相同步。

3.4 RGB ↔ HSV 双向换算

HsvFromRgb()(ColorItem.cs)实现了标准 RGB→HSV 算法:取 R/G/B 的最大/最小值,Value = max,Saturation = (max > 0) ? (max − min) / max : 0,色相按 RGB 三通道的相对差计算并归一化到 [0, 360)。

RgbFromHsv()(ColorItem.cs)则是其逆过程:饱和度为 0 时 R=G=B=Value(灰色);否则将 Hue 归一化到 [0, 360) 后按 60° 分段,落入六边形色环的六个区间,分别计算 R/G/B 分量再乘以 255 转回 byte。算法中对浮点计算引入了 epsilon = 0.0001 的容差判断,避免接近零的抖动造成无效通知。

3.5 亮度计算与 Brush 刷新

UpdateBrush()(ColorItem.cs)承担两个职责:

  1. 用当前 A/R/G/B 构造新的 Color.FromArgb(alpha, red, green, blue) 并替换 Brush,抛出 Brush 变更通知——色块与列表项的底色随之实时更新;
  2. 按经典加权公式计算亮度并抛出 Luminance 通知:
var luminance = (0.30 * _red + 0.59 * _green + 0.11 * _blue) / 255.0;

即 Luminance = (0.30R + 0.59G + 0.11B) / 255,取值落在 [0, 1],供文字前景色与排序使用。

四、数据源:ColorItemList 反射加载系统颜色

ColorItemList.cs 继承 ObservableCollection<ColorItem>,在构造函数中通过反射遍历 WPF 内置的 Brushes 类:

var type = typeof(Brushes);
foreach (var propertyInfo in type.GetProperties(BindingFlags.Public | BindingFlags.Static))
{
    if (propertyInfo.PropertyType == typeof(SolidColorBrush))
        Add(new ColorItem(propertyInfo.Name, (SolidColorBrush)propertyInfo.GetValue(null, null)));
}

要点:

  • Brushes 中每个 public static 且类型为 SolidColorBrush 的属性(如 Brushes.Red、Brushes.AliceBlue 等)都被转换成一个 ColorItem,属性名即颜色名;
  • 因此示例天然覆盖 WPF 提供的全部系统命名颜色,无需手写数据;
  • ObservableCollection<ColorItem> 保证后续 Add 新颜色时,绑定到它的 ListBox 能自动收到集合变更通知并刷新列表。

五、界面布局与数据绑定

MainWindow.xaml 展示了"声明式 UI + 绑定"的完整组织方式。

5.1 资源区:数据源与转换器注册

<Window.Resources>
    <local:ColorItemList x:Key="ColorList"/>
    <local:ByteToDoubleConverter x:Key="ByteToDouble"/>
    <local:DoubleToStringConverter x:Key="DoubleToString"/>
    <local:SourceToBoolConverter x:Key="SourceToBool"/>
    <local:LuminanceToBrushConverter x:Key="LuminanceToBrush"/>
    ...
</Window.Resources>

根 DockPanel 通过 DataContext="{Binding Source={StaticResource ColorList}}" 把整个窗口的数据上下文指向同一个颜色集合实例,所有子元素共享该数据上下文。

5.2 列表项模板:颜色条

<DataTemplate x:Key="ColorItemTemplate">
    <Border Width="170" Height="30" Background="{Binding Path=Brush}">
        <TextBlock HorizontalAlignment="Center" VerticalAlignment="Center"
                   Foreground="{Binding Path=Luminance, Converter={StaticResource LuminanceToBrush}}"
                   Text="{Binding Path=Name}"/>
    </Border>
</DataTemplate>

每个颜色条以 Brush 为背景,颜色名显示在中央,文字颜色由亮度经 LuminanceToBrushConverter 决定(暗底白字、亮底黑字),保证任意颜色上文字都可读。另有一个 ListItemStyle 覆盖默认主题,将 ListBoxItem.Width 设为 Auto,避免列表项被拉伸占满整行。

5.3 编辑面板:RGB 与 HSV 滑块

控制面板分为三组:

  • 常规信息:Name 文本框(绑定 Name,并用 SourceToBool 控制是否可编辑)、Hex value 文本(直接绑定 Brush.Color)、Source 文本、只读的 Luminance 滑块与格式化数值;
  • RGB 属性:Alpha/Red/Green/Blue 四个滑块,范围均为 0–255,值经 ByteToDoubleConverter 在 byte 与 double 间转换,并绑定对应的颜色分量;同时用 SourceToBool 决定是否可编辑;
  • HSV 属性:Hue(0–360)、Saturation(0–1)、Value(0–1)三个滑块,直接绑定 double 属性,显示值经 DoubleToStringConverter 格式化为两位小数。

由于绑定默认为 TwoWay(TextBox.Text、Slider.Value 均支持双向),拖动滑块即可实时写入数据模型,RGB 与 HSV 两组控件通过模型的级联通知互相联动刷新。

5.4 颜色列表与当前项联动

<ListBox Name="colorListBox" Height="455" Width="200" DockPanel.Dock="Left"
         ItemsSource="{Binding}"
         ItemTemplate="{StaticResource ColorItemTemplate}"
         ItemContainerStyle="{StaticResource ListItemStyle}"
         IsSynchronizedWithCurrentItem="True"/>

IsSynchronizedWithCurrentItem="True" 让 ListBox 的选中项与集合视图(CollectionView)的 CurrentItem 保持同步。这正是编辑面板数据上下文的关键——滑块绑定的是集合的 CurrentItem(即当前选中颜色),选中哪一项,面板就编辑哪一项。

右侧 100×100 的色块预览 Border 同样直接绑定 CurrentItem 的 Brush 与 Name,随选中项实时变化。

六、排序实现:CollectionView 与 SortDescriptions

排序由排序单选钮的 Checked 事件驱动,处理逻辑位于 MainWindow.cs:

private void OnSortByChanged(object sender, RoutedEventArgs args)
{
    var rb = (RadioButton) sender;
    var sortBy = rb.Content.ToString();

    if (sortBy != null)
    {
        var cv = (CollectionView) CollectionViewSource.GetDefaultView((IEnumerable) rb.DataContext);
        cv.SortDescriptions.Clear();
        cv.SortDescriptions.Add(new SortDescription(sortBy, ListSortDirection.Descending));
    }
}

实现要点:

  • 通过 CollectionViewSource.GetDefaultView 获取数据源(ColorItemList)的默认集合视图,而不是直接操作集合本身;
  • 每次切换排序时先 SortDescriptions.Clear() 清空旧排序,再添加新的 SortDescription;
  • 排序依据取自单选按钮的 Content(Name/Luminance/Red/Green/Blue/Hue/Saturation/Value),即 ColorItem 的公开属性名,方向统一为 ListSortDirection.Descending(降序);
  • 集合视图排序不修改底层集合,ListBox 的展示顺序会即时更新;
  • 排序单选按钮共 8 个,均属同一 GroupName="SortBy",保证互斥选中;XAML 中八个按钮的布局见 MainWindow.xaml。

七、添加新颜色:复制当前项并选中

"New Color" 按钮的 Click 处理位于 MainWindow.cs:

private void OnNewColorClicked(object sender, RoutedEventArgs args)
{
    var button = (Button) sender;
    var colorList = (ColorItemList) button.DataContext;
    var cv = (CollectionView) CollectionViewSource.GetDefaultView(colorList);

    // add a new color based on the current one, then select the new one
    var newItem = new ColorItem((ColorItem) cv.CurrentItem);
    colorList.Add(newItem);
    cv.MoveCurrentTo(newItem);
}

流程拆解:

  1. 从按钮的 DataContext 取回 ColorItemList 集合实例;
  2. 通过 GetDefaultView 拿到集合视图,读取 cv.CurrentItem(当前选中颜色);
  3. 用复制构造函数基于当前颜色生成新 ColorItem(Source = UserDefined、名称 "New Color"),这样新颜色以当前颜色为起点,便于用户微调;
  4. colorList.Add(newItem) 触发 ObservableCollection 的集合变更通知,ListBox 自动新增一项;
  5. cv.MoveCurrentTo(newItem) 配合 IsSynchronizedWithCurrentItem="True",使列表选中并定位到新项,编辑面板随即切换到新颜色。

新颜色因为是 UserDefined,其 Name 文本框与所有 RGB/HSV 滑块均可编辑;而系统内置颜色经 SourceToBoolConverter 判定为不可编辑,保护内置数据不被误改。

八、转换器(IValueConverter)逐项解析

示例一共注册了四个转换器,分别解决一类典型的绑定类型适配问题。

8.1 ByteToDoubleConverter:byte ↔ double

ByteToDoubleConverter.cs 用于把 byte(0–255)颜色分量与 Slider.Value 的 double 类型互转:

  • Convert:直接把 byte 转为 double;
  • ConvertBack:先钳制到 [0, 255] 再转回 byte,防止滑块越界值导致 byte 溢出。

8.2 DoubleToStringConverter:double → 格式化文本

DoubleToStringConverter.cs 用 $"{o:f2}" 把 Hue/Saturation/Value/Luminance 格式化为两位小数显示,ConvertBack 返回 null,即只做单向显示转换。

8.3 LuminanceToBrushConverter:亮度 → 前景色

LuminanceToBrushConverter.cs 根据亮度阈值决定文字颜色:

return (luminance < 0.5) ? Brushes.White : Brushes.Black;

亮度低于 0.5 时用白色文字,否则用黑色文字,保证列表项与色块预览上的文字始终与背景形成对比。

8.4 SourceToBoolConverter:来源 → 可编辑性

SourceToBoolConverter.cs 把 ColorItem.Sources 枚举转为布尔值:

return (source != ColorItem.Sources.BuiltIn);

即只有用户定义的颜色返回 true。该结果绑定到 TextBox.IsEnabled 与各 Slider.IsEnabled,实现"内置颜色只读、新颜色可编辑"的交互约束。

九、数据绑定要点小结

透过该示例可以总结出一套可复用的 WPF 数据绑定模式:

  1. 模型层:实现 INotifyPropertyChanged,把业务计算(RGB/HSV 换算、亮度)封装进属性 setter,让通知链自动维护多属性联动;
  2. 集合层:用 ObservableCollection 承载数据,增删自动通知 UI;需要排序时通过 CollectionViewSource.GetDefaultView(...).SortDescriptions 操作视图而非集合;
  3. 视图层:Window 根元素统一设置 DataContext,用 DataTemplate 定义列表项外观,用 IsSynchronizedWithCurrentItem 让选中项与 CurrentItem 联动,配合按钮代码用 MoveCurrentTo 编程定位当前项;
  4. 类型适配:凡涉及滑块、文本显示、枚举开关等类型不匹配的绑定,用 IValueConverter 在 Convert/ConvertBack 中完成双向或单向转换,并按需做钳制与格式化。

如果你希望亲手验证这些机制,可打开仓库中的 Data Binding/Colors 目录,按上文"构建与运行"一节编译运行,逐一拖动 RGB/HSV 滑块、切换 8 种排序并点击 "New Color",观察列表、色块与编辑面板的实时联动。

登录后查看全文
WPF-Samples