欢迎光临
我们一直在努力

Qt快速入门:C++ 扩展 QML 类型

一、为什么要用 C++ 扩展 QML?

场景举例:

  • 性能考虑:复杂计算用 C++ 更快
  • 复用代码:已有 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 会在控制台显示详细的错误信息
    • 仔细阅读错误信息,通常能直接定位问题
  • 逐步测试
    • 先测试简单的属性
    • 再测试简单的函数
    • 最后测试复杂的功能
    赞(0)
    未经允许不得转载:171主机测评 » Qt快速入门:C++ 扩展 QML 类型
    分享到: 更多 (0)

    评论 抢沙发

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址