关于HandyControl3.5.1中ListView显示空白的问题记录

问题现象

在使用HandyControl 3.5.1版本的WPF项目中，发现ListView控件无法正常显示内容。具体表现为：页面上其他控件（如TextBlock）可以正常渲染，但ListView区域始终为空白，无论使用数据绑定还是硬编码方式添加列表项，均无法显示。

环境说明

• 开发框架：WPF + .NET 8
• UI库：HandyControl 3.5.1
• 数据绑定：CommunityToolkit.Mvvm

排查过程

首先检查了常见的问题原因：

• DataContext是否正确设置：已确认在UserControl的构造函数中创建并赋值了ViewModel实例
• Items集合是否包含数据：ViewModel初始化时已添加测试数据，集合不为空
• 绑定语法是否正确：经检查无误
• 文字颜色与背景色是否相近：设置了对比明显的颜色后仍然无法显示

这些常规的排查方向都没有找到问题所在。

为了排除绑定的影响，编写了一个硬编码版本的ListView进行测试：

<ListView Height="200" Background="White">
    <ListViewItem>
        <Border Background="Orange" Margin="5" Padding="10">
            <TextBlock Text="测试数据" />
        </Border>
    </ListViewItem>
</ListView>

硬编码的ListViewItem同样无法显示，而ListView外部的TextBlock可以正常显示。这说明问题不在数据绑定层面，而是ListView控件本身的渲染出现了异常。

注意到项目中使用了HandyControl，怀疑是该UI库的全局样式覆盖了ListView的默认样式。尝试在ListView上添加以下两个属性：

<ListView Style="{x:Null}" ItemContainerStyle="{x:Null}" ...>

添加后，ListView恢复了正常显示。

原因分析

HandyControl的设计目标是提供一套统一的现代化控件样式，它会通过全局资源字典替换WPF原生控件的默认样式。在3.5.0版本中，对ListView和ListViewItem的样式修改引入了一个问题：

• ListViewItem的ControlTemplate可能将内容高度设置为0或可见性设置为Collapsed
• 样式继承链可能出现断裂，导致ListViewItem应用了不完整的模板
• 默认的虚拟化面板在计算可见项时可能出现错误

这个问题的特殊性在于：没有抛出任何异常，输出窗口也没有绑定错误信息，控件只是“安静地”不显示任何内容。经查阅社区反馈，确实有开发者在升级到3.5.0版本后遇到了相同的问题，可以确认这是一个特定版本的Bug。

解决方案

根据不同场景，有以下几种处理方式：

临时修复

在需要使用ListView的地方，添加清除样式的属性：

<ListView Style="{x:Null}" 
          ItemContainerStyle="{x:Null}"
          ItemsSource="{Binding Items}"
          Height="200">
    <ListView.ItemTemplate>
        <DataTemplate>
            <!-- 列表项布局 -->
        </DataTemplate>
    </ListView.ItemTemplate>
</ListView>

全局修复

在App.xaml中重置ListView相关的样式：

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <hc:ThemeResources/>
            <hc:Theme/>
        </ResourceDictionary.MergedDictionaries>
        
        <Style TargetType="ListView" BasedOn="{x:Null}"/>
        <Style TargetType="ListViewItem" BasedOn="{x:Null}"/>
    </ResourceDictionary>
</Application.Resources>

替换控件

使用ItemsControl配合ScrollViewer来替代ListView：

<ScrollViewer Height="200" VerticalScrollBarVisibility="Auto">
    <ItemsControl ItemsSource="{Binding Items}">
        <ItemsControl.ItemTemplate>
            <DataTemplate>
                <!-- 列表项布局 -->
            </DataTemplate>
        </ItemsControl.ItemTemplate>
    </ItemsControl>
</ScrollViewer>

小结

在使用第三方UI库时，如果控件行为异常，可以尝试清除样式来判断是否是UI库的样式覆盖导致的问题。同时，生产环境中建议锁定UI库的具体版本，避免自动升级引入不兼容的变化。