AtomUI/docs/Desktop.Controls/OptionButtonGroup/OptionButtonGroupUsage.md

OptionButtonGroup 使用文档

本文档介绍 AtomUI OptionButtonGroup 控件的各种使用方式，示例代码摘自 Gallery 演示程序。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/RadioButtonShowCase.axaml

---

前置准备

在 AXAML 中使用 OptionButtonGroup，需要引入以下命名空间：

xmlns:atom="https://atomui.net"
xmlns:antdicons="https://atomui.net/icons/antdesign"

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // OptionButton, OptionButtonGroup
using AtomUI.Controls;            // SizeType, OptionButtonStyle 等共享类型

---

1. 基本用法（Outline 样式）

默认 Outline 样式的选项按钮组，选中项以边框颜色和文字颜色区分：

<atom:OptionButtonGroup>
    <atom:OptionButton IsChecked="True">Hangzhou</atom:OptionButton>
    <atom:OptionButton>Shanghai</atom:OptionButton>
    <atom:OptionButton>Beijing</atom:OptionButton>
    <atom:OptionButton>Chengdu</atom:OptionButton>
</atom:OptionButtonGroup>

通过 IsChecked="True" 设置默认选中项。

---

2. Solid 样式

通过 ButtonStyle="Solid" 启用实色填充样式，选中项使用主色背景 + 白色文字：

<atom:OptionButtonGroup ButtonStyle="Solid">
    <atom:OptionButton IsChecked="True">Hangzhou</atom:OptionButton>
    <atom:OptionButton>Shanghai</atom:OptionButton>
    <atom:OptionButton>Beijing</atom:OptionButton>
    <atom:OptionButton>Chengdu</atom:OptionButton>
</atom:OptionButtonGroup>

使用场景指引：

• Outline：适合常规选项切换场景，视觉权重较低
• Solid：适合需要强调选中状态的场景（如工具栏模式切换）

---

3. 三种尺寸

通过 SizeType 属性设置尺寸，支持 Large、Middle（默认）、Small 三种：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:OptionButtonGroup SizeType="Large">
        <atom:OptionButton IsChecked="True">Hangzhou</atom:OptionButton>
        <atom:OptionButton>Shanghai</atom:OptionButton>
        <atom:OptionButton>Beijing</atom:OptionButton>
        <atom:OptionButton>Chengdu</atom:OptionButton>
    </atom:OptionButtonGroup>

    <atom:OptionButtonGroup SizeType="Middle">
        <atom:OptionButton IsChecked="True">Hangzhou</atom:OptionButton>
        <atom:OptionButton>Shanghai</atom:OptionButton>
        <atom:OptionButton>Beijing</atom:OptionButton>
        <atom:OptionButton>Chengdu</atom:OptionButton>
    </atom:OptionButtonGroup>

    <atom:OptionButtonGroup SizeType="Small">
        <atom:OptionButton IsChecked="True">Hangzhou</atom:OptionButton>
        <atom:OptionButton>Shanghai</atom:OptionButton>
        <atom:OptionButton>Beijing</atom:OptionButton>
        <atom:OptionButton>Chengdu</atom:OptionButton>
    </atom:OptionButtonGroup>
</StackPanel>

---

4. 带图标的选项按钮

通过 Icon 属性为按钮添加图标，支持图标 + 文字组合：

<!-- Solid 样式 + 图标 -->
<atom:OptionButtonGroup ButtonStyle="Solid">
    <atom:OptionButton IsChecked="True"
        Icon="{antdicons:AntDesignIconProvider Kind=AppleOutlined}">macOS</atom:OptionButton>
    <atom:OptionButton
        Icon="{antdicons:AntDesignIconProvider Kind=LinuxOutlined}">Linux</atom:OptionButton>
    <atom:OptionButton
        Icon="{antdicons:AntDesignIconProvider Kind=WindowsOutlined}">Windows</atom:OptionButton>
</atom:OptionButtonGroup>

