AtomUI/docs/Desktop.Controls/ListBox/ListBoxStyling.md

ListBox 自定义样式指南

ListBox 控件族的视觉表现通过 ControlTheme + Design Token 系统控制。以下介绍各种常见的自定义方式。

---

1. 使用属性直接控制

尺寸

<atom:ListBox SizeType="Large" />
<atom:ListBox SizeType="Middle" />
<atom:ListBox SizeType="Small" />

无边框模式

<atom:ListBox IsBorderless="True" />

自定义悬浮和选中背景色

<atom:ListBox ItemHoverBg="#E6F4FF" ItemSelectedBg="#BAE0FF" />

选中指示器

<!-- 启用勾选图标 -->
<atom:ListBox IsShowSelectedIndicator="True" />

<!-- 自定义选中图标 -->
<atom:ListBox IsShowSelectedIndicator="True">
    <atom:ListBox.SelectedIndicator>
        <atom:IconTemplate>
            <antdicons:HeartFilled />
        </atom:IconTemplate>
    </atom:ListBox.SelectedIndicator>
</atom:ListBox>

禁用选择

<!-- 纯展示模式，不可选择 -->
<atom:ListBox IsSelectable="False" />

过滤与高亮

<atom:ListBox ItemFilterValue="{Binding SearchText}"
              ItemFilterHighlightStrategy="All" />

自定义空状态

<atom:ListBox>
    <atom:ListBox.EmptyIndicatorTemplate>
        <DataTemplate>
            <atom:TextBlock Text="暂无数据" HorizontalAlignment="Center" />
        </DataTemplate>
    </atom:ListBox.EmptyIndicatorTemplate>
</atom:ListBox>

---

2. 通过 Style 覆盖样式

全局 ListBox 样式

<Window.Styles>
    <Style Selector="atom|ListBox">
        <Setter Property="Margin" Value="0 5" />
        <Setter Property="Background" Value="Transparent" />
    </Style>
</Window.Styles>

自定义 ListBoxItem 样式

<!-- 自定义悬浮态背景色 -->
<Style Selector="atom|ListBoxItem:pointerover">
    <Setter Property="Background" Value="#F0F5FF" />
</Style>

<!-- 自定义选中态背景色 -->
<Style Selector="atom|ListBoxItem:selected:not(:disabled)">
    <Setter Property="Background" Value="#D6E4FF" />
    <Setter Property="Foreground" Value="#1677FF" />
</Style>

<!-- 禁用态 -->
<Style Selector="atom|ListBoxItem:disabled">
    <Setter Property="Opacity" Value="0.5" />
</Style>

按尺寸定制

<Style Selector="atom|ListBox[SizeType=Large]">
    <Setter Property="FontSize" Value="16" />
</Style>

<Style Selector="atom|ListBox[SizeType=Small]">
    <Setter Property="FontSize" Value="12" />
</Style>

---

3. 通过 ControlTheme 完全替换主题

如需彻底替换 ListBox 或 ListBoxItem 的模板：

<ControlTheme x:Key="MyCustomListBoxItem" TargetType="atom:ListBoxItem">
    <Setter Property="Template">
        <ControlTemplate TargetType="atom:ListBoxItem">
            <Border Background="{TemplateBinding Background}"
                    Padding="{TemplateBinding Padding}"
                    CornerRadius="{TemplateBinding CornerRadius}">
                <ContentPresenter Content="{TemplateBinding Content}"
                                  ContentTemplate="{TemplateBinding ContentTemplate}" />
            </Border>
        </ControlTemplate>
    </Setter>
</ControlTheme>

⚠️ 注意：完全替换 ControlTheme 将丢失内置的选中指示器和过滤高亮功能。建议优先使用 Style 覆盖。

---

4. 自定义 ItemTemplate

通过 ItemTemplate 自定义列表项的内容布局：

<atom:ListBox>
    <atom:ListBox.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal" Spacing="8">
                <antdicons:UserOutlined Width="16" Height="16" />
                <atom:TextBlock Text="{Binding Name}" />
                <atom:TextBlock Text="{Binding Description}" Opacity="0.5" />
            </StackPanel>
        </DataTemplate>
    </atom:ListBox.ItemTemplate>
</atom:ListBox>

---

样式选择器速查

ListBox 选择器

选择器	说明
atom|ListBox	匹配所有 ListBox 实例
atom|ListBox[SizeType=Large]	匹配大号 ListBox
atom|ListBox[SizeType=Middle]	匹配中号 ListBox
atom|ListBox[SizeType=Small]	匹配小号 ListBox
atom|ListBox[IsBorderless=True]	匹配无边框 ListBox

ListBoxItem 选择器

选择器	说明
atom|ListBoxItem	匹配所有 ListBoxItem
atom|ListBoxItem:selected	匹配选中状态的 ListBoxItem
atom|ListBoxItem:pointerover	匹配鼠标悬浮的 ListBoxItem
atom|ListBoxItem:disabled	匹配禁用的 ListBoxItem
atom|ListBoxItem:selected:not(:disabled)	匹配非禁用的选中项

模板内部元素选择器

选择器	说明
atom|ListBoxItem /template/ Border#Frame	列表项外框
atom|ListBoxItem /template/ ContentPresenter#ContentPresenter	列表项内容区
atom|ListBoxItem /template/ atom|IconPresenter#SelectedIndicator	选中指示器图标
atom|ListBox /template/ ContentPresenter#EmptyIndicator	空状态指示器