syncfusion-winforms-checkbox

在 Windows Forms 中实现 CheckBoxAdv

何时使用此技能

在用户需要执行以下操作时使用此技能：

• 在 Windows Forms 应用程序中实现高级复选框控件
• 创建具有选中、未选中和不确定状态的复选框
• 为复选框应用渐变背景、自定义边框或阴影文本
• 独立配置复选框和文本的对齐方式
• 将整数值或字符串值与复选框状态关联
• 处理复选框状态更改事件
• 将 CheckBoxAdv 控件绑定到 SQL 数据库字段
• 自定义复选框外观，使其超越标准 Windows Forms 控件的效果
• 实现支持三态的复选框
• 创建只读或自动调整大小的复选框控件

组件概述

CheckBoxAdv 是一种适用于 Windows Forms 的高级复选框控件，在标准 CheckBox 的基础上扩展了更丰富的视觉和功能特性。它支持渐变背景、自定义边框（2D 和 3D）、阴影文本、文本和复选框独立对齐、图像复选框以及全面的数据绑定选项。

主要功能

• 三种状态：选中、未选中和不确定，支持三态模式
• 值关联：为每种状态绑定整数值和字符串值
• 外观自定义：渐变背景、自定义边框、阴影文本
• 灵活对齐：独立设置文本和复选框的位置
• 数据绑定：通过 BoolValue 和 IntValue 属性连接 SQL 数据库
• 事件处理：响应 CheckStateChanged 和 CheckedChanged 事件
• 行为控制：提供 AutoHeight、ReadOnlyMode 和焦点矩形选项

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和 NuGet 包
• 通过设计器添加 CheckBoxAdv
• 以编程方式添加 CheckBoxAdv
• 所需的命名空间（Syncfusion.Windows.Forms.Tools）
• 基本初始化和设置
• 设置复选框的初始状态

状态和配置

📄 阅读： references/states-and-values.md

• CheckState 属性（Checked、Unchecked、Indeterminate）
• 用于设置布尔状态的 Checked 属性
• 用于启用三态模式的 Tristate 属性
• 将整数值与状态关联（CheckedInt、UncheckedInt、IndeterminateInt）
• 将字符串值与状态关联（CheckedString、UncheckedString、IndeterminateString）
• 使用 BoolValue、IntValue 和 StringValue 属性
• 各类值的适用场景

文本和对齐

📄 阅读： references/text-and-alignment.md

• 文本阴影效果（TextShadow、ShadowColor、ShadowOffset）
• 使用 WrapText 属性换行文本
• 文本对齐选项（TextContentAlignment）
• 复选框对齐选项（CheckAlign）
• 位置选项（TopLeft、MiddleCenter、BottomRight 等）
• 组合设置文本和复选框的对齐方式

外观和行为

📄 阅读： references/appearance-and-behavior.md

• 焦点矩形的可见性（DrawFocusRectangle）
• 自动计算高度（AutoHeight）
• 只读模式（ReadOnlyMode）
• 渐变背景（BackgroundStyle、GradientStart、GradientEnd）
• 边框样式（Border3DStyle、BorderStyle、BorderSingle）
• 边框颜色（BorderColor、HotBorderColor）
• 鼠标悬停效果

事件和交互

📄 阅读： references/events.md

• CheckStateChanged 事件
• CheckedChanged 事件
• 事件处理程序模式
• 响应状态变化
• 事件触发时机和顺序
• 事件处理最佳实践

数据绑定

📄 阅读： references/data-binding.md

• 绑定到 SQL 数据库
• 用于 bit/布尔字段的 BoolValue 属性
• 用于整数型字段的 IntValue 属性
• SqlDataAdapter 和 DataTable 的用法
• 连接字符串配置
• 常见数据绑定模式
• 数据绑定问题排查

快速入门示例

using Syncfusion.Windows.Forms.Tools;

// Create CheckBoxAdv instance
CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Enable Feature";
checkBoxAdv1.Size = new Size(150, 25);
checkBoxAdv1.Location = new Point(20, 20);

// Set initial state
checkBoxAdv1.Checked = true;

// Add to form
this.Controls.Add(checkBoxAdv1);

// Handle state changes
checkBoxAdv1.CheckedChanged += (sender, e) => {
    MessageBox.Show($"Checkbox is now: {checkBoxAdv1.Checked}");
};

常见模式

模式 1：三态复选框

当用户需要具有选中、未选中和不确定状态的复选框时：

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Select All";
checkBoxAdv1.Tristate = true;
checkBoxAdv1.CheckState = CheckState.Indeterminate;