<!-- Outline 样式 + 图标 -->
<atom:OptionButtonGroup ButtonStyle="Outline">
    <atom:OptionButton
        Icon="{antdicons:AntDesignIconProvider Kind=AppleOutlined}">macOS</atom:OptionButton>
    <atom:OptionButton IsChecked="True"
        Icon="{antdicons:AntDesignIconProvider Kind=LinuxOutlined}">Linux</atom:OptionButton>
    <atom:OptionButton
        Icon="{antdicons:AntDesignIconProvider Kind=WindowsOutlined}">Windows</atom:OptionButton>
</atom:OptionButtonGroup>

图标与文本之间的间距由 SharedToken.SpacingXXS 控制。

---

5. 不同尺寸的图标按钮

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:OptionButtonGroup ButtonStyle="Outline" SizeType="Large">
        <atom:OptionButton
            Icon="{antdicons:AntDesignIconProvider Kind=AppleOutlined}">macOS</atom:OptionButton>
        <atom:OptionButton IsChecked="True"
            Icon="{antdicons:AntDesignIconProvider Kind=LinuxOutlined}">Linux</atom:OptionButton>
        <atom:OptionButton
            Icon="{antdicons:AntDesignIconProvider Kind=WindowsOutlined}">Windows</atom:OptionButton>
    </atom:OptionButtonGroup>

    <atom:OptionButtonGroup ButtonStyle="Outline">
        <atom:OptionButton
            Icon="{antdicons:AntDesignIconProvider Kind=AppleOutlined}">macOS</atom:OptionButton>
        <atom:OptionButton IsChecked="True"
            Icon="{antdicons:AntDesignIconProvider Kind=LinuxOutlined}">Linux</atom:OptionButton>
        <atom:OptionButton
            Icon="{antdicons:AntDesignIconProvider Kind=WindowsOutlined}">Windows</atom:OptionButton>
    </atom:OptionButtonGroup>

    <atom:OptionButtonGroup ButtonStyle="Outline" SizeType="Small">
        <atom:OptionButton
            Icon="{antdicons:AntDesignIconProvider Kind=AppleOutlined}">macOS</atom:OptionButton>
        <atom:OptionButton IsChecked="True"
            Icon="{antdicons:AntDesignIconProvider Kind=LinuxOutlined}">Linux</atom:OptionButton>
        <atom:OptionButton
            Icon="{antdicons:AntDesignIconProvider Kind=WindowsOutlined}">Windows</atom:OptionButton>
    </atom:OptionButtonGroup>
</StackPanel>

---

6. 禁用状态

禁用单个选项

<atom:OptionButtonGroup ButtonStyle="Outline">
    <atom:OptionButton>Apple</atom:OptionButton>
    <atom:OptionButton IsChecked="True">Pear</atom:OptionButton>
    <atom:OptionButton IsEnabled="False">Orange</atom:OptionButton>
</atom:OptionButtonGroup>

禁用的选项显示为灰色调，不可点击。已选中的选项也可以被禁用。

禁用整个组

<!-- Solid 样式全组禁用 -->
<atom:OptionButtonGroup ButtonStyle="Solid" IsEnabled="False">
    <atom:OptionButton IsChecked="True"
        Icon="{antdicons:AntDesignIconProvider Kind=AppleOutlined}">macOS</atom:OptionButton>
    <atom:OptionButton
        Icon="{antdicons:AntDesignIconProvider Kind=LinuxOutlined}">Linux</atom:OptionButton>
    <atom:OptionButton
        Icon="{antdicons:AntDesignIconProvider Kind=WindowsOutlined}">Windows</atom:OptionButton>
</atom:OptionButtonGroup>

<!-- Outline 样式全组禁用 -->
<atom:OptionButtonGroup ButtonStyle="Outline" IsEnabled="False">
    <atom:OptionButton
        Icon="{antdicons:AntDesignIconProvider Kind=AppleOutlined}">macOS</atom:OptionButton>
    <atom:OptionButton IsChecked="True"
        Icon="{antdicons:AntDesignIconProvider Kind=LinuxOutlined}">Linux</atom:OptionButton>
    <atom:OptionButton
        Icon="{antdicons:AntDesignIconProvider Kind=WindowsOutlined}">Windows</atom:OptionButton>
