AtomUI/docs/Desktop.Controls/RadioButton/RadioButtonUsage.md

RadioButton 使用文档

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

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

---

前置准备

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

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

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // RadioButton, RadioButtonGroup
using AtomUI.Controls;            // RadioButtonOption, IRadioButtonOption

---

1. 基本用法

最简单的单选框使用方式：

<atom:RadioButton>Radio</atom:RadioButton>

两个单选框互斥（默认选中一个）：

<StackPanel Orientation="Horizontal">
    <atom:RadioButton>Option A</atom:RadioButton>
    <atom:RadioButton IsChecked="True">Option B</atom:RadioButton>
</StackPanel>

---

2. 禁用状态

通过 IsEnabled="False" 禁用单选框：

<StackPanel Orientation="Vertical">
    <StackPanel Orientation="Horizontal">
        <atom:RadioButton x:Name="ToggleDisabledRadioUnChecked">Radio1</atom:RadioButton>
        <atom:RadioButton x:Name="ToggleDisabledRadioChecked" IsChecked="True">Radio2</atom:RadioButton>
    </StackPanel>
    <atom:Button ButtonType="Primary"
                 Margin="0, 20, 0, 0"
                 Click="ToggleDisabledStatus">
        toggle disabled
    </atom:Button>
</StackPanel>

public void ToggleDisabledStatus(object? sender, RoutedEventArgs args)
{
    ToggleDisabledRadioUnChecked.IsEnabled = !ToggleDisabledRadioUnChecked.IsEnabled;
    ToggleDisabledRadioChecked.IsEnabled   = !ToggleDisabledRadioChecked.IsEnabled;
}

禁用时的视觉变化：

• 文本变为 ColorTextDisabled（灰色）
• 指示器背景变为 ColorBgContainerDisabled（灰色背景）
• 如果选中，圆点变为 DotColorDisabled（灰色圆点）
• 不可点击，鼠标样式不会变为手型

📖 参考：Gallery 中 "Disabled" 示例。

---

3. 单选框组（RadioButtonGroup）

声明式用法

直接在 AXAML 中声明 RadioButton 子元素：

<!-- 水平排列（默认） -->
<atom:RadioButtonGroup>
    <atom:RadioButton>Option A</atom:RadioButton>
    <atom:RadioButton>Option B</atom:RadioButton>
    <atom:RadioButton>Option C</atom:RadioButton>
</atom:RadioButtonGroup>

垂直排列

<atom:RadioButtonGroup Orientation="Vertical" HorizontalAlignment="Left">
    <atom:RadioButton>Option A</atom:RadioButton>
    <atom:RadioButton>Option B</atom:RadioButton>
    <atom:RadioButton>Option C</atom:RadioButton>
    <atom:RadioButton>Option D</atom:RadioButton>
</atom:RadioButtonGroup>

自定义内容（图标 + 文字）

RadioButton 的 Content 属性接受任意控件，可以用来创建带图标的选项：

<atom:RadioButtonGroup>
    <atom:RadioButton>
        <StackPanel Spacing="5" Orientation="Vertical">
            <antdicons:LineChartOutlined Width="18" Height="18" />
            <TextBlock>LineChart</TextBlock>
        </StackPanel>
    </atom:RadioButton>
    <atom:RadioButton>
        <StackPanel Spacing="5" Orientation="Vertical">
            <antdicons:DotChartOutlined Width="18" Height="18" />
            <TextBlock>DotChart</TextBlock>
        </StackPanel>
    </atom:RadioButton>
    <atom:RadioButton>
        <StackPanel Spacing="5" Orientation="Vertical">
            <antdicons:BarChartOutlined Width="18" Height="18" />
            <TextBlock>BarChart</TextBlock>
        </StackPanel>
    </atom:RadioButton>
    <atom:RadioButton>
        <StackPanel Spacing="5" Orientation="Vertical">
            <antdicons:PieChartOutlined Width="18" Height="18" />
            <TextBlock>PieChart</TextBlock>
        </StackPanel>
    </atom:RadioButton>
</atom:RadioButtonGroup>

📖 参考：Gallery 中 "Radio Group" 示例。

数据驱动用法

通过 ItemsSource 绑定 IRadioButtonOption 集合，动态生成子项：

<atom:RadioButtonGroup Name="RadioButtonGroup" HorizontalAlignment="Left" />

