AtomUI/docs/Desktop.Controls/ComboBox/ComboBoxStyling.md

ComboBox 自定义样式指南

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

---

1. 使用属性直接控制

最简单的方式是通过 ComboBox 的公共属性来控制外观：

<!-- 不同样式变体 -->
<atom:ComboBox StyleVariant="Outline" PlaceholderText="Please select" Width="300">
    <atom:ComboBoxItem>选项一</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项二</atom:ComboBoxItem>
</atom:ComboBox>
<atom:ComboBox StyleVariant="Filled" PlaceholderText="Please select" Width="300">
    <atom:ComboBoxItem>选项一</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项二</atom:ComboBoxItem>
</atom:ComboBox>
<atom:ComboBox StyleVariant="Borderless" PlaceholderText="Please select" Width="300">
    <atom:ComboBoxItem>选项一</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项二</atom:ComboBoxItem>
</atom:ComboBox>

<!-- 不同尺寸 -->
<atom:ComboBox SizeType="Large" PlaceholderText="Large" />
<atom:ComboBox SizeType="Middle" PlaceholderText="Default" />
<atom:ComboBox SizeType="Small" PlaceholderText="Small" />

<!-- 验证状态 -->
<atom:ComboBox Status="Error" PlaceholderText="Error" Width="300" />
<atom:ComboBox Status="Warning" PlaceholderText="Warning" Width="300" />

<!-- 前置/后置标签 -->
<atom:ComboBox LeftAddOn="http://" RightAddOn=".com" PlaceholderText="Please select" Width="300">
    <atom:ComboBoxItem>选项一</atom:ComboBoxItem>
</atom:ComboBox>

<!-- 内部前缀/后缀 -->
<atom:ComboBox
    ContentLeftAddOn="{antdicons:AntDesignIconProvider Kind=UserOutlined, FillBrush=#D7D7D7}"
    ContentRightAddOn="{antdicons:AntDesignIconProvider Kind=InfoCircleOutlined, FillBrush=#8C8C8C}"
    PlaceholderText="Please select" Width="300">
    <atom:ComboBoxItem>选项一</atom:ComboBoxItem>
</atom:ComboBox>

📖 完整示例参考：controlgallery/AtomUIGallery/ShowCases/Views/Navigation/ComboBoxShowCase.axaml

---

2. 通过 Style 覆盖样式

可以在 AXAML 中使用 Style 对 ComboBox 进行全局或局部样式覆盖：

全局统一宽度

<Window.Styles>
    <Style Selector="atom|ComboBox">
        <Setter Property="Width" Value="300" />
        <Setter Property="Margin" Value="0,5" />
    </Style>
</Window.Styles>

按样式变体定制

<!-- 填充样式的自定义背景 -->
<Style Selector="atom|ComboBox[StyleVariant=Filled]">
    <Setter Property="Opacity" Value="0.9" />
</Style>

使用伪类选择器

<!-- 错误状态下加粗文本 -->
<Style Selector="atom|ComboBox:error">
    <Setter Property="FontWeight" Value="SemiBold" />
</Style>

<!-- 警告状态的自定义样式 -->
<Style Selector="atom|ComboBox:warning">
    <Setter Property="FontWeight" Value="SemiBold" />
</Style>

通过属性选择器定制尺寸

<!-- 所有大号 ComboBox 使用粗体 -->
<Style Selector="atom|ComboBox[SizeType=Large]">
    <Setter Property="FontWeight" Value="SemiBold" />
</Style>

<!-- 所有小号 ComboBox 限制宽度 -->
<Style Selector="atom|ComboBox[SizeType=Small]">
    <Setter Property="MaxWidth" Value="200" />
</Style>

定制 ComboBoxItem 选项样式

<!-- 所有选中项使用特定背景色 -->
<Style Selector="atom|ComboBoxItem:selected">
    <Setter Property="FontWeight" Value="Bold" />
</Style>

<!-- 悬浮态选项样式 -->
<Style Selector="atom|ComboBoxItem:pointerover">
    <Setter Property="Opacity" Value="0.9" />
</Style>

---

3. 通过 ControlTheme 完全替换主题

