一、为什么要用 C++ 扩展 QML?
场景举例:
简单理解:
- QML:负责界面,长得好看
- C++扩展:负责干活,能力强大
- 结合:让界面也能干重活
二、创建一个最简单的 C++ 类型
步骤 1:创建 C++ 类
// CppType.h 头文件
#pragma once
#include <QObject>
#include <QString>
class CppType : public QObject
{
Q_OBJECT // 必须添加这个宏!
public:
// 构造函数
explicit CppType(QObject *parent = nullptr);
// 声明一个属性(QML 可以访问)
Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
// 读取属性的函数
QString name() const;
// 修改属性的函数
void setName(const QString &name);
// 声明一个可以被 QML 调用的函数
Q_INVOKABLE void sayHello();
signals:
// 属性改变时发出的信号
void nameChanged();
private:
QString m_name; // 保存属性的变量
};
步骤 2:实现 C++ 类
// CppType.cpp 源文件
#include "CppType.h"
#include <QDebug>
CppType::CppType(QObject *parent)
: QObject(parent)
, m_name("默认名字") // 初始化属性
{
qDebug() << "CppType 被创建了!";
}
QString CppType::name() const
{
return m_name;
}
void CppType::setName(const QString &name)
{
// 如果新值和旧值一样,就不做任何事
if (m_name == name)
return;
m_name = name;
// 发出信号,告诉 QML 属性改变了
emit nameChanged();
qDebug() << "名字改为:" << name;
}
void CppType::sayHello()
{
qDebug() << "你好!我叫" << m_name;
}
三、在 QML 中使用自定义类型
步骤 1:注册 C++ 类型到 QML
// main.cpp
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QQmlContext>
#include "CppType.h" // 包含我们的自定义类型
int main(int argc, char *argv[])
{
QGuiApplication app(argc, argv);
QQmlApplicationEngine engine;
// 注册 C++ 类型到 QML
// 参数1:类名
// 参数2:QML 中的版本号(1.0表示版本1.0)
// 参数3:QML 中的模块名
// 参数4:QML 中的类型名
qmlRegisterType<CppType>("MyTypes", 1, 0, "CppType");
engine.load(QUrl("qrc:/main.qml"));
return app.exec();
}
步骤 2:在 QML 中使用
// main.qml
import QtQuick
import MyTypes 1.0 // 导入我们刚才注册的模块
Window {
width: 400
height: 300
visible: true
title: "使用自定义 C++ 类型"
// 创建我们的 C++ 类型实例
CppType {
id: myCppObject
// 设置属性(会自动调用 setName 函数)
name: "小明"
// 当 name 属性改变时(C++ 发出 nameChanged 信号)
onNameChanged: {
console.log("QML 收到:名字改变了!")
}
}
Column {
spacing: 10
anchors.centerIn: parent
Text {
text: "当前名字:" + myCppObject.name
font.pixelSize: 20
}
Button {
text: "调用 C++ 函数"
onClicked: {
// 调用 C++ 的函数
myCppObject.sayHello()
}
}
Button {
text: "修改名字"
onClicked: {
// 修改 C++ 的属性
myCppObject.name = "小红" + Math.random().toFixed(2)
}
}
}
}
四、属性的详细解释
Q_PROPERTY 宏的格式
Q_PROPERTY(类型 属性名 READ 读取函数 WRITE 写入函数 NOTIFY 信号名)
示例分解:
// 定义一个字符串属性
Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
| QString | 属性的类型 | 是 |
| name | QML 中使用的属性名 | 是 |
| READ name | 读取属性值的函数 | 是 |
| WRITE setName | 设置属性值的函数 | 可选 |
| NOTIFY nameChanged | 属性改变时发出的信号 | 可选 |
属性的不同类型:
1. 可读可写属性(最常用)
Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged)
2. 只读属性(不能修改)
Q_PROPERTY(int count READ count CONSTANT)
// 注意:使用 CONSTANT 就不要用 WRITE 和 NOTIFY
3. 使用 MEMBER 简化(不用写读写函数)
Q_PROPERTY(QString url MEMBER m_url NOTIFY urlChanged)
// m_url 是成员变量,Qt 会自动处理读写
五、让 C++ 函数可以被 QML 调用
使用 Q_INVOKABLE 宏
class MyClass : public QObject
{
Q_OBJECT
public:
// 普通的函数,QML 不能调用
void normalFunction();
// 添加 Q_INVOKABLE,QML 就能调用了
Q_INVOKABLE void qmlCallableFunction();
// 带参数的函数
Q_INVOKABLE int add(int a, int b);
// 带复杂参数的函数
Q_INVOKABLE QString processList(const QList<int> &numbers);
};
QML 中调用示例:
// 调用无参数函数
myObject.qmlCallableFunction()
// 调用带参数函数
var result = myObject.add(10, 20)
// 调用带复杂参数的函数
var list = [1, 2, 3, 4, 5]
var result = myObject.processList(list)
六、信号和槽(事件通知)
C++ 中定义信号:
class CppType : public QObject
{
Q_OBJECT
signals:
// 定义一个信号(不用实现)
void dataReady(const QString &data);
// 无参数信号
void somethingHappened();
public slots:
// 定义一个槽函数(可以被信号连接)
void handleData(const QString &data) {
qDebug() << "收到数据:" << data;
}
};
QML 中接收信号:
CppType {
id: myObject
// 方法1:使用 on信号名 语法
onDataReady: function(data) {
console.log("QML 收到数据:", data)
}
// 方法2:使用 Connections
Connections {
target: myObject
onSomethingHappened: {
console.log("有事情发生了!")
}
}
}
七、处理复杂数据类型
1. 列表/数组
// C++ 中
Q_INVOKABLE QList<int> getNumbers() {
return {1, 2, 3, 4, 5};
}
Q_INVOKABLE void processNumbers(const QList<int> &numbers) {
for (int num : numbers) {
qDebug() << num;
}
}
// QML 中调用
var numbers = myObject.getNumbers()
console.log("数字列表:", numbers)
myObject.processNumbers([10, 20, 30])
2. 键值对/对象
// C++ 中
Q_INVOKABLE QVariantMap getUserInfo() {
QVariantMap info;
info["name"] = "小明";
info["age"] = 20;
info["score"] = 95.5;
return info;
}
Q_INVOKABLE void printInfo(const QVariantMap &info) {
for (auto it = info.begin(); it != info.end(); ++it) {
qDebug() << it.key() << ":" << it.value();
}
}
// QML 中调用
var userInfo = myObject.getUserInfo()
console.log("用户信息:", userInfo)
myObject.printInfo({
"city": "北京",
"job": "程序员"
})
八、完整示例:计算器类
C++ 类定义:
// Calculator.h
#pragma once
#include <QObject>
class Calculator : public QObject
{
Q_OBJECT
Q_PROPERTY(double result READ result WRITE setResult NOTIFY resultChanged)
public:
explicit Calculator(QObject *parent = nullptr);
double result() const;
void setResult(double value);
// QML 可以调用的计算函数
Q_INVOKABLE void add(double value);
Q_INVOKABLE void subtract(double value);
Q_INVOKABLE void multiply(double value);
Q_INVOKABLE void divide(double value);
signals:
void resultChanged();
void errorOccurred(const QString &message);
private:
double m_result;
};
C++ 类实现:
// Calculator.cpp
#include "Calculator.h"
#include <QDebug>
Calculator::Calculator(QObject *parent)
: QObject(parent)
, m_result(0)
{
}
double Calculator::result() const
{
return m_result;
}
void Calculator::setResult(double value)
{
if (qFuzzyCompare(m_result, value))
return;
m_result = value;
emit resultChanged();
}
void Calculator::add(double value)
{
m_result += value;
emit resultChanged();
qDebug() << "加法计算,结果:" << m_result;
}
void Calculator::subtract(double value)
{
m_result -= value;
emit resultChanged();
qDebug() << "减法计算,结果:" << m_result;
}
void Calculator::multiply(double value)
{
m_result *= value;
emit resultChanged();
qDebug() << "乘法计算,结果:" << m_result;
}
void Calculator::divide(double value)
{
if (value == 0) {
emit errorOccurred("除数不能为零!");
return;
}
m_result /= value;
emit resultChanged();
qDebug() << "除法计算,结果:" << m_result;
}
QML 界面:
import QtQuick
import QtQuick.Controls
Window {
width: 300
height: 400
visible: true
// 导入我们的计算器类型
Calculator {
id: calculator
onResultChanged: {
resultText.text = "结果: " + calculator.result
}
onErrorOccurred: function(message) {
errorText.text = "错误: " + message
}
}
Column {
spacing: 10
anchors.centerIn: parent
Text {
id: resultText
text: "结果: 0"
font.pixelSize: 24
}
Text {
id: errorText
color: "red"
font.pixelSize: 16
}
Button {
text: "+5"
onClicked: calculator.add(5)
}
Button {
text: "-3"
onClicked: calculator.subtract(3)
}
Button {
text: "×2"
onClicked: calculator.multiply(2)
}
Button {
text: "÷2"
onClicked: calculator.divide(2)
}
Button {
text: "清零"
onClicked: calculator.result = 0
}
}
}
九、常见问题和调试技巧
问题 1:QML 找不到我的类型
// 检查是否正确注册
qmlRegisterType<MyType>("MyModule", 1, 0, "MyType");
// 检查 QML 是否正确导入
import MyModule 1.0
问题 2:属性修改不生效
// 检查是否发出了信号
void setValue(int newValue) {
if (m_value == newValue) // 检查值是否真的变了
return;
m_value = newValue;
emit valueChanged(); // 必须发出信号!
}
问题 3:函数调用失败
// 检查是否添加了 Q_INVOKABLE
Q_INVOKABLE void myFunction(); // 正确
void myFunction(); // 错误:QML 不能调用
调试技巧:
qDebug() << "函数被调用,参数:" << parameter;
- QML 会在控制台显示详细的错误信息
- 仔细阅读错误信息,通常能直接定位问题
- 先测试简单的属性
- 再测试简单的函数
- 最后测试复杂的功能


![P11246 [GESP202409 六级] 小杨和整数拆分-171主机测评](https://www.171host.com/wp-content/uploads/2026/11/20261108100631-6af049a75855c-220x150.png)

