AtomUI/docs/Desktop.Controls/CheckBox/CheckBoxUsage.md

CheckBox 使用文档

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

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

---

前置准备

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

xmlns:atom="https://atomui.net"

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // CheckBox, CheckBoxGroup
using AtomUI.Controls;            // CheckBoxOption, ICheckBoxOption

---

1. 基本用法

最简单的复选框，通过 Content 设置标签文本：

<atom:CheckBox>Checkbox</atom:CheckBox>

---

2. 禁用状态

通过 IsEnabled="False" 禁用复选框，三种状态均支持禁用：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:CheckBox IsChecked="False" IsEnabled="False">UnChecked</atom:CheckBox>
    <atom:CheckBox IsChecked="{x:Null}" IsEnabled="False">Indeterminate</atom:CheckBox>
    <atom:CheckBox IsChecked="True" IsEnabled="False">Checked</atom:CheckBox>
</StackPanel>

---

3. 受控复选框

通过数据绑定控制复选框状态：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:CheckBox IsChecked="{Binding ControlledCheckBoxCheckedStatus}"
                   IsEnabled="{Binding ControlledCheckBoxEnabledStatus}"
                   Content="{Binding ControlledCheckBoxText}" />
    <StackPanel Orientation="Horizontal" Spacing="10">
        <atom:Button SizeType="Small" ButtonType="Primary"
                     Content="{Binding CheckStatusBtnText}" />
        <atom:Button SizeType="Small" ButtonType="Primary"
                     Content="{Binding EnableStatusBtnText}" />
    </StackPanel>
</StackPanel>

---

4. 复选框组

声明式用法

直接在 CheckBoxGroup 中添加 CheckBox 子项：

<!-- 默认全选 -->
<atom:CheckBoxGroup>
    <atom:CheckBox IsChecked="True">Apple</atom:CheckBox>
    <atom:CheckBox IsChecked="True">Pear</atom:CheckBox>
    <atom:CheckBox IsChecked="True">Orange</atom:CheckBox>
</atom:CheckBoxGroup>

<!-- 部分选中 -->
<atom:CheckBoxGroup>
    <atom:CheckBox>Apple</atom:CheckBox>
    <atom:CheckBox IsChecked="True">Pear</atom:CheckBox>
    <atom:CheckBox>Orange</atom:CheckBox>
</atom:CheckBoxGroup>

<!-- 部分禁用 -->
<atom:CheckBoxGroup>
    <atom:CheckBox IsChecked="True" IsEnabled="False">Apple</atom:CheckBox>
    <atom:CheckBox IsEnabled="False">Pear</atom:CheckBox>
    <atom:CheckBox IsEnabled="False">Orange</atom:CheckBox>
</atom:CheckBoxGroup>

数据驱动用法

通过 ItemsSource 绑定 ICheckBoxOption 集合：

// ViewModel 或 Code-behind
var options = new List<CheckBoxOption>
{
    new() { Content = "Apple", IsChecked = true },
    new() { Content = "Pear" },
    new() { Content = "Orange" }
};
BasicCheckBoxGroup.ItemsSource = options;

---

5. 全选/部分选联动

通过 Indeterminate 不确定态实现全选联动效果：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:CheckBox Name="CheckAllCheckbox"
                   IsChecked="{Binding CheckedAllStatus}">
        Check all
    </atom:CheckBox>
    <WrapPanel Margin="0,20,0,0">
        <atom:CheckBox IsChecked="{Binding AppleCheckedStatus}">Apple</atom:CheckBox>
        <atom:CheckBox IsChecked="{Binding PearCheckedStatus}">Pear</atom:CheckBox>
        <atom:CheckBox IsChecked="{Binding OrangeCheckedStatus}">Orange</atom:CheckBox>
    </WrapPanel>
</StackPanel>

实现逻辑：

• 全选框的 IsChecked 绑定到 ViewModel 的计算属性
• 当所有子项选中时，全选框为 true
• 当部分子项选中时，全选框为 null（不确定态，显示横杠）
• 当没有子项选中时，全选框为 false
• 点击全选框时，全部子项同步切换

---

6. Grid 布局中使用

利用 Grid 实现复杂的复选框布局：

<Grid ColumnDefinitions="*,*,*" RowDefinitions="Auto,Auto" Margin="10">
    <atom:CheckBox Grid.Row="0" Grid.Column="0">A</atom:CheckBox>
    <atom:CheckBox Grid.Row="0" Grid.Column="1">B</atom:CheckBox>
    <atom:CheckBox Grid.Row="0" Grid.Column="2">C</atom:CheckBox>
    <atom:CheckBox Grid.Row="1" Grid.Column="0">D</atom:CheckBox>
    <atom:CheckBox Grid.Row="1" Grid.Column="1">E</atom:CheckBox>
</Grid>

---

7. MVVM 命令绑定

CheckBox 继承自 Button，完整支持 Command 绑定：

<atom:CheckBox Command="{Binding ToggleOptionCommand}"
               CommandParameter="newsletter">
    Subscribe to newsletter
</atom:CheckBox>

---

8. 控制动画行为

<!-- 禁用点击波纹效果 -->
<atom:CheckBox IsWaveSpiritEnabled="False">No Wave</atom:CheckBox>

---

常见组合模式

设置选项列表

<StackPanel Spacing="8">
    <atom:TextBlock Text="Notification Preferences" FontWeight="Bold" />
    <atom:CheckBox IsChecked="True">Email notifications</atom:CheckBox>
    <atom:CheckBox IsChecked="True">Push notifications</atom:CheckBox>
    <atom:CheckBox>SMS notifications</atom:CheckBox>
</StackPanel>

表单中使用

<atom:FormItem Label="Interests">
    <atom:CheckBoxGroup>
        <atom:CheckBox>Music</atom:CheckBox>
        <atom:CheckBox>Sports</atom:CheckBox>
        <atom:CheckBox>Reading</atom:CheckBox>
        <atom:CheckBox>Travel</atom:CheckBox>
    </atom:CheckBoxGroup>
</atom:FormItem>

协议确认

<StackPanel Orientation="Horizontal" Spacing="8">
    <atom:CheckBox Name="AgreeCheckBox">
        I have read and agree to the
    </atom:CheckBox>
    <atom:Button ButtonType="Link" Padding="0">Terms of Service</atom:Button>
</StackPanel>
<atom:Button ButtonType="Primary"
             IsEnabled="{Binding #AgreeCheckBox.IsChecked}">
    Submit
</atom:Button>