如果需要彻底替换 ComboBox 的模板和样式，可以定义自定义 ControlTheme：

<ControlTheme x:Key="MyCustomComboBox" TargetType="atom:ComboBox">
    <Setter Property="Template">
        <ControlTemplate>
            <!-- 自定义模板结构 -->
        </ControlTemplate>
    </Setter>
</ControlTheme>

<!-- 使用 -->
<atom:ComboBox Theme="{StaticResource MyCustomComboBox}" />

⚠️ 注意：完全替换 ControlTheme 将丢失内置的 AddOnDecoratedBox 装饰、下拉手柄、动画效果等功能。建议优先使用 Style 覆盖。

---

4. 控制下拉面板行为

<!-- 设置下拉面板可见项数量（默认 10） -->
<atom:ComboBox DropDownDisplayPageSize="5" PlaceholderText="仅显示 5 项" Width="300">
    <atom:ComboBoxItem>选项一</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项二</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项三</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项四</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项五</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项六</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项七</atom:ComboBoxItem>
    <atom:ComboBoxItem>选项八</atom:ComboBoxItem>
</atom:ComboBox>

---

5. 控制动画行为

<!-- 禁用过渡动画（下拉面板不再有展开/收起动画） -->
<atom:ComboBox IsMotionEnabled="False" PlaceholderText="无动画" Width="300">
    <atom:ComboBoxItem>选项一</atom:ComboBoxItem>
</atom:ComboBox>

---

样式选择器速查

说明：Avalonia 样式选择器中使用 atom|ComboBox 语法引用 atom XML 命名空间下的 ComboBox 类型，其中 | 是命名空间分隔符。

按样式变体选择

选择器	说明
atom|ComboBox	匹配所有 AtomUI ComboBox 实例，用于设置全局通用样式（如统一 Width、Margin 等）
atom|ComboBox[StyleVariant=Outline]	匹配描边样式（默认），白色背景 + 实线边框
atom|ComboBox[StyleVariant=Filled]	匹配填充样式，灰色填充背景
atom|ComboBox[StyleVariant=Borderless]	匹配无边框样式，无背景无边框

按尺寸选择

选择器	说明
atom|ComboBox[SizeType=Large]	匹配大号 ComboBox（高度 = ControlHeightLG，字号 = FontSizeLG）
atom|ComboBox[SizeType=Middle]	匹配中号 ComboBox（默认尺寸）
atom|ComboBox[SizeType=Small]	匹配小号 ComboBox（高度 = ControlHeightSM，字号 = FontSizeSM）

按伪类选择

选择器	说明
atom|ComboBox:error	匹配错误验证状态（Status == Error），边框/背景变为红色系
atom|ComboBox:warning	匹配警告验证状态（Status == Warning），边框/背景变为橙色系
atom|ComboBox:pointerover	匹配鼠标悬浮状态
atom|ComboBox:pressed	匹配按下状态
atom|ComboBox:disabled	匹配禁用状态（IsEnabled == false）
atom|ComboBox:focus	匹配获得焦点的状态
atom|ComboBox:focus-visible	匹配通过键盘（Tab 键）获得焦点的状态

ComboBoxItem 选择器

选择器	说明
atom|ComboBoxItem	匹配所有下拉选项
atom|ComboBoxItem:pointerover	匹配鼠标悬浮的选项，背景变为 ItemHoverBgColor
atom|ComboBoxItem:selected	匹配被选中的选项，背景变为 ItemSelectedBgColor，字体加粗
atom|ComboBoxItem:disabled	匹配禁用的选项，文字变为 ColorTextDisabled

组合选择器示例

选择器	说明
atom|ComboBox[StyleVariant=Filled]:error	填充样式 + 错误状态
atom|ComboBox[StyleVariant=Borderless]:warning	无边框样式 + 警告状态
atom|ComboBox[SizeType=Large]:not(:disabled)	非禁用的大号 ComboBox
atom|ComboBox /template/ Border#PopupFrame	访问模板内的弹出框架 Border
atom|ComboBox /template/ atom|AddOnDecoratedBox	访问模板内的 AddOn 装饰容器
atom|ComboBox /template/ ContentPresenter#SelectedContentPresenter	访问模板内的选中内容展示器