// Code-behind 或 ViewModel
var options = new List<RadioButtonOption>
{
    new() { Content = "Option A" },
    new() { Content = "Option B", IsChecked = true },
    new() { Content = "Option C" },
    new() { Content = "Option D", IsEnabled = false },
};
RadioButtonGroup.ItemsSource = options;

使用 ReactiveUI 数据绑定模式：

this.OneWayBind(ViewModel, vm => vm.RadioOptions, v => v.RadioButtonGroup.ItemsSource)
    .DisposeWith(disposables);

📖 参考：Gallery 中 "Radio Group by Items source" 示例 及 RadioButtonShowCase.axaml.cs。

监听选中变化

// 声明式用法 — CheckedItem 返回 RadioButton 实例
RadioButtonGroup.CheckedChanged += (sender, args) =>
{
    if (args.NewCheckedItem is RadioButton radioButton)
    {
        Console.WriteLine($"Selected: {radioButton.Content}");
    }
};

// 数据驱动用法 — CheckedItem 返回数据对象
RadioButtonGroup.CheckedChanged += (sender, args) =>
{
    if (args.NewCheckedItem is RadioButtonOption option)
    {
        Console.WriteLine($"Selected: {option.Content}");
    }
};

---

4. 按钮样式单选框（OptionButtonGroup）

Ant Design 的 Radio.Button 在 AtomUI 中通过 OptionButtonGroup + OptionButton 实现：

Outline 样式（默认）

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

Solid 填充样式

<atom:OptionButtonGroup ButtonStyle="Solid">
    <atom:OptionButton IsChecked="True">Apple</atom:OptionButton>
    <atom:OptionButton>Pear</atom:OptionButton>
    <atom:OptionButton>Orange</atom:OptionButton>
</atom:OptionButtonGroup>

带图标的按钮样式

<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>

三种尺寸

<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>

禁用状态

<!-- 部分禁用 -->
<atom:OptionButtonGroup>
    <atom:OptionButton IsChecked="True">Hangzhou</atom:OptionButton>
    <atom:OptionButton IsEnabled="False">Shanghai</atom:OptionButton>
    <atom:OptionButton>Beijing</atom:OptionButton>
</atom:OptionButtonGroup>

<!-- 整组禁用 -->
<atom:OptionButtonGroup ButtonStyle="Solid" IsEnabled="False">
    <atom:OptionButton IsChecked="True">macOS</atom:OptionButton>
    <atom:OptionButton>Linux</atom:OptionButton>
    <atom:OptionButton>Windows</atom:OptionButton>
</atom:OptionButtonGroup>

📖 参考：Gallery 中 "Option Button"、"Option Button with icon"、"option style"、"Solid option button"、"Size type" 示例。

---

5. 控制动画行为

<!-- 禁用选中波纹效果 -->
<atom:RadioButton IsWaveSpiritEnabled="False">No Wave</atom:RadioButton>

<!-- 禁用过渡动画 -->
<atom:RadioButton IsMotionEnabled="False">No Animation</atom:RadioButton>

<!-- 通过组统一禁用动画（传递给所有子项） -->
<atom:RadioButtonGroup IsMotionEnabled="False">
    <atom:RadioButton>A</atom:RadioButton>
    <atom:RadioButton>B</atom:RadioButton>
</atom:RadioButtonGroup>

---

常见组合模式

表单中使用

<atom:FormItem Label="性别">
    <atom:RadioButtonGroup>
        <atom:RadioButton>男</atom:RadioButton>
        <atom:RadioButton>女</atom:RadioButton>
        <atom:RadioButton>其他</atom:RadioButton>
    </atom:RadioButtonGroup>
</atom:FormItem>

切换视图模式

使用按钮样式单选框在几种模式间切换：

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

MVVM 数据绑定

<atom:RadioButtonGroup CheckedItem="{Binding SelectedOption, Mode=TwoWay}">
    <atom:RadioButton>Option A</atom:RadioButton>
    <atom:RadioButton>Option B</atom:RadioButton>
    <atom:RadioButton>Option C</atom:RadioButton>
</atom:RadioButtonGroup>

混合禁用项

<StackPanel Orientation="Horizontal" HorizontalAlignment="Left">
    <atom:RadioButton IsChecked="True">Apple</atom:RadioButton>
    <atom:RadioButton>Pear</atom:RadioButton>
    <atom:RadioButton IsEnabled="False">Orange</atom:RadioButton>
</StackPanel>

📖 参考：Gallery 中 "Option Button" 示例中的第二个 StackPanel。