第5章：可视化组件（一）——Button、CheckBox、RadioButton、Slider、ProgressBar、TextField

本章导览

本章将深入讲解QT Quick中6种最基础且常用的可视化组件，它们是构建交互式UI的核心基石。我们会从每个组件的属性、信号、方法及适用场景入手，结合QML代码示例，帮你快速掌握其使用精髓。

QT Quick基础可视化组件家族——用户交互与数据展示的核心

本章涉及的6个核心组件各有明确定位：

• Button：触发即时动作，核心特性包括显示文本text、点击信号clicked、可配置图标；
• CheckBox：支持多项选择，具备选中状态checked，还可启用三态模式；
• RadioButton：用于互斥单项选择，通过分组实现选项间的互斥；
• Slider：在指定范围内选择数值，核心属性含当前值value、范围from/to、步进stepSize；
• ProgressBar：展示任务完成进度，支持确定进度与不确定等待两种模式；
• TextField：接收单行文本输入，可配置提示文本、密码掩码及输入验证器。

组件深度解析与示例

Button（按钮）

描述：最基础的交互组件，用于响应用户点击，触发提交表单、执行操作等特定功能。

核心属性：

• text：按钮上显示的文本内容；
• icon.source：按钮图标的文件路径；
• enabled：控制按钮是否可用，禁用状态下用户无法点击。

核心信号：clicked()——按钮被点击时触发。

import QtQuick 2.15
import QtQuick.Controls 2.15

Button {
    id: myButton
    text: "点击我！"
    width: 150
    height: 50
    // 自定义样式：实现点击、 hover时的颜色变化
    background: Rectangle {
        color: myButton.down ? "#CCCCCC" : (myButton.hovered ? "#E0E0E0" : "#F5F5F5")
        border.color: "#2196F3"
        radius: 8
    }
    onClicked: {
        console.log("按钮被点击了！");
        // 在此添加业务逻辑，如弹窗、数据提交等
    }
}

CheckBox（复选框）

描述：允许用户从一组选项中选择多个或全不选，代表选中/未选中的二进制状态；开启三态模式后支持半选状态，适合批量选择子项的场景。

核心属性：

• checked：布尔值，标记是否被选中；
• text：复选框旁的标签文本；
• tristate：布尔值，启用后支持checked、unchecked、partiallyChecked三种状态。

核心信号：checkStateChanged()——选中状态改变时触发。

CheckBox {
    id: agreeCheckBox
    text: "我同意用户协议"
    checked: false
    // 如需三态模式，取消下方注释
    // tristate: true
    onCheckStateChanged: {
        if (checked) {
            console.log("用户已同意协议");
            myButton.enabled = true; // 启用提交按钮
        } else {
            console.log("用户未同意协议");
            myButton.enabled = false; // 禁用提交按钮
        }
    }
}

RadioButton（单选按钮）

描述：用于在一组互斥选项中选择唯一答案，必须通过分组确保选项间的互斥性。

核心属性：

• checked：布尔值，标记是否被选中；
• text：单选按钮旁的标签文本；
• exclusiveGroup（QtQuick.Controls 1.x）：指定互斥分组（2.x推荐用ButtonGroup）。

核心信号：toggled()——选中状态切换时触发。

// 方法1：使用Column/Row自然分组（隐式互斥，适合简单布局）
Column {
    spacing: 10
    RadioButton { text: "选项 A"; checked: true }
    RadioButton { text: "选项 B" }
    RadioButton { text: "选项 C" }
}

// 方法2：使用ButtonGroup（显式分组，更灵活，支持分散布局的单选按钮）
ButtonGroup {
    id: colorGroup
    buttons: colorColumn.children
}
Column {
    id: colorColumn
    RadioButton { text: "红色" }
    RadioButton { text: "绿色"; checked: true }
    RadioButton { text: "蓝色" }
}

Slider（滑块）

描述：允许用户通过拖动滑块在连续或离散范围内选择数值，常用于音量调节、亮度设置等场景。

核心属性：

• value：当前选中的数值；
• from、to：定义数值的最小与最大值范围；
• stepSize：拖动时的步进值，控制数值变化的粒度；
• orientation：滑块方向，可选Qt.Horizontal（水平）或Qt.Vertical（垂直）。

核心信号：valueChanged()——数值改变时触发。

Slider {
    id: volumeSlider
    from: 0.0
    to: 1.0
    value: 0.5
    stepSize: 0.05
    width: 200
    // 实时显示当前音量百分比
    onValueChanged: {
        volumeText.text = "音量: " + Math.round(value * 100) + "%";
        // 实际应用中可在此调用音频API设置音量
    }
}
Text {
    id: volumeText
    text: "音量: 50%"
    anchors.top: volumeSlider.bottom
}

ProgressBar（进度条）

描述：向用户展示耗时任务的完成进度，或表示不确定时长的等待状态，是提升用户体验的重要反馈组件。

核心属性：

• value、from、to：定义进度的当前值与范围；
• indeterminate：布尔值，设为true时显示动画化的不确定进度。

