1276 lines
34 KiB
Markdown
1276 lines
34 KiB
Markdown
# QML 应用程序开发技术总结
|
||
|
||
- [QML 应用程序开发技术总结](#qml-应用程序开发技术总结)
|
||
- [1. 基础部分](#1-基础部分)
|
||
- [1.1. 方法/属性名称的大小写](#11-方法属性名称的大小写)
|
||
- [1.2. 显示顺序](#12-显示顺序)
|
||
- [2. 全局属性](#2-全局属性)
|
||
- [3. 信号与槽](#3-信号与槽)
|
||
- [3.1. 信号与信号处理器](#31-信号与信号处理器)
|
||
- [3.2. 属性变化信号与属性变化信号处理器](#32-属性变化信号与属性变化信号处理器)
|
||
- [3.3. 附加属性与附加信号处理器](#33-附加属性与附加信号处理器)
|
||
- [3.4. Connections 建立信号与槽的连接](#34-connections-建立信号与槽的连接)
|
||
- [3.5. connect()方法](#35-connect方法)
|
||
- [3.6. 自定义信号](#36-自定义信号)
|
||
- [4. 界面加载完成信号](#4-界面加载完成信号)
|
||
- [5. 包别名](#5-包别名)
|
||
- [6. 添加图标](#6-添加图标)
|
||
- [6.1. 制作图标](#61-制作图标)
|
||
- [6.2. 添加图标到应用](#62-添加图标到应用)
|
||
- [7. 绘制圆形](#7-绘制圆形)
|
||
- [8. 常用组件](#8-常用组件)
|
||
- [8.1. QtQuick.Loader](#81-qtquickloader)
|
||
- [8.2. QtQuick.Controls.Button](#82-qtquickcontrolsbutton)
|
||
- [8.3. Dialog 对象](#83-dialog-对象)
|
||
- [8.3.1. QtQuick.Controls 中的 Dialog](#831-qtquickcontrols-中的-dialog)
|
||
- [8.3.2. QtQuick.Dialogs](#832-qtquickdialogs)
|
||
- [8.3.2.1. FileDialog](#8321-filedialog)
|
||
- [8.3.2.2. MessageDialog](#8322-messagedialog)
|
||
- [8.4. ComboBox](#84-combobox)
|
||
- [8.5. Grid](#85-grid)
|
||
- [8.6. ScrollView](#86-scrollview)
|
||
- [8.7. QtQuick.ListView](#87-qtquicklistview)
|
||
- [8.7. GridView](#87-gridview)
|
||
- [8.8. BusyIndicator](#88-busyindicator)
|
||
- [8.9. VirtualKeyboard](#89-virtualkeyboard)
|
||
- [9. 多文档开发](#9-多文档开发)
|
||
- [9.1. 多 QML 文件的管理](#91-多-qml-文件的管理)
|
||
- [9.2. 如何引用自定义 QML 文件](#92-如何引用自定义-qml-文件)
|
||
- [9.3. 使用另一 QML 文件中的元件或属性](#93-使用另一-qml-文件中的元件或属性)
|
||
- [9.4. 示例](#94-示例)
|
||
- [10. QML 与 C++ 交互](#10-qml-与-c-交互)
|
||
- [10.1. QML 访问 C++ 中声明的类型](#101-qml-访问-c-中声明的类型)
|
||
- [10.2. C++ 访问 QML 对象](#102-c-访问-qml-对象)
|
||
- [10.3. 通过信号槽传递自建类型](#103-通过信号槽传递自建类型)
|
||
- [10.4. QML 与 C++ 交互综合示例](#104-qml-与-c-交互综合示例)
|
||
- [11. Windows 下 QML 程序的打包发布](#11-windows-下-qml-程序的打包发布)
|
||
- [12. 外部参考资料](#12-外部参考资料)
|
||
|
||
## 1. 基础部分
|
||
|
||
### 1.1. 方法/属性名称的大小写
|
||
|
||
QML 语法与 JS 相同，具体请参考相关教程，此处只对一些需要特殊注意的地方进行说明。
|
||
|
||
QML 的属性、变量、函数等一般为小写字母开头，大写字母开头通常具有特殊意义，比如使用 QML 连接名为 demo() 的信号时，系统将自动连接 onDemo() 作为其槽函数。以下以连接 Button 的 clicked 信号为例进行演示：
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Controls 2.12
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
|
||
Button {
|
||
onClicked: {
|
||
// Do something...
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2. 显示顺序
|
||
|
||
QML 可以包含多个可显示对象，默认情况下 QML 文件中先写的对象显示在下层，后写的对象显示在上层。在显示时，上层的对象覆盖下层对象。
|
||
|
||
## 2. 全局属性
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Controls 2.12
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
|
||
property int demoInt: 1
|
||
property string demoStr: "Hello"
|
||
}
|
||
```
|
||
|
||
## 3. 信号与槽
|
||
|
||
在 QML 中连接信号槽主要有以下 5 种方法。
|
||
|
||
### 3.1. 信号与信号处理器
|
||
|
||
```js
|
||
signal()
|
||
|
||
on<Signal>: {}
|
||
```
|
||
|
||
这是最常见的方法，比如 onClicked: {} 槽。
|
||
|
||
### 3.2. 属性变化信号与属性变化信号处理器
|
||
|
||
```js
|
||
property
|
||
|
||
on<Property>Changed: {}
|
||
```
|
||
|
||
QML 规范，当属性变化后会发送一个 \<Property\>Changed 信号。从 C 环境创建属性时需要注册 NOTIFY 信号，其命名格式也需要遵循该规范。
|
||
|
||
### 3.3. 附加属性与附加信号处理器
|
||
|
||
```js
|
||
Attached Signal(附加属性)
|
||
|
||
XX元素.on<附加属性>: {}
|
||
```
|
||
|
||
最常见的是 Component.onCompleted：{} 槽。
|
||
|
||
### 3.4. Connections 建立信号与槽的连接
|
||
|
||
```js
|
||
Connections {
|
||
target: 发送者
|
||
发送者信号处理器：{}
|
||
}
|
||
```
|
||
|
||
前面的信号连接都嵌入在某个对象中，当信号与槽的连接不依赖具体对象时，需要将其嵌入到 Connections 对象中。Connections 的 target 指向信号的发送者，一个 Connections 可以绑定同一个 target 的多个信号处理机。
|
||
|
||
```js
|
||
Connections {
|
||
target: whomSentTheSignal
|
||
|
||
function onSignal0(arg) {
|
||
console.log(arg)
|
||
}
|
||
|
||
function onSignal1(arg) {
|
||
console.log(arg)
|
||
}
|
||
// ...
|
||
}
|
||
```
|
||
|
||
### 3.5. connect()方法
|
||
|
||
使用 connect() 方法，可以为信号指定非 on\<Signal\> 格式命名的响应方法，也可以指令信号触发下一个信号形成信号的连锁反应。
|
||
|
||
```js
|
||
[元素对象.]信号.connect(信号/方法)
|
||
```
|
||
|
||
示例如下：
|
||
|
||
```js
|
||
Rectangle {
|
||
id: root
|
||
|
||
signal mySignal()
|
||
// 信号响应处理
|
||
onMySignal: console.log("clicked connect mySignal")
|
||
|
||
// 普通方法
|
||
function slt_clicked() {
|
||
console.log("clicked connect slt_clicked");
|
||
}
|
||
|
||
Component.onCompleted: {
|
||
mousearea.clicked.connect(slt_clicked);
|
||
mousearea.clicked.connect(mySignal);
|
||
}
|
||
|
||
MouseArea {
|
||
id: mousearea
|
||
anchors.fill: parent
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.6. 自定义信号
|
||
|
||
用以下形式声明自定义的信号：
|
||
|
||
```js
|
||
signal <name>[([<type> <parameter name>[, ...]])]
|
||
```
|
||
|
||
示例如下：
|
||
|
||
```js
|
||
Rectangle {
|
||
id: root
|
||
signal mysignal(int x, int y)
|
||
|
||
MouseArea {
|
||
anchors.fill: parent
|
||
onPressed: root.mysignal(mouse.x, mouse.y)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. 界面加载完成信号
|
||
|
||
许多时候需要在 QML 程序界面完成加载后做一些事情，比如设置一些属性的初始值。这时候就需要用到 Component 的 completed() 信号：
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Controls 2.12
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
|
||
TextField {
|
||
id: demoText
|
||
text: qsTr("Demo")
|
||
font.pixelSize: 12
|
||
}
|
||
|
||
Component.onCompleted: {
|
||
demoText.text = qsTr("DemoText"）
|
||
// 加载完成后 demoText 默认获得焦点.
|
||
demoText.forceActiveFocus()
|
||
}
|
||
}
|
||
```
|
||
|
||
## 5. 包别名
|
||
|
||
编写 QML 应用时需要像 include 那样引用一些软件包，有的时候软件包中的对象会有重名的情况，比如 QtQuick.Dialogs 1.3 和 Qt.labs.qmlmodels 1.0 中均包含了 FileDialog 对象，但他们的功能并不相同。此时可以使用 import as 来实现类似别名或者命名空间的功能。
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Dialogs 1.3
|
||
import Qt.labs.platform 1.1 as QLP
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
|
||
FileDialog {
|
||
title: qsTr("保存到…")
|
||
folder: QLP.StandardPaths.writableLocation(QLP.StandardPaths.DocumentsLocation)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 添加图标
|
||
|
||
### 6.1. 制作图标
|
||
|
||
先安装 ImageMagic 工具，并将其添加到系统 PATH 下方便使用。
|
||
|
||
使用以下命令将多个不同尺寸的图片打包成一个 ICO 文件。
|
||
|
||
```bash
|
||
magick.exe convert icon-16.png icon-32.png icon-256.png myappico.ico
|
||
```
|
||
|
||
### 6.2. 添加图标到应用
|
||
|
||
在 Qt .pro 文件中添加以下内容，以便将图标编译到 Qt 程序中：
|
||
|
||
```js
|
||
RC_ICONS = myappico.ico
|
||
```
|
||
|
||
However, if you already have an .rc file, for example, with the name myapp.rc, which you want to reuse, the following two steps will be required. First, put a single line of text to the myapp.rc file:
|
||
|
||
```js
|
||
IDI_ICON1 ICON "myappico.ico"
|
||
```
|
||
|
||
Then, add this line to your myapp.pro file:
|
||
|
||
```js
|
||
RC_FILE = myapp.rc
|
||
```
|
||
|
||
If you do not use qmake, the necessary steps are: first, create an .rc file and run the rc or windres program on the .rc file, then link your application with the resulting .res file.
|
||
|
||
更详细内容见《[Setting the Application Icon](https://doc.qt.io/qt-5/appicon.html)》。
|
||
|
||
## 7. 绘制圆形
|
||
|
||
设置 Rectangle 的 radius 为边长的一半即可。
|
||
|
||
## 8. 常用组件
|
||
|
||
### 8.1. QtQuick.Loader
|
||
|
||
TODO:
|
||
TODO: 参考 XiaYu 项目中的 SubMenuGrp 和 SubMenuBtn 对 default 属性和子组件引用父组件方法、属性进行说明。
|
||
|
||
### 8.2. QtQuick.Controls.Button
|
||
|
||
```js
|
||
Button {
|
||
id: butDemo
|
||
width: 200
|
||
height: 100
|
||
text: qsTr("Demo")
|
||
// 获得焦点时高亮.
|
||
highlighted: activeFocus
|
||
onClicked: butDemo.text = qsTr("DemoButton")
|
||
// 当 Button 获得焦点时可响应回车按钮.
|
||
Keys.onReturnPressed: butDemo.text = qsTr("Button")
|
||
}
|
||
```
|
||
|
||
### 8.3. Dialog 对象
|
||
|
||
QML 中有三大类 Dialog 对象，这里主要介绍 QtQuick.Controls 中的 Dialog 和 QtQuick.Dialogs。
|
||
|
||
#### 8.3.1. QtQuick.Controls 中的 Dialog
|
||
|
||
QtQuick.Controls 中的 Dialog 比较原始，属性需要自行定义和实现，所以它的自由度也比较高。该 Dialog 包含了页眉（Header）、页脚（Footer）和内容（Content）三部分，每个部分都可以单独设定。
|
||
|
||
- footer：Item
|
||
|
||
对话框页脚项。页脚项目位于底部，并调整为对话框的宽度。 默认值为空。
|
||
|
||
注意：将 DialogButtonBox 指定为对话框页脚会自动将其 accepted() 和 rejected() 信号连接到 Dialog 中的相应信号。
|
||
|
||
注意：将 DialogButtonBox、ToolBar 或 TabBar 指定为对话框页脚会自动将相应的 DialogButtonBox::position、ToolBar::position 或 TabBar::position 属性设置为 Footer。
|
||
|
||
- header：Item
|
||
|
||
对话框标题项。标题项位于顶部，并调整为对话框的宽度。默认值为空。
|
||
|
||
注意：将 DialogButtonBox 指定为对话框标题会自动将其 accepted() 和 rejected() 信号连接到 Dialog 中的相应信号。
|
||
|
||
注意：将 DialogButtonBox、ToolBar 或 TabBar 指定为对话框标题会自动将相应的 DialogButtonBox::position、ToolBar::position 或 TabBar::position 属性设置为 Header。
|
||
|
||
该 Dialog 不会阻塞父窗口，并且在点击 Dialog 之外的区域会自动关闭，如果需要阻塞父窗口并且不自动关闭，则需要设定如下属性：
|
||
|
||
```js
|
||
Dialog {
|
||
modal : true
|
||
closePolicy: Popup.NoAutoClose
|
||
}
|
||
```
|
||
|
||
上面的对话框没有提供任何按钮，可以通过 standardButtons 设定标准按钮：
|
||
|
||
```js
|
||
Dialog {
|
||
title: qsTr("Demo")
|
||
standardButtons: Dialog.Ok | Dialog.Cancel
|
||
modal : true
|
||
closePolicy: Popup.NoAutoClose
|
||
}
|
||
```
|
||
|
||
除 Ok Button 和 Cancel Button 外，还有许多系统预定义的 Standard Button 可自行翻阅 QML 帮助获得相关帮助信息。
|
||
|
||
#### 8.3.2. QtQuick.Dialogs
|
||
|
||
在使用 QtQuick.Dialogs 的 Dialog 对象时，如果使用 QGuiApplication 来执行则会导致无法加载主题风格，并且对话框无法正确显示图标。如果最初使用 QGuiApplication 创建了 app，则需要进行如下修改：
|
||
|
||
```cpp
|
||
/**
|
||
* .pro 文件中增加 widgets
|
||
*/
|
||
QT += widgets
|
||
|
||
/**
|
||
* main.cpp 中替换 QGuiApplication 为 QApplication
|
||
*/
|
||
// #include <QGuiApplication>
|
||
#include <QApplication>
|
||
// QGuiApplication app(argc, argv);
|
||
QApplication app(argc, argv);
|
||
```
|
||
|
||
Dialog 对象默认不显示，当调用 Dialog 的 open() 方法后弹出窗口并阻塞父窗体的执行。
|
||
|
||
##### 8.3.2.1. FileDialog
|
||
|
||
FileDialog 为标准文件对话框。
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Controls 2.12
|
||
import QtQuick.Dialogs 1.3
|
||
import Qt.labs.platform 1.1 as QLP
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
|
||
Button {
|
||
text: qsTr("保存到")
|
||
|
||
onClicked: {
|
||
savetoDialog.open()
|
||
}
|
||
}
|
||
|
||
FileDialog {
|
||
id: savetoDialog
|
||
title: qsTr("保存到…")
|
||
selectFolder: true
|
||
onAccepted: {
|
||
// ...
|
||
}
|
||
}
|
||
|
||
Component.onCompleted: {
|
||
savetoDialog.folder = QLP.StandardPaths.writableLocation(QLP.StandardPaths.DocumentsLocation)
|
||
}
|
||
}
|
||
```
|
||
|
||
##### 8.3.2.2. MessageDialog
|
||
|
||
MessageDialog 为标准消息对话框。
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Controls 2.12
|
||
import QtQuick.Dialogs 1.3
|
||
import Qt.labs.platform 1.1 as QLP
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
|
||
function showInfoDialog(title, info, detail) {
|
||
infoDialog.title = title
|
||
infoDialog.text = info
|
||
infoDialog.detailedText = detail
|
||
infoDialog.open()
|
||
}
|
||
|
||
MessageDialog {
|
||
id: infoDialog
|
||
standardButtons: MessageDialog.Ok
|
||
title: ""
|
||
text: ""
|
||
}
|
||
|
||
Button {
|
||
text: qsTr("显示消息")
|
||
|
||
onClicked: {
|
||
showInfoDialog(qsTr("标题"), qsTr("信息"), qsTr("细节"))
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.4. ComboBox
|
||
|
||
ComboBox 为标准组合框
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Controls 2.12
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
|
||
ComboBox {
|
||
id: baudrate
|
||
width: 88
|
||
height: 24
|
||
anchors.left: port.right
|
||
anchors.top: parent.top
|
||
currentIndex: 6
|
||
anchors.leftMargin: 8
|
||
anchors.topMargin: 8
|
||
model: ["2400", "4800", "9600", "19200", "38400", "57600", "115200", "230400", "460800"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.5. Grid
|
||
|
||
布局组件，可以布局多个行和列，每个子成员必须是相同类型，一般使用 Item 来组织多个不同类型。每个子成员必须设置高度和宽度，否则不被显示。
|
||
|
||
```js
|
||
import QtQuick
|
||
import QtQuick.Controls 6.3
|
||
|
||
Grid {
|
||
spacing: 8
|
||
rows: 2
|
||
columns: 2
|
||
|
||
Item {
|
||
height: 20; width: 68
|
||
Text {
|
||
anchors.fill: parent
|
||
text: qsTr("DemoItem0")
|
||
}
|
||
}
|
||
Item {
|
||
height: 20; width: 68
|
||
TextField {
|
||
anchors.fill: parent
|
||
text: qsTr("DemoItem1")
|
||
}
|
||
}
|
||
Item {
|
||
height: 20; width: 68
|
||
Button {
|
||
anchors.fill: parent
|
||
text: qsTr("DemoItem2")
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.6. ScrollView
|
||
|
||
ScrollView 会为其所容纳的对象创建滚动条。
|
||
|
||
### 8.7. QtQuick.ListView
|
||
|
||
TODO: header, headerPositioning
|
||
|
||
TODO: 如果通过设置 header 和 headerPositioning 参数来实现固定 header，且同时伴有 ScrollBar 的情况下，滚动条依然会覆盖到 header 上，效果不理想。此时最好在 ListView 之外使用 Row 嵌套 Label 来实现类似效果。
|
||
|
||
### 8.7. GridView
|
||
|
||
GridView 可以以网格的形式显示模型内容。可以使用 ListModel 或 XmlListModel 作为模型。
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Controls 2.12
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
id: window
|
||
// 测试按钮, 添加项目
|
||
Button {
|
||
id: butAdd
|
||
width: 64
|
||
height: 24
|
||
text: qsTr("添加")
|
||
anchors.left: parent.left
|
||
anchors.top: parent.top
|
||
anchors.leftMargin: 4
|
||
anchors.topMargin: 4
|
||
|
||
onClicked: {
|
||
demoList.append({fname: "fruit", fcost: "price"})
|
||
}
|
||
}
|
||
// 测试按钮, 清空全部项目
|
||
Button {
|
||
id: butClear
|
||
width: 64
|
||
height: 24
|
||
text: qsTr("清空")
|
||
anchors.left: butAdd.right
|
||
anchors.top: parent.top
|
||
anchors.leftMargin: 4
|
||
anchors.topMargin: 4
|
||
|
||
onClicked: {
|
||
demoList.clear()
|
||
}
|
||
}
|
||
|
||
// 使用 Rectangle 作为背景.
|
||
Rectangle {
|
||
color: "#e0e0e0"
|
||
anchors.left: parent.left
|
||
anchors.right: parent.right
|
||
anchors.top: butAdd.bottom
|
||
anchors.bottom: parent.bottom
|
||
anchors.rightMargin: 4
|
||
anchors.bottomMargin: 4
|
||
anchors.leftMargin: 4
|
||
anchors.topMargin: 4
|
||
|
||
GridView {
|
||
id: demoView
|
||
anchors.fill: parent
|
||
cellWidth: 128
|
||
cellHeight: 32
|
||
contentWidth: cellWidth
|
||
contentHeight: cellHeight
|
||
// clip 属性非常重要, 如不设置该属性, 显示的单元信息有可能溢出 GridView 边界.
|
||
clip: true
|
||
|
||
// 滚动条设置.
|
||
ScrollBar.vertical: ScrollBar {
|
||
policy: ScrollBar.AlwaysOn
|
||
}
|
||
|
||
// 使用 ListModel 作为模型.
|
||
model: ListModel {
|
||
id: demoList
|
||
ListElement {fname: "Apple"; fcost: "2.45"}
|
||
ListElement {fname: "Orange"; fcost: "3.25"}
|
||
}
|
||
|
||
// 委托包含用于显示信息的 Text 对象和用于获取鼠标点击事件的 MouseArea
|
||
delegate: Rectangle {
|
||
id: demoDelegate
|
||
width: demoView.cellWidth
|
||
height: demoView.cellHeight
|
||
color: "#f6f6f6"
|
||
MouseArea {
|
||
anchors.fill: parent
|
||
onClicked: {
|
||
// index 为系统传入参数, 代表当前点击对象的索引值.
|
||
// fcost 和 fcost 为 demoList 中的对象属性, 需要特别注意其用法.
|
||
demoList.setProperty(index, "fcost", "free")
|
||
console.log(demoList.get(index).fcost)
|
||
}
|
||
}
|
||
|
||
Text {
|
||
anchors.fill: parent
|
||
horizontalAlignment: Text.AlignHCenter
|
||
verticalAlignment: Text.AlignVCenter
|
||
text: fname+": "+fcost
|
||
}
|
||
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.8. BusyIndicator
|
||
|
||
用于指示工作状态，设置 BusyIndicator 的 running 属性为 true 将默认显示一个旋转的圆圈；设置 running 属性为 false 则 BusyIndicator 将不显示。
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Controls 2.12
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
|
||
BusyIndicator {
|
||
id: busyInd
|
||
anchors.horizontalCenter: parent.horizontalCenter
|
||
anchors.verticalCenter: parent.verticalCenter
|
||
running: true
|
||
}
|
||
}
|
||
```
|
||
|
||
可以对 BusyIndicator 进行自定义。
|
||
|
||
### 8.9. VirtualKeyboard
|
||
|
||
一些涉及触屏的应用会涉及到虚拟键盘/软键盘的应用，不同系统平台上往往会提供不同的软键盘工具，但相比之下，Qt 内嵌的 VirtualKeyboard 更加易用，并具有很好的跨平台能力，中文（拼音）、英文以及其他主要语言的支持能力也比较好。
|
||
|
||
若使用 VirtualKeyboard，只需要在创建“Qt Quick Application”时选中“Use Qt Virtual Keyboard”（旧版本 QtCreator 没有该选项）即可自动向项目添加 VirtualKeyboard 功能。
|
||
|
||
对比源码不难发现，启用 VirtualKeyboard 后主要在 main.cpp 中增加了：
|
||
|
||
```cpp
|
||
qputenv("QT_IM_MODULE", QByteArray("qtvirtualkeyboard"));
|
||
```
|
||
|
||
在 main.qml 中增加了：
|
||
|
||
```js
|
||
import QtQuick.VirtualKeyboard 2.4
|
||
|
||
Window {
|
||
InputPanel {
|
||
states: State {
|
||
// ...
|
||
}
|
||
transitions: Transition {
|
||
// ...
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
可以使用 VirtualKeyboardSettings 对 VirtualKeyboard 进行一些设置，这是一个全局对象，在 QML 中直接通过 VirtualKeyboardSettings.xxxxx 方式使用即可。VirtualKeyboardSettings 可对键盘风格、语言列表进行设置。需要特殊说明的是，VirtualKeyboard 所支持的语言列表是在编译时决定的，通过 VirtualKeyboardSettings.availableLocales 可以获得当前支持的语言列表；而 VirtualKeyboardSettings.activeLocales 可以在应用程序中临时限定允许使用的语言，最终在 Qt 的虚拟键盘中允许切换的语言为二者的交集。如下示例限制 VirtualKeyboard 只可以使用“简体中文”和“英文”输入法，如果编译 VirtualKeyboard 没有使能中文输入法则最终只能使用英文输入：
|
||
|
||
```js
|
||
import QtQuick.VirtualKeyboard.Settings 2.4
|
||
|
||
Window {
|
||
Component.onCompleted: {
|
||
VirtualKeyboardSettings.activeLocales = ["zh_CN", "en_US"]
|
||
}
|
||
}
|
||
```
|
||
|
||
如果是使用 Qt 提供的安装包来安装 VirtualKeyboard 模块则默认开启了中文支持，部分系统如 Ubuntu 中使用 apt 进行安装的可能不支持中文，可改用官方安装包来安装 Qt 或使用源码自行编译，注意在编译 VirtualKeyboard 的 qmake 阶段需要增加：
|
||
|
||
```makefile
|
||
CONFIG+="lang-en_GB lang-zh_CN"
|
||
```
|
||
|
||
更多关于 VirtualKeyboard 的应用可以参考官方自带示例。
|
||
|
||
## 9. 多文档开发
|
||
|
||
### 9.1. 多 QML 文件的管理
|
||
|
||
在创建基于 Qt6 的 QML 项目时，不会包含 qml.qrc 文件，系统编译时自动创建该文件，创建的依据是 .pro 文件中的 resources.xxx 字段：
|
||
|
||
```js
|
||
resources.files = main.qml
|
||
|
||
resources.prefix = /$${TARGET}
|
||
```
|
||
|
||
当我们向工程增加自定义 QML 文件时，会被增加到 DISTFILES 字段，比如：
|
||
|
||
```js
|
||
DISTFILES += \
|
||
Demo.qml
|
||
```
|
||
|
||
这会导致无法将 Demo.qml 加如到系统自建的 .qrc 文件中，此时会报：
|
||
|
||
```js
|
||
failed to load component ... is not a type
|
||
```
|
||
|
||
错误，此时需要手动添加 Demo.qml 到 resources.files 字段中。
|
||
|
||
### 9.2. 如何引用自定义 QML 文件
|
||
|
||
引用同级目录下的 QML 文件时不需要 import，在引用其他文件夹下的 QML 文件时需要：
|
||
|
||
```js
|
||
import "./DemoQml"
|
||
```
|
||
|
||
QML 文件必须以大写字母开头，以表明这是一个 QML 类型。
|
||
|
||
### 9.3. 使用另一 QML 文件中的元件或属性
|
||
|
||
可以使用：
|
||
|
||
```js
|
||
property alias <别名>:<属性名称/ID>
|
||
```
|
||
|
||
将一个 QML 文件中的某属性，某子组件的属性或某个子组件变为外部可见。
|
||
|
||
### 9.4. 示例
|
||
|
||
假设存在 DemoQml/Demo.qml 文件，该文件内容如下：
|
||
|
||
```js
|
||
import QtQuick
|
||
import QtQuick.Controls 6.3
|
||
|
||
Item {
|
||
property alias dia: diaDemo
|
||
|
||
Dialog {
|
||
id: diaDemo
|
||
title: qsTr("DemoDialog")
|
||
standardButtons: Dialog.Ok | Dialog.Cancel
|
||
|
||
onRejected: console.log("Cancel clicked")
|
||
}
|
||
}
|
||
```
|
||
|
||
注意这里使用的是 QtQuick.Controls 中的 Dialog，需要保持 main.cpp 中的 app 为 QGuiApplication 类型。
|
||
|
||
.pro 文件的相关字段如下：
|
||
|
||
```js
|
||
resources.files = main.qml \
|
||
DemoQml/Demo.qml
|
||
|
||
resources.prefix = /$${TARGET}
|
||
```
|
||
|
||
main.qml 文件内容如下：
|
||
|
||
```js
|
||
import QtQuick
|
||
import "./DemoQml"
|
||
|
||
Window {
|
||
id: window
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
title: qsTr("Hello World")
|
||
|
||
Demo {
|
||
id: compDemo
|
||
dia.onAccepted: {
|
||
console.log("clicked Ok button.")
|
||
}
|
||
}
|
||
|
||
Button {
|
||
anchors.fill: parent
|
||
text: qsTr("显示 Dialog")
|
||
onClicked: {
|
||
compDemo.dia.open()
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 10. QML 与 C++ 交互
|
||
|
||
QML 与 C++ 交互的主要实现方式是：
|
||
|
||
1. QML 访问 C++ 中声明的类型；
|
||
2. QML 访问 C++ 中创建的对象；
|
||
3. QML 调用 C++ 中的方法或发射信号；
|
||
4. QML 响应 C++ 中产生的信号；
|
||
5. C++ 访问 QML 对象。
|
||
|
||
QML 与 C++ 之间主要通过信号槽机制来传递消息。
|
||
|
||
### 10.1. QML 访问 C++ 中声明的类型
|
||
|
||
QML 使用 C++ 中声明的类型可以为类、结构体或枚举等。若需要将 C++ 类导出给 QML，则需要使用 qmlRegisterType() 方法进行注册：
|
||
|
||
```cpp
|
||
qmlRegisterType<Type>("package.Type", <version>, <sub-version>, "Type");
|
||
```
|
||
|
||
之后在 QML 中使用 C++ 类创建对象即可。若需要在 QML 中使用类中定义的枚举，格式如下：
|
||
|
||
```js
|
||
<类名>.<枚举值>
|
||
```
|
||
|
||
若 QML 需要使用 C++ 中声明的枚举类型，则该枚举需要使用 Q_ENUM() 进行修饰（必须放在声明之后）；若访问属性成员则需要使用 Q_PROPERTY() 进行修饰；若访问方法则该方法需要使用 Q_INVOKABLE() 来修饰。C++ 中的信号不需要特殊处理，QML 可直接访问。
|
||
|
||
若对象在 C++ 上下文中创建，并需要在 QML 中使用该对象，可以使用：
|
||
|
||
```cpp
|
||
QQmlApplicationEngine engine;
|
||
engine.rootContext()->setContextProperty("qmlObj", cObj);
|
||
```
|
||
|
||
将 C++ 对象注册到 QML 上下文环境中。
|
||
|
||
### 10.2. C++ 访问 QML 对象
|
||
|
||
在 QML 中为对象添加 objectName 属性后，在 C++ 中可使用：
|
||
|
||
```cpp
|
||
auto root = engine.rootObjects();
|
||
auto qmlObj = root.first()->findChild<QObject*>("object name");
|
||
```
|
||
|
||
查找该对象，再连接信号槽等。
|
||
|
||
大部分情况下在 QML 中访问 C++ 即可实现较完善的功能，QML 传递信息给 C++ 完全可以通过信号槽机制实现。除非需要在 C++ 中动态创建对象并连接到 QML 中的信号槽，否则没必要这样设计。
|
||
|
||
### 10.3. 通过信号槽传递自建类型
|
||
|
||
当使用信号槽机制时，需要注意一点：如果需要通过信号槽传递自建类型数据，需要使用 qRegisterMetaType() 方法进行注册。
|
||
|
||
```cpp
|
||
qRegisterMetaType<MyClass>("Myclass");
|
||
```
|
||
|
||
### 10.4. QML 与 C++ 交互综合示例
|
||
|
||
该示例包含以下文件：
|
||
|
||
- QmlDemo.por
|
||
- qml.qrc
|
||
- DemoDirect.h
|
||
- DemoDirect.cpp
|
||
- DemoJoint.h
|
||
- DemoJoint.cpp
|
||
- DemoIndirect.h
|
||
- DemoIndirect.cpp
|
||
- main.qml
|
||
- main.cpp
|
||
|
||
QmlDemo.por 内容如下：
|
||
|
||
```js
|
||
QT += quick widgets
|
||
|
||
# You can make your code fail to compile if it uses deprecated APIs.
|
||
# In order to do so, uncomment the following line.
|
||
#DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0x060000 # disables all the APIs deprecated before Qt 6.0.0
|
||
|
||
SOURCES += \
|
||
DemoDirect.cpp \
|
||
DemoIndirect.cpp \
|
||
DemoJoint.cpp \
|
||
main.cpp
|
||
|
||
RESOURCES += qml.qrc
|
||
|
||
# Additional import path used to resolve QML modules in Qt Creator's code model
|
||
QML_IMPORT_PATH =
|
||
|
||
# Additional import path used to resolve QML modules just for Qt Quick Designer
|
||
QML_DESIGNER_IMPORT_PATH =
|
||
|
||
# Default rules for deployment.
|
||
qnx: target.path = /tmp/$${TARGET}/bin
|
||
else: unix:!android: target.path = /opt/$${TARGET}/bin
|
||
!isEmpty(target.path): INSTALLS += target
|
||
|
||
HEADERS += \
|
||
DemoDirect.h \
|
||
DemoIndirect.h \
|
||
DemoJoint.h
|
||
```
|
||
|
||
qml.qrc 内容如下：
|
||
|
||
```xml
|
||
<RCC>
|
||
<qresource prefix="/">
|
||
<file>main.qml</file>
|
||
</qresource>
|
||
</RCC>
|
||
```
|
||
|
||
DemoDirect.h 内容如下
|
||
|
||
```cpp
|
||
#ifndef DEMODIRECT_H
|
||
#define DEMODIRECT_H
|
||
|
||
#include <QObject>
|
||
|
||
class DemoDirect : public QObject
|
||
{
|
||
Q_OBJECT
|
||
// 声明 cppStr 为只读属性. NOTIFY 信号是必须的.
|
||
Q_PROPERTY(QString cppStr READ readCppStr NOTIFY cppStrChanged)
|
||
public:
|
||
explicit DemoDirect(QObject *parent = nullptr);
|
||
|
||
// 使用 Q_INVOKABLE 向 QML 声明函数方法.
|
||
Q_INVOKABLE void writeCppStr(QString str);
|
||
Q_INVOKABLE QString readCppStr();
|
||
|
||
signals:
|
||
void cppStrChanged(QString str);
|
||
|
||
protected:
|
||
QString cppStr;
|
||
|
||
};
|
||
|
||
#endif // DEMODIRECT_H
|
||
```
|
||
|
||
DemoDirect.cpp 内容如下
|
||
|
||
```cpp
|
||
#include "DemoDirect.h"
|
||
#include <QDebug>
|
||
|
||
DemoDirect::DemoDirect(QObject *parent)
|
||
: QObject{parent}
|
||
{
|
||
cppStr = "Hello";
|
||
}
|
||
|
||
void DemoDirect::writeCppStr(QString str)
|
||
{
|
||
cppStr = str;
|
||
qDebug()<<"[CPP:DemoDirect:writeCppStr]srt="<<cppStr;
|
||
emit cppStrChanged(cppStr);
|
||
}
|
||
|
||
QString DemoDirect::readCppStr()
|
||
{
|
||
return cppStr;
|
||
}
|
||
```
|
||
|
||
DemoJoint.h 内容如下
|
||
|
||
```cpp
|
||
#ifndef DEMOJOINT_H
|
||
#define DEMOJOINT_H
|
||
|
||
#include <QThread>
|
||
#include <QSemaphore>
|
||
|
||
class DemoJoint : public QThread
|
||
{
|
||
Q_OBJECT
|
||
public:
|
||
enum DemoEnum {
|
||
DE_OPEN,
|
||
DE_READ,
|
||
DE_WRITE,
|
||
DE_CLOSE,
|
||
|
||
DE_OPEN_DONE,
|
||
DE_READ_DONE,
|
||
DE_WRITE_DONE,
|
||
DE_CLOSE_DONE
|
||
};
|
||
// 向 QML 声明 DemoEnum 类型.
|
||
Q_ENUM(DemoEnum)
|
||
|
||
explicit DemoJoint(QObject *parent = nullptr);
|
||
~DemoJoint();
|
||
|
||
signals:
|
||
// 从 QML 调用的信号, 信号不必使用 Q_INVOKABLE 进行显式声明.
|
||
void qml2Cpp(DemoJoint::DemoEnum op);
|
||
// 从 DemoIndirect 中发射该信号, QML 中响应该信号.
|
||
void cpp2Qml(DemoJoint::DemoEnum op);
|
||
|
||
protected:
|
||
class DemoIndirect* demoIndirect;
|
||
|
||
void run() override;
|
||
|
||
private:
|
||
QSemaphore initLock;
|
||
|
||
};
|
||
|
||
#endif // DEMOJOINT_H
|
||
```
|
||
|
||
DemoJoint.cpp 内容如下
|
||
|
||
```cpp
|
||
#include "DemoJoint.h"
|
||
#include "DemoIndirect.h"
|
||
|
||
DemoJoint::DemoJoint(QObject *parent)
|
||
: QThread{parent}
|
||
{
|
||
this->start();
|
||
initLock.acquire(1);
|
||
}
|
||
|
||
DemoJoint::~DemoJoint()
|
||
{
|
||
this->wait();
|
||
}
|
||
|
||
void DemoJoint::run()
|
||
{
|
||
this->setPriority(QThread::NormalPriority);
|
||
demoIndirect = new DemoIndirect(this, nullptr);
|
||
connect(this, &DemoJoint::qml2Cpp, demoIndirect, &DemoIndirect::onQml2Cpp, Qt::QueuedConnection);
|
||
initLock.release(1);
|
||
this->exec();
|
||
demoIndirect->deleteLater();
|
||
}
|
||
```
|
||
|
||
DemoIndirect.h 内容如下
|
||
|
||
```cpp
|
||
#ifndef DEMOINDIRECT_H
|
||
#define DEMOINDIRECT_H
|
||
|
||
#include <QObject>
|
||
#include "DemoJoint.h"
|
||
|
||
class DemoIndirect : public QObject
|
||
{
|
||
Q_OBJECT
|
||
public:
|
||
explicit DemoIndirect(DemoJoint* j, QObject *parent = nullptr);
|
||
|
||
public slots:
|
||
// 在 DemoJoint run() 方法中连接了该槽.
|
||
void onQml2Cpp(DemoJoint::DemoEnum op);
|
||
|
||
signals:
|
||
|
||
private:
|
||
DemoJoint* joint;
|
||
|
||
};
|
||
|
||
#endif // DEMOINDIRECT_H
|
||
```
|
||
|
||
DemoIndirect.cpp 内容如下
|
||
|
||
```cpp
|
||
#include "DemoIndirect.h"
|
||
#include <QDebug>
|
||
|
||
DemoIndirect::DemoIndirect(class DemoJoint* j, QObject *parent)
|
||
: QObject{parent}
|
||
{
|
||
joint = j;
|
||
}
|
||
|
||
void DemoIndirect::onQml2Cpp(DemoJoint::DemoEnum op)
|
||
{
|
||
qDebug()<<"[CPP:DemoIndirect:onQml2Cpp]op="<<op;
|
||
switch (op) {
|
||
case DemoJoint::DE_OPEN:
|
||
emit joint->cpp2Qml(DemoJoint::DE_OPEN_DONE);
|
||
break;
|
||
default:
|
||
emit joint->cpp2Qml(DemoJoint::DE_CLOSE_DONE);
|
||
break;
|
||
}
|
||
}
|
||
```
|
||
|
||
main.cpp 内容如下：
|
||
|
||
```cpp
|
||
#include <QApplication>
|
||
#include <QQmlApplicationEngine>
|
||
#include <QQmlContext>
|
||
#include "DemoJoint.h"
|
||
#include "DemoDirect.h"
|
||
|
||
int main(int argc, char *argv[])
|
||
{
|
||
// 注册 DemoDirect 类型, 否则无法在 QML 中使用 DemoDirect 创建对象.
|
||
qmlRegisterType<DemoDirect>("project.DemoDirect", 1, 0, "DemoDirect");
|
||
// 注册 DemoJoint 类型, 否则无法在 QML 中使用 DemoJoint.DemoEnum 类型.
|
||
qmlRegisterType<DemoJoint>("project.DemoJoint", 1, 0, "DemoJoint");
|
||
// 注册用于在信号槽中使用的类型.
|
||
qRegisterMetaType<DemoJoint::DemoEnum>("DemoJoint::DemoEnum");
|
||
|
||
#if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
|
||
QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
|
||
#endif
|
||
QApplication app(argc, argv);
|
||
|
||
// 在 C 上下文创建 demoJoint 对象.
|
||
DemoJoint* demoJoint = new DemoJoint();
|
||
|
||
QQmlApplicationEngine engine;
|
||
const QUrl url(QStringLiteral("qrc:/main.qml"));
|
||
QObject::connect(&engine, &QQmlApplicationEngine::objectCreated,
|
||
&app, [url](QObject *obj, const QUrl &objUrl) {
|
||
if (!obj && url == objUrl)
|
||
QCoreApplication::exit(-1);
|
||
}, Qt::QueuedConnection);
|
||
|
||
// 将 C 环境下的 demoJoint 注册到 QML 上下文中.
|
||
engine.rootContext()->setContextProperty("demoJoint", demoJoint);
|
||
engine.load(url);
|
||
|
||
return app.exec();
|
||
}
|
||
```
|
||
|
||
main.qml 内容如下：
|
||
|
||
```js
|
||
import QtQuick 2.12
|
||
import QtQuick.Window 2.12
|
||
import QtQuick.Controls 2.12
|
||
// 导入自定义包, 包名与版本号要与 C 环境下注册的一致.
|
||
import project.DemoDirect 1.0
|
||
import project.DemoJoint 1.0
|
||
|
||
Window {
|
||
width: 640
|
||
height: 480
|
||
visible: true
|
||
id: window
|
||
|
||
// 直接从 QML 环境下实例化 C 对象.
|
||
DemoDirect {
|
||
id: demoDirect
|
||
}
|
||
|
||
Text {
|
||
id: demoText
|
||
anchors.left: parent.left
|
||
anchors.right: parent.right
|
||
anchors.top: parent.top
|
||
anchors.rightMargin: 8
|
||
anchors.leftMargin: 8
|
||
anchors.topMargin: 8
|
||
// 显示 demoDirect 的 cppStr 属性值, 注意这是一个只读属性.
|
||
text: demoDirect.cppStr
|
||
}
|
||
|
||
Button {
|
||
id: demoBut
|
||
width: 64
|
||
height: 24
|
||
text: qsTr("信号测试")
|
||
anchors.left: parent.left
|
||
anchors.top: demoText.bottom
|
||
anchors.leftMargin: 8
|
||
anchors.topMargin: 8
|
||
|
||
onClicked: {
|
||
// 从 QML 环境中向 C 环境发送信号.
|
||
demoJoint.qml2Cpp(DemoJoint.DE_OPEN)
|
||
// 直接调用 C 方法.
|
||
demoDirect.writeCppStr("Demo")
|
||
}
|
||
}
|
||
|
||
// 使用 Connections 与 C 信号建立连接, 并处理 cpp2Qml() 信号.
|
||
Connections {
|
||
target: demoJoint
|
||
function onCpp2Qml(op) {
|
||
console.log("[QML:onCpp2Qml]op=", op)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 11. Windows 下 QML 程序的打包发布
|
||
|
||
Qt 提供了导出 Qt 环境变量的命令行脚本，比如“Qt 5.15.2 (MinGW 8.1.0 64-bit)”，运行该脚本可进入带有 Qt 环境变量的命令行界面，之后可通过如下命令打包程序（编译生成的可执行程序需要拷贝到\<Package Output Path\>）：
|
||
|
||
```bash
|
||
cd <Package Output Path>
|
||
windeployqt <Exe File> [--qmldir <Project QML File Path>]
|
||
```
|
||
|
||
Qt 自带的打包程序会添加额外的库，如果想进一步减小体积，可手动筛减。
|
||
|
||
## 12. 外部参考资料
|
||
|
||
1. [深入了解JS中的整数](https://www.jianshu.com/p/1ba45c3894ab)
|
||
2. [QML 中的信号与槽](https://blog.csdn.net/Love_XiaoQinEr/article/details/123746983)
|
||
3. [QML 信号与响应方法的总结](https://zhuanlan.zhihu.com/p/576316521)
|
||
4. [QML 控件类型：ScrollBar、ScrollIndicator](https://blog.csdn.net/kenfan1647/article/details/122522063)
|
||
5. [QML 类型：GridView](https://blog.csdn.net/kenfan1647/article/details/120761466)
|
||
6. [Qt Quick 常用元素：ComboBox(下拉列表) 与 ProgressBar(进度条)](https://www.cnblogs.com/linuxAndMcu/p/11949814.html)
|
||
7. [【QML Model-View】ListView-增删改查（二）](https://www.cnblogs.com/linuxAndMcu/p/13597106.html)
|
||
8. [关于 Q_ENUMS 和 Q_ENUM 的区别和用法](https://blog.csdn.net/lsylovezsl/article/details/108766437)
|
||
9. [C++ 共享枚举类型给 QML](https://www.cnblogs.com/linkyip/p/14462288.html)
|
||
10. [QML Connections: Implicitly defined onFoo properties in Connections are deprecated.](https://blog.csdn.net/weixin_43720622/article/details/112346039)
|
||
11. [QML 调用 C++ 方法](https://blog.csdn.net/woshouji1/article/details/121348179)
|
||
12. [Qml 与 C++ 交互3：Qml 的信号与 C++ 的槽函数连接](https://blog.csdn.net/tanxuan231/article/details/124990296)
|
||
13. [Qt-虚拟键盘](https://blog.csdn.net/qq_39175540/article/details/87972667)
|
||
14. [Qt5软键盘实现中文拼音输入法](https://blog.csdn.net/onlyshi/article/details/78408000)
|
||
15. [Qt6中加载自定义qml遇到的问题](https://blog.csdn.net/youyicc/article/details/124367513)
|
||
16. [QML控件类型：Dialog（Qt Quick Controls 模块）](https://blog.csdn.net/kenfan1647/article/details/123109241)
|