checkBoxAdv1.CheckStateChanged += (sender, e) => {
    switch(checkBoxAdv1.CheckState) {
        case CheckState.Checked:
            // Select all items
            break;
        case CheckState.Unchecked:
            // Deselect all items
            break;
        case CheckState.Indeterminate:
            // Partial selection
            break;
    }
};

模式 2：自定义样式复选框

当用户需要具有渐变背景和边框、视觉效果更丰富的复选框时：

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Styled Checkbox";

// Gradient background
checkBoxAdv1.BackgroundStyle = CheckBoxAdvBackStyle.HorizontalGradient;
checkBoxAdv1.GradientStart = Color.LightBlue;
checkBoxAdv1.GradientEnd = Color.DarkBlue;

// Custom border
checkBoxAdv1.BorderStyle = BorderStyle.FixedSingle;
checkBoxAdv1.BorderColor = Color.Navy;
checkBoxAdv1.HotBorderColor = Color.Red; // On mouse hover

// Shadow text
checkBoxAdv1.TextShadow = true;
checkBoxAdv1.ShadowColor = Color.Gray;
checkBoxAdv1.ShadowOffset = new Point(2, 2);

模式 3：数据绑定复选框

当用户需要将复选框绑定到数据库字段时：

// For boolean/bit fields
using (SqlConnection conn = new SqlConnection(connectionString)) {
    conn.Open();
    SqlDataAdapter adapter = new SqlDataAdapter("SELECT * FROM Settings", conn);
    DataTable dataTable = new DataTable();
    adapter.Fill(dataTable);
    
    checkBoxAdv1.DataBindings.Add("BoolValue", dataTable, "IsEnabled");
}

// For integer fields (values: -1, 0, 1)
checkBoxAdv1.DataBindings.Add("IntValue", dataTable, "StatusCode");

模式 4：只读复选框显示

当用户需要显示复选框状态但不允许用户更改时：

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Read-Only Status";
checkBoxAdv1.Checked = true;
checkBoxAdv1.ReadOnlyMode = true;
checkBoxAdv1.DrawFocusRectangle = false;

主要属性

状态属性

• Checked (bool)：获取或设置选中状态（true/false）
• CheckState (CheckState)：获取或设置状态（Checked、Unchecked、Indeterminate）
• Tristate (bool)：启用三态模式，允许用户选择不确定状态

值属性

• BoolValue (bool)：状态的布尔表示形式（用于数据绑定）
• IntValue (int)：状态的整数表示形式
• StringValue (string)：当前状态的字符串表示形式
• CheckedInt/UncheckedInt/IndeterminateInt (int)：每种状态对应的整数值
• CheckedString/UncheckedString/IndeterminateString (string)：每种状态对应的字符串值

外观属性

• BackgroundStyle (CheckBoxAdvBackStyle)：背景样式（Default、HorizontalGradient、VerticalGradient）
• GradientStart/GradientEnd (Color)：渐变颜色
• BorderStyle (BorderStyle)：边框样式（FixedSingle、Fixed3D、None）
• BorderColor/HotBorderColor (Color)：边框颜色
• TextShadow (bool)：启用文本阴影
• DrawFocusRectangle (bool)：显示焦点矩形

对齐属性

• TextContentAlignment (ContentAlignment)：文本位置
• CheckAlign (ContentAlignment)：复选框位置

行为属性

• AutoHeight (bool)：自动计算高度
• ReadOnlyMode (bool)：禁止用户交互
• WrapText (bool)：启用文本换行

常见用例

用例 1：设置对话框

为应用程序设置创建可持久保存状态的复选框：

• 简单的开/关设置使用 BoolValue
• 直接绑定到配置数据库
• 处理 CheckedChanged 事件，立即保存设置

用例 2：列表项选择

使用不确定状态实现“全选”：

• 使用 Tristate 属性实现三态行为
• 部分选中时使用 CheckState.Indeterminate
• 根据子项的选择情况更新状态

用例 3：表单验证

创建只读复选框以显示验证状态：

• 设置 ReadOnlyMode = true
• 以编程方式更新 Checked 状态
• 使用自定义颜色指示状态

用例 4：增强 UI 设计

构建与应用程序主题一致、视觉效果丰富的复选框：

• 应用渐变背景
• 配置自定义边框和悬停效果
• 添加文本阴影以增强立体感
• 分别设置文本和复选框的位置

用例 5：数据录入表单

将复选框绑定到数据库记录：

• 状态代码使用 IntValue（0、1 或 -1）
• 是/否字段使用 BoolValue
• 为各状态关联自定义整数值或字符串值