提示：ProgressBar通常由后台逻辑驱动更新value，而Slider由用户交互直接控制。

// 确定进度模式（模拟下载进度）
ProgressBar {
    id: downloadProgress
    from: 0
    to: 100
    value: 0 // 初始进度为0
    width: 300
    // 用计时器模拟下载进度更新
    Timer {
        interval: 200
        running: true
        repeat: true
        onTriggered: {
            if (downloadProgress.value < 100) {
                downloadProgress.value += 2;
            }
        }
    }
}

// 不确定进度模式（用于等待未知时长的任务，如网络请求）
ProgressBar {
    indeterminate: true
    visible: someBusyCondition // 根据业务条件控制显示
}

TextField（文本输入框）

描述：接收用户单行文本输入，适用于用户名、密码、搜索关键词等场景，支持输入验证与密码掩码。

核心属性：

• text：输入框内的文本内容；
• placeholderText：输入为空时显示的提示文本（水印）；
• echoMode：文本显示模式，可选Normal（正常显示）、Password（密码掩码）、NoEcho（不显示）；
• validator：输入验证器，如IntValidator（整数验证）、RegExpValidator（正则验证）等，限制输入内容格式。

核心信号：editingFinished()——编辑完成（焦点移出输入框）时触发。

// 用户名输入框（限制字母数字）
TextField {
    id: usernameField
    width: 200
    placeholderText: "请输入用户名"
    // 正则验证：只允许字母和数字
    validator: RegExpValidator { regExp: /[a-zA-Z0-9]+/ }
    onEditingFinished: {
        console.log("输入的用户名是：", text);
        // 可在此执行用户名查重、格式校验等操作
    }
}

// 密码输入框（掩码显示）
TextField {
    id: passwordField
    width: 200
    placeholderText: "请输入密码"
    echoMode: TextInput.Password // 用圆点掩码密码
    // 可搭配Button实现密码显示/隐藏切换功能
}

综合实践：一个简单的应用设置面板

我们将上述组件组合，打造一个模拟“应用设置”面板，展示组件间的协同工作方式：

import QtQuick 2.15
import QtQuick.Controls 2.15
import QtQuick.Layouts 1.15

Rectangle {
    width: 400
    height: 500
    color: "#F5F5F5"
    border.color: "#CCCCCC"
    radius: 10

    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 15

        // 标题
        Text { text: "应用程序设置"; font.bold: true; font.pixelSize: 20; Layout.alignment: Qt.AlignHCenter }

        // 1. 用户名输入区域
        Text { text: "用户名:" }
        TextField {
            id: username
            Layout.fillWidth: true
            placeholderText: "输入新用户名"
        }

        // 2. 通知选项（多选）
        Text { text: "通知设置:" }
        CheckBox { text: "启用声音通知"; checked: true }
        CheckBox { text: "显示桌面提醒" }
        CheckBox { text: "邮件通知" }

        // 3. 主题选择（单选）
        Text { text: "主题颜色:" }
        Column {
            RadioButton { text: "浅色主题"; checked: true }
            RadioButton { text: "深色主题" }
            RadioButton { text: "自动切换" }
        }

        // 4. 音量控制滑块
        Text { text: "提示音量:" }
        Slider {
            id: volumeSlider
            Layout.fillWidth: true
            from: 0; to: 100; value: 60
        }
        Text { text: "当前音量: " + Math.round(volumeSlider.value); Layout.alignment: Qt.AlignRight }

        // 5. 保存设置与进度展示
        Button {
            text: "保存设置"
            Layout.alignment: Qt.AlignHCenter
            onClicked: {
                saveProgress.visible = true;
                saveTimer.start(); // 启动模拟保存计时器
            }
        }
        ProgressBar {
            id: saveProgress
            Layout.fillWidth: true
            visible: false
            from: 0; to: 100; value: 0
        }

        // 模拟保存进度的计时器
        Timer {
            id: saveTimer
            interval: 50
            repeat: true
            onTriggered: {
                if (saveProgress.value < 100) {
                    saveProgress.value += 5;
                } else {
                    stop();
                    saveProgress.visible = false;
                    console.log("设置保存完成！");
                    saveProgress.value = 0; // 重置进度
                }
            }
        }
    }
}

本章总结

• Button是交互动作的触发器，是用户操作的起点；
• CheckBox支持多选，RadioButton强制单选，二者分别满足不同的选择场景；
• Slider提供直观的数值范围选择方式，适合调节类功能；
• ProgressBar是用户反馈的核心组件，清晰展示任务进度或等待状态；
• TextField是获取单行文本输入的主要途径，合理使用验证器可提升输入数据质量；
• 掌握每个组件的属性、信号与适用场景是灵活运用的关键，通过自定义样式（如修改background），能让组件完美适配应用设计风格。
• 
  

优秀的UI设计不仅是组件的简单摆放，更要贴合用户意图，通过合适的组件与流畅的交互逻辑满足需求。下一章我们将探索更复杂的QT Quick可视化组件。