</atom:OptionButtonGroup>

选中项被禁用

<atom:OptionButtonGroup>
    <atom:OptionButton IsChecked="True" IsEnabled="False">Hangzhou</atom:OptionButton>
    <atom:OptionButton IsEnabled="False">Shanghai</atom:OptionButton>
    <atom:OptionButton IsEnabled="False">Beijing</atom:OptionButton>
    <atom:OptionButton IsEnabled="False">Chengdu</atom:OptionButton>
</atom:OptionButtonGroup>

---

7. 选中变更事件

通过 OptionCheckedChanged 事件监听选中项变更：

<atom:OptionButtonGroup ButtonStyle="Outline"
                         OptionCheckedChanged="HandleSizeTypeChanged">
    <atom:OptionButton IsChecked="True">Default</atom:OptionButton>
    <atom:OptionButton>Large</atom:OptionButton>
    <atom:OptionButton>Small</atom:OptionButton>
</atom:OptionButtonGroup>

private void HandleSizeTypeChanged(object? sender, OptionCheckedChangedEventArgs e)
{
    // e.CheckedOption — 新选中的按钮实例
    // e.Index — 新选中项的索引
    var selectedText = e.CheckedOption.Content?.ToString();
    // 根据选中项执行相应逻辑...
}

📖 参考：controlgallery/AtomUIGallery/ShowCases/Views/Feedback/SkeletonShowCase.axaml 中使用 OptionButtonGroup 切换 Skeleton 尺寸。

---

8. 数据驱动模式

通过 ItemsSource 绑定数据集合自动生成按钮：

// ViewModel 或 Code-behind
var items = new List<OptionButtonData>
{
    new() { Header = "Apple", Icon = new AppleOutlined() },
    new() { Header = "Linux", Icon = new LinuxOutlined() },
    new() { Header = "Windows", Icon = new WindowsOutlined(), IsEnabled = false }
};
optionButtonGroup.ItemsSource = items;

<atom:OptionButtonGroup Name="optionButtonGroup"
                         ButtonStyle="Solid" />

---

常见组合模式

作为视图模式切换器

<atom:OptionButtonGroup ButtonStyle="Solid" SizeType="Small">
    <atom:OptionButton IsChecked="True"
        Icon="{antdicons:AntDesignIconProvider Kind=AppstoreOutlined}" />
    <atom:OptionButton
        Icon="{antdicons:AntDesignIconProvider Kind=UnorderedListOutlined}" />
</atom:OptionButtonGroup>

作为 Skeleton 尺寸切换器

<atom:OptionButtonGroup ButtonStyle="Outline"
                         OptionCheckedChanged="HandleSizeTypeChanged">
    <atom:OptionButton IsChecked="True">Default</atom:OptionButton>
    <atom:OptionButton>Large</atom:OptionButton>
    <atom:OptionButton>Small</atom:OptionButton>
</atom:OptionButtonGroup>

作为折叠面板展开按钮位置切换器

<atom:OptionButtonGroup ButtonStyle="Outline" Name="ExpandButtonPosGroup">
    <atom:OptionButton IsChecked="True">Start</atom:OptionButton>
    <atom:OptionButton>End</atom:OptionButton>
</atom:OptionButtonGroup>

与表单集成

<atom:FormItem Label="Region">
    <atom:OptionButtonGroup>
        <atom:OptionButton IsChecked="True">China</atom:OptionButton>
        <atom:OptionButton>USA</atom:OptionButton>
        <atom:OptionButton>EU</atom:OptionButton>
    </atom:OptionButtonGroup>
</atom:FormItem>

MVVM 绑定选中项

<atom:OptionButtonGroup SelectedItem="{Binding SelectedRegion}">
    <atom:OptionButton>China</atom:OptionButton>
    <atom:OptionButton>USA</atom:OptionButton>
    <atom:OptionButton>EU</atom:OptionButton>
</atom:OptionButtonGroup>

// ViewModel
[Reactive]
public object? SelectedRegion { get; set; }