Qt Quick基础可视Item

Qt Quick模块作为一个编写QML应用程序的标准库，提供了用于创建用户界面的所有基本类型，使用这些类型可以创建动态可视化组件、接收用户输入、创建数据模型和视图。

其中提供的Item类型，是所有其他可视化类型的基类型。

Qt Quick模块既提供了QML 语言接口，可以使用QML类型来创建用户界面，也提供了C语言接口，可以使用C代码来扩展 QML 应用。

Qt Quick模块的子模块如下：

• Local Storage：提供前端式本地持久化数据库，基于 SQLite，类似网页的 LocalStorage，专门给 QML 脚本做轻量本地数据存储。
• Particles：高性能粒子渲染引擎，做动态视觉特效，底层 GPU 加速，不阻塞 UI 主线程。
• Controls：Qt Quick 官方完整交互控件集，替代原生简陋 Rectangle 自制按钮，提供开箱即用的标准化 UI 组件，支持桌面 / 移动端统一样式。
• Layouts：自动布局系统，替代手动绑定 x/y/width/height，实现自适应、响应式界面，窗口缩放自动适配。
• Tests：专门针对 QML 代码、Quick 控件做自动化单元测试、界面交互测试，属于测试工具模块，打包发布时一般不携带。
• Effects：GPU 实时滤镜、图层特效，给任意 Item 增加后期渲染效果，基于着色器（Shader）硬件加速。

Item

Qt Quick中所有可视化类型都基于Item，它们都被称为可视化项目（visual items）。虽然单独的Item对象没有可视化外观，但是它定义了可视化项目所有通用的特性，例如关于位置的x和y属性，关于大小的width和height属性，关于布局的anchors相关属性，以及关于按键处理的Keys附加属性等等。

• 作为容器

Item常用于对项目进行分组，在一个根项目下，使用Item项目组织其它的项目。例如下面的代码片段中，Item里面包含了一个图片Image项目和一个矩形Rectangle项目：

Item {
    Image {
        x: 80
        width: 100; height: 100
        source: "tile.png"
    }
    Rectangle {
        x: 190
        width: 100; height: 100
    }
}

• 默认属性

Item有一个children属性和一个resources属性，前者包含了可见的子项目列表，后者包含了不可见的资源。例如下面的代码片段所示：

Item {
    children: [
        Text {},
        Rectangle {}
    ]
    resources: [
        Timer {}
    ]
}

Item还有一个data默认属性，允许在一个项目中将可见的子项目和不可见的资源进行自由混合。也就是说，如果向data列表中添加一个可视项目，那么该项目将作为一个孩子进行添加；如果添加任何其它的对象类型，则会作为资源进行添加。因为data是默认属性，所以可以省略data标签，这样前面的代码可以改写为：

Item {
    Text {}
    Rectangle {}
    Timer {}
}

• 不透明度：

Item有一个opacity属性，可以用来设置不透明度。该属性可选值为0.0（完全透明）和1.0（完全不透明）之间的任意数字，默认值为1.0。opacity是一个继承属性，也就是说，父项目的透明度也会应用到子项目上。例如两个相互重叠的不透明矩形，通过设置父项目的opacity属性，会使两个矩形都变成透明的：

Item {
    Rectangle {
        opacity: 0.5
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

• 可见与启用

Item的visible属性用来设置项目是否可见，其默认值为true。设置一个项目的visible属性会直接影响其子项目的可见性，除非单独设置子项目的visible属性。如果将该属性设置为false，那么项目将不再接收鼠标事件，但是可以继续接收键盘事件。如果在设置visible属性之前，项目被设置了键盘焦点，那么焦点依然会保留。

Item还有一个enabled属性，它可以设置项目是否接收鼠标和键盘事件，其值默认为true。设置一个项目的enabled属性也会直接影响其子项目的enabled值，除非对其子项目的enabled属性进行单独设置。

• 定位子项目和坐标映射

Item中提供了childAt(real x, real y)函数来返回在点(x, y)处的第一个可视子项目，如果没有这样的项目则返回null。

Item的mapFromItem(Item item, real x, real y)函数会将item坐标系统中点(x, y)映射到该项目的坐标系统上，该函数会返回一个包含映射后的x和y属性的对象。

对应的还有一个mapToItem(Item item, real x, real y)函数，可以从当前项目坐标系统的(x, y)点映射到item的坐标系统。

• 堆叠顺序

Item拥有一个z属性，可以用来设置兄弟项目间的堆叠顺序。默认的堆叠顺序为0。拥有较大z值的项目会出现在z值较小的兄弟项目之上。拥有相同的z属性值的项目会以代码中出现的顺序由下向上进行绘制。如果项目的z属性值为负，那么它会被绘制在其父项目的下面。

Item {
    Rectangle {
        z: 1
        color: "red"; width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Rectangle

Rectangle项目继承自Item，被用来使用纯色或者渐变填充一个矩形区域，并提供一个边框。

Rectangle项目可以使用color属性指定一个纯色来填充，或者使用gradient属性指定一个Gradient类型定义的渐变来填充。

除此之外，还可以为Rectangle添加一个可选的边框，并通过border.color和border.width为其指定颜色和宽度。也可以使用radius属性来产生一个圆角矩形。

Rectangle {
    width: 100; height: 100
    color: "lightgrey"
    border.color: "black"; border.width: 5; radius: 20
}

Text

Text项目可以显示纯文本或者富文本，类似于Qt Widgets中的QLabel。Text支持有限的HTML子集。如果在文本中包含HTML的img标签加载远程的图片，文本会被重载。Text是只读文本，如果要使用可编辑文本，可以使用TextEdit项目。

• wrapMode属性设置换行
• elide属性设置自动省略显示
• textFormat属性设置文本格式
• horizontalAlignment设置文本在Text项目区域中的水平对齐方式
• verticalAlignment设置文本在Text项目区域中的垂直对齐方式

Column {
    Text {
        text: "Hello World!"
        font.family: "Helvetica"; font.pointSize: 50
        color: "red"
    }
    Text {
        text: "<b>Hello</b> <i>World!</i>"
        font.pointSize: 30
    }
}


Rectangle {
    width: 200; height: 200; color: "lightgrey"

    Text {
        width: 200; height: 200
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        text: qsTr("中心")
        font.pointSize: 20
    }
}

TextInput

TextInput项目用来显示单行可编辑的纯文本。TextInput与Qt Widgets中的QLineEdit相似，用于接收单行文本输入。

Item {
    Rectangle {
        id: rect
        width: input.contentWidth<100 ? 100 : input.contentWidth + 10
        height: input.contentHeight + 5
        color: "lightgrey"; border.color: "grey"

        TextInput {
            id: input
            anchors.fill: parent; anchors.margins: 2
            font.pointSize: 15; focus: true

            inputMask: ">AA_9_a"
            onEditingFinished: text2.text = text
        }
    }

    Text { id: text2; anchors.top: rect.bottom}
}

TextEdit

TextEdit与TextInput类似，不同之处在于，TextEdit用来显示多行的可编辑的格式化文本。TextEdit与Qt中的QTextEdit很相似，它既可以显示纯文本也可以显示富文本。

TextEdit {
    width: 240; height: 400
    wrapMode: Text.WordWrap
    text: "<b>Hello</b> <i>World!</i> Note that the TextEdit does not implement scrolling,
            following the cursor, or other behaviors specific to a look and feel. For example,
            to add flickable scrolling that follows the cursor"
    textFormat: Text.RichText
    font.family: "Helvetica"
    font.pointSize: 20
    color: "blue"
    focus: true
}

Qt Quick Controls

Qt Quick Controls模块是Qt Quick模块的子模块，包含了一组丰富的UI控件，迎合了最常见的用例，并且提供了定制选项，可用于在Qt Quick中构建完整的应用界面。

控件基类型 Control

Control是用户界面控件的基类型，Qt Quick Controls模块中的大部分控件都继承自Control，而Control继承自Item，一般不直接使用该类型，而是使用它的众多子控件类型。Control从窗口系统接收输入事件并在屏幕上绘制自身，一个典型的Control控件布局如图所示。

控件的隐式大小implicitWidth和implicitHeight通常基于背景background和内容项contentItem的隐式大小以及四周的insets和paddings等属性的值。

当没有明确指定控件的width和height属性时，会通过这些值来决定控件的大小。背景的insets相关属性可以在不影响控件的视觉外观的情况下扩展其可交互区域，这对于较小的控件非常有用。

按钮类

在Qt Quick Controls模块中提供了一组按钮类控件，包括AbstractButton及其子孙类型，每种类型的按钮都有自己的特定用例。

Qt Quick Controls AbstractButton 完整核心属性如下：

AbstractButton子类如下：

• Button：最通用、默认的矩形主按钮，页面主操作、弹窗确认 / 取消、表单提交都用它。

实现了一个通用的按钮控件，一般用来执行一个动作或者回答一个问题，比如“确定”“取消”等。Button在AbstractButton的基础上添加了flat和highlighted两个属性。

• CheckBox：多选开关控件，可独立勾选、取消，支持多选项同时选中。

复选框用来创建一个选项按钮，可以在“选中”和“未选中”两种状态间切换。如果将tristate属性设置为true，则复选框可以拥有第3种状态“部分选中”。

• DelayButton：需要长按等待一段时间才触发点击，防止误触的安全按钮。

是一个可被选中的按钮，在被选中并发出activated()信号之前，有一个延迟，用来防止意外按压。progress属性可返回当前进度，介于0.0~1.0之间，延迟时间以毫秒为单位，通过delay属性进行设置。

• RadioButton：互斥单选组件，同一分组内只能选一个。

单选按钮通常用于从一组选项中选择一个选项。单选按钮的autoExclusive属性默认为true，在属于同一父项的单选按钮中，任何时候只能选中一个按钮，选中另一个按钮会自动取消选中先前选中的按钮。（ButtonGroup可以包含一组互斥的按钮，该控件本身是不可见的，一般与RadioButton等控件一起使用。如果需要ButtonGroup中的按钮不再互斥，可以设置exclusive属性为false。）

• RoundButton：圆形变体按钮，视觉更柔和，常做悬浮、浮动操作按钮。

作为Button的子类型，在其基础上添加了一个radius属性，可以设置圆角，将按钮的implicitWidth和implicitHeight设置为同一值，并将radius设置为width / 2，可以创建一个圆形按钮。

• Switch：移动端风格滑动开关，用来控制布尔型功能开关。

开关按钮可以在“打开”和“关闭”之间进行切换，该按钮通常用于在两种状态之间进行选择。

• ToolButton：专为顶部 / 侧边工具栏、菜单栏设计的紧凑型按钮。

总结：

指示器类

在Qt Quick Controls提供了一系列类似指示器的控件，包括BusyIndicator、PageIndicator、ProgressBar、ScrollBar和ScrollIndicator等，它们均直接继承自Control。

• PageIndicator控件一般与StackLayout这样包含多个页面的容器控件一起使用来指示当前的活动页面；
• ScrollBar和ScrollIndicator控件一般用于Flickable及其子类型，用于显示滚动条和滚动位置。
• BusyIndicator控件用来显示一个忙碌指示器控件，用来指示正在加载内容或UI被阻止需等待资源等情况。
• ProgressBar控件用来显示一个进度条指示器控件，可以指示操作的进度。进度值由value属性指定，需要定期进行更新来显示进度，其范围由from属性（默认值为0.0）和to属性（默认值为1.0）指定。

Pane {
    width: 400; height: 300
    Image {
        id: image; anchors.fill: parent
        source: "https://www.qter.org/temp/back.png"
    }
    BusyIndicator {
        id:busy
        anchors.horizontalCenter: 
                        parent.horizontalCenter
        anchors.verticalCenter:
                        parent.verticalCenter
        running: image.status === Image.Loading
    }
    ProgressBar {
        visible: image.status === Image.Loading
        value: image.progress
    }
}

输入类

Qt Quick Controls模块中为数字和文本输入提供了多种输入控件，包括ComboBox、Dial、RangeSlider、Slider、TextArea、TextField、Tumbler和SpinBox等。示例如下：

• ComboBox控件

ComboBox继承自Control，是一个组合按钮和弹出列表的组合框控件，提供了一种以占用最小屏幕空间的方式向用户呈现选项列表的方法。填充到ComboBox的数据模型通常是JavaScript数组、ListModel或整数。将editable属性设置为true时，可以对ComboBox进行编辑。

Item {
    width: 200; height: 300

    ComboBox {
        x:10; y:10
        editable: true
        model: ListModel {
            id: model
            ListElement { text: "Banana" }
            ListElement { text: "Apple" }
            ListElement { text: "Coconut" }
        }
        onAccepted: {
            if (find(editText) === -1)
                model.append({text: editText})
        }
    }
}

• Dial 圆形旋钮调节控件

Dial继承自Control，实现类似于传统的音响上拨号旋钮样式的控件，可以用来指定范围内的值。通过from和to属性来指定开始和结束的值，value属性设置当前值。另外，可以使用stepSize设置步长，将wrap设置为true，可以到终点后直接跳到起始点。

Item {
    width: 100; height: 120

    Dial {
        id: dial
        from: 1; to: 10
        stepSize: 1; wrap: true
    }
    Label {
        anchors.top: dial.bottom
        text: dial.value
    }
}

• TextField 单行文本输入框

单行文字输入，用户名、密码、搜索框、短文本录入。核心属性：text 输入内容、placeholderText 提示文字、echoMode 密码隐藏、validator 输入校验、readOnly 只读。

TextField {
    width: 240
    placeholderText: "请输入用户名"
    text: "admin"
    echoMode: TextField.Normal // Password 密码隐藏
    onTextChanged: console.log("输入内容：", text)
}

TextField {
    width: 240
    placeholderText: "密码"
    echoMode: TextField.Password
}

• TextArea 多行文本框

TextArea继承自TextEdit，提供了一个多行文本编辑器，在TextEdit之上添加了占位符文本功能，并进行了一些装饰。TextArea本身不可以滚动，可以将其放入ScrollView中来实现滚动条。通过placeholderText属性可以设置占位符文本，它是在用户输入之前显示在文本区域中的简短提示。

ScrollView {
    id: view
    anchors.fill: parent
    TextArea {
        width: 300
        height: 100
        placeholderText: "请输入备注信息..."
        wrapMode: TextArea.Wrap
        text: "这里是多行文本\n支持换行显示"
	}
}

• SpinBox 数字增减输入框

允许用户通过单击向上或向下指示器按钮，或通过键盘向上或向下键来选择整数值。可以通过editable属性将SpinBox设置为可编辑。默认情况下，SpinBox提供0~99范围内的离散值，步长为1，可以通过from和to设置起始值和结束值，通过value设置当前值。尽管SpinBox默认只可以处理整数值，通过validator、textFromValue和valueFromText等属性也可以自定义让其接受任意输入值。

SpinBox {
    id: spinBox
    from: 0; to: items.length - 1
    value: 1 // "Medium"
    property var items: ["Small", "Medium", "Large"]
    
    validator: RegularExpressionValidator {
        regularExpression: new RegExp("(Small|Medium|Large)", "i")
    }
    
    textFromValue: function(value) {
        return items[value];
    }
    
    valueFromText: function(text) {
        for (var i = 0; i < items.length; ++i) {
            if (items[i].toLowerCase().indexOf(text.toLowerCase()) === 0)
                return i
        }
        return spinBox.value
    }
}

• Slider 单滑块进度条

单一数值滑动调节，音量、亮度、透明度、单一参数。核心属性：value、from、to、stepSize、handle 滑块样式

Slider {
    width: 260
    from: 0
    to: 100
    value: 50
    onValueChanged: console.log("亮度：", value)
}

• RangeSlider 双滑块区间滑块

区间选择，同时控制最小值、最大值，价格区间、时间范围。核心属性：firstValue 左滑块、secondValue 右滑块、from/to 整体范围。

RangeSlider {
    width: 260
    from: 0
    to: 1000
    firstValue: 200
    secondValue: 600
    onFirstValueChanged: console.log("区间下限：", firstValue)
    onSecondValueChanged: console.log("区间上限：", secondValue)
}

• Tumbler 滚轮选择器（移动端风格）

竖向滚轮滑动选择，时间选择器、数字列表、日期滚轮，手机端常用。核心属性：model 选项列表、currentIndex、visibleItemCount 可见行数。

Tumbler {
    width: 120
    height: 150
    visibleItemCount: 3
    model: ["周一", "周二", "周三", "周四", "周五"]
    currentIndex: 2
    onCurrentIndexChanged: console.log("选中：", model[currentIndex])
}

日期类

日期类控件包括DayOfWeekRow、WeekNumberColumn和MonthGrid，它们都继承自Control。

• DayOfWeekRow会将星期几的名称显示为一行，日期的名称使用指定的locale区域设置进行排序和格式化。

• WeekNumberColumn在一列中显示给定year年份、month月份的周数。这两个控件都可以独自使用，但是一般会和MonthGrid一起使用，通过计算给定月份和年份实现在网格中显示日历月。

Item {
    width: 400; height: 300
    
    GridLayout {
        columns: 2
        DayOfWeekRow {
            locale: grid.locale
            Layout.column: 1
            Layout.fillWidth: true
        }
        WeekNumberColumn {
            month: grid.month; year: grid.year
            locale: grid.locale
            Layout.fillHeight: true
        }
        MonthGrid {
            id: grid
            month: Calendar.December; year: 2022
            locale: Qt.locale("zh_CN")
            Layout.fillWidth: true
            Layout.fillHeight: true
            onClicked: (date) => console.log(date)
        }
    }
}

Qt Quick系统对话框

从Qt 6.2开始引入了Qt Quick Dialogs模块，可以从QML创建系统对话框并与之交互。常用的系统对话框类型包括ColorDialog、FileDialog、FolderDialog、FontDialog和MessageDialog等。

颜色对话框ColorDialog

ColorDialog类型为系统颜色对话框提供了QML API。要显示颜色对话框，可以先创建ColorDialog的实例，设置所需的属性，然后调用open()方法。通过selectedColor属性可用于获取对话框选定的颜色，通过options属性可以启用一些选项，比如显示Alpha通道。

Window {
    width: 800; height: 600; visible: true

    RowLayout {
        Button {
            text: qsTr("颜色对话框")
            onClicked: colorDialog.open()
        }
        Label { id: label; text: qsTr("颜色展示")}
    }

    ColorDialog {
        id: colorDialog
        selectedColor: label.color
        options: ColorDialog.ShowAlphaChannel
        onAccepted: label.color = selectedColor
    }
}

文件对话框FileDialog

FileDialog类型为系统文件对话框提供了QML API。

• 通过selectedFile和selectedFiles属性可以获取选择的文件；
• 通过nameFilters属性可以设置类型过滤器，只显示指定类型的文件；
• 通过currentFolder属性可以指定打开的默认目录；
• 通过acceptLabel和rejectLabel可以设置两个按钮的显示文本；
• 通过fileMode属性可以设置对话框模式，默认是FileDialog.OpenFile选择一个文件，另外还有FileDialog.OpenFiles选择多个文件，FileDialog.SaveFile保存文件。

Window {
    width: 640; height: 480; visible: true

    Image {
        id: image; anchors.fill: parent
        fillMode: Image.PreserveAspectFit
    }

    Button {
        text: qsTr("Choose Image...")
        onClicked: fileDialog.open()
    }

    FileDialog {
        id: fileDialog
        nameFilters: ["Image files (*.png *.jpg)"]
        currentFolder: StandardPaths.writableLocation
                       (StandardPaths.PicturesLocation)
        acceptLabel: qsTr("选择图片")
        onAccepted: image.source = selectedFile
    }
}

消息对话框MessageDialog

MessageDialog类型为系统消息对话框提供了QML API。MessageDialog用于通知用户或向用户提问。

• text属性，作为主要文本用来提醒用户注意的情况；
• informativeText属性，作为信息性文本以进一步解释警报或向用户提问；
• detailedText属性，作为可选的详细文本用于用户请求时提供更多数据；
• buttons属性用来设置按钮，例如MessageDialog.Ok、MessageDialog.Cancel等。

Window {
    width: 640; height: 480; visible: true

    Button {
        text: qsTr("消息对话框")
        onClicked: dlg.open()
    }
    
    MessageDialog {
        id: dlg
        title: qsTr("消息对话框")
        text: qsTr("这里是text的内容")
        informativeText: qsTr("这里是informativeText的内容")
        detailedText: qsTr("这里是detailedText的内容")
        buttons: MessageDialog.Ok | MessageDialog.Cancel
        onAccepted: console.log("ok")
    }
}

程序调试

Qt Creator中提供的调试模式可以对Qt Widgets和Qt Quick程序进行调试，其中的调试器可以查看应用程序在运行或崩溃时内部发生的情况，它可以通过如下方式来查找应用中的问题：

• 使用指定的参数启动应用程序；
• 在满足条件时停止应用程序；
• 检查应用程序停止时会发生什么；
• 修复错误后对应用程序进行更改，然后继续查找下一个错误。

开始调试前一般在需要调试的代码标号前面单击来设置断点。所谓断点，就是程序运行到该行代码时会暂停下来，从而可以查看一些信息。要取消断点，只要在那个断点上再单击一下就可以了。设置好断点后便可以按下F5或者左下角的调试按钮开始调试。

1. 继续按钮。程序在断点处停了下来，按下继续按钮后，程序便会像正常运行一样。
2. 停止调试按钮。按下该按钮后结束调试。
3. 单步跳过按钮。直接执行本行代码，然后指向下一行代码。
4. 单步进入按钮。进入调用的函数内部。
5. 单步跳出按钮。当进入函数内部时，跳出该函数，一般与单步进入配合使用。
6. 重新启动调试会话。
7. 显示源码对应的汇编指令，并可以单步调试。
8. 堆栈视图。这里显示了从程序开始到断点处，所有嵌套调用的函数所在的源文件名和行号。
9. 其它视图。这里可以选择多种视图，主要有局部变量（Locals）和表达式（Expressions）视图、断点（Breakpoints）视图、线程视图（Threads）等。

在Qt Widgets程序中使用qDebug()函数

程序调试过程中常用的是qDebug()、qInfo()、qCritical()、qWarning()和qFatal()等函数，它们由Qt Core模块提供，可以将调试信息直接输出到控制台，当然，Qt Creator中是输出到下方应用程序输出栏。在Qt Widgets程序中，调试信息一般常用qDebug()。

 int x = widget.x();
    qDebug("x: %d", x);           
    int y = widget.y();
    qDebug("y: %d", y);
    QRect geometry = widget.geometry();
    QRect frame = widget.frameGeometry();
    qDebug() << "geometry: " << geometry << "frame: " << frame;

这里使用了两种输出方法，一种是直接将字符串当做参数传给qDebug()函数，例如上面使用这种方法输出x和y的值。另一种方法是使用输出流的方式一次输出多个值，它们的类型可以不同，如程序中输出geometry和frame的值。实际编程中经常使用第二种方法。

qDebug() << "pos:" << widget.pos() << Qt::endl 
         << "rect:" << widget.rect()<< Qt::endl 
         << "size:" << widget.size() << Qt::endl 
         << "width:"<< widget.width() << Qt::endl 
         << "height:" << widget.height();

在Qt Quick程序中使用console.log()函数

Qt Quick程序也可以使用调试模式，而且QML中也提供了console.log()、 console.debug()、console.info()、 console.warn()和console.error()等调试输出函数，比较常用的是console.log()。

Rectangle {
    width: 200
    height: 200
    color: "blue"
    
    MouseArea {
        anchors.fill:parent
        onClicked: console.log("矩形的颜色：", parent.color)
    }
}