使用 C++ 编写 QML 扩展

该 Qt Qml 模块提供了一组 API，用于通过 C++ 扩展来扩展 QML。您可以编写扩展来添加自己的 QML 类型、扩展现有的 Qt 类型，或者调用普通 QML 代码无法访问的 C/C++ 函数。

本教程演示了如何使用 C++ 编写包含核心 QML 功能（包括属性、信号和绑定）的 QML 扩展，同时还介绍了如何通过插件部署扩展。

本教程涉及的许多主题在《概述 - QML 与 C++ 集成》及其文档子主题中都有更详细的说明。特别是，您可能会对“将 C++ 类的属性暴露给 QML”和“从 C++ 定义 QML 类型”这两个子主题感兴趣。

打开教程源代码

本教程中的代码作为 Qt 源代码的一部分提供。如果您通过 Qt 开发套件（Qt Online Installer ）安装了 Qt，可以在 Qt 安装目录下的 Examples/Qt-6.12.0/qml/tutorials/extending-qml/ 路径中找到源代码。

从零开始创建项目

此外，您还可以通过从零开始创建源代码来跟随本教程：对于每个章节，请使用Qt Quick 的“应用程序”模板创建一个新项目：

如果您使用Qt Creator ，请按照Qt Creator ：创建Qt Quick 应用程序中的说明进行操作。
如果您使用的是Qt Extension for Visual Studio Code ，请按照Qt Extension for Visual Studio Code 中的说明操作：创建应用程序。

然后，通过调整和扩展生成的骨架代码来继续操作。

第 1 章：创建新类型

extending-qml/chapter1-basics

扩展 QML 时的一项常见任务是提供一种新的 QML 类型，该类型支持超出内置类型所提供范围的某些自定义功能 Qt Quick types所提供的功能之外的某些自定义功能。例如，这可以用来实现特定的数据模型，或者提供具有自定义绘制和描绘功能的类型，或者访问通过内置 QML 功能无法访问的系统功能（如网络编程）。

在本教程中，我们将演示如何利用Qt Quick 模块中的C++类来扩展QML。最终结果将是一个简单的饼图显示，它由几个自定义QML类型实现，这些类型通过绑定和信号等QML特性相互连接，并通过插件提供给QML Runtime。

首先，让我们创建一个名为“PieChart”的新 QML 类型，它具有两个属性：名称和颜色。我们将将其置于一个名为“Charts”的可导入类型命名空间中，版本号为 1.0。

我们希望该PieChart 类型能在QML中以如下方式使用：

import Charts

PieChart {
    width: 100; height: 100
    name: "A simple pie chart"
    color: "red"
}

注意：您 可能需要启用QML Language Server 及其语义高亮功能（在Qt Creator或 Qt Extension for Visual Studio Code 中），才能让Qt Creator 正确高亮显示PieChart 。

为此，我们需要一个 C++ 类来封装这种PieChart 类型及其属性。由于 QML 广泛使用了 Qt的元对象系统，因此这个新类必须：

继承自QObject
使用Q_PROPERTY 宏声明其属性

类声明

以下是在piechart.h 中定义的PieChart 类：

#include <QtQuick/QQuickPaintedItem>
#include <QColor>

class PieChart : public QQuickPaintedItem
{
    Q_OBJECT
    Q_PROPERTY(QString name READ name WRITE setName FINAL)
    Q_PROPERTY(QColor color READ color WRITE setColor FINAL)
    QML_ELEMENT

public:
    PieChart(QQuickItem *parent = nullptr);

    QString name() const;
    void setName(const QString &name);

    QColor color() const;
    void setColor(const QColor &color);

    void paint(QPainter *painter) override;

private:
    QString m_name;
    QColor m_color;
};

该类继承自QQuickPaintedItem ，是因为我们希望重写QQuickPaintedItem::paint()方法，以使用QPainter API执行绘制操作。如果该类仅表示某种数据类型，且并非实际需要显示的项，则可以直接继承自QObject 。或者，如果我们希望扩展现有基于QObject 的类的功能，则可以继承自该类。此外，如果我们要创建一个无需使用QPainter API执行绘制操作的可视化项，只需继承QQuickItem 类即可。

PieChart 类通过Q_PROPERTY 宏定义了name 和color 这两个属性，并重写了QQuickPaintedItem::paint()方法。PieChart 类通过QML_ELEMENT 宏进行注册，以便在QML中使用。如果未注册该类，App.qml 将无法创建PieChart 。

qmake 设置

为了使注册生效，需在项目文件的 `CONFIG ` 中添加 `qmltypes ` 选项，并指定 `QML_IMPORT_NAME ` 和 `QML_IMPORT_MAJOR_VERSION `：

CONFIG += qmltypes
QML_IMPORT_NAME = Charts
QML_IMPORT_MAJOR_VERSION = 1

此外，还需要手动添加一个qmldir文件来创建QML 模块。

module Charts
typeinfo chapter1-basics.qmltypes
depends QtQuick
prefer :/qt/qml/Charts/
App 254.0 App.qml

CMake 配置

若要在使用 CMake 时使注册生效，请使用qt_add_qml_module()命令：

qt_add_qml_module(chapter1-basics
    URI Charts
    QML_FILES App.qml
    DEPENDENCIES QtQuick
)

qt_add_qml_module()API 会为 QML 模块自动生成一个qmldir 文件。

类实现

piechart.cpp 中的类实现只需根据需要设置并返回m_name 和m_color 的值，并实现paint() 方法以绘制一个简单的饼图：

PieChart::PieChart(QQuickItem *parent)
    : QQuickPaintedItem(parent)
{
}
...
void PieChart::paint(QPainter *painter)
{
    QPen pen(m_color, 2);
    painter->setPen(pen);
    painter->setRenderHints(QPainter::Antialiasing, true);
    painter->drawPie(boundingRect().adjusted(1, 1, -1, -1), 90 * 16, 290 * 16);
}

QML 使用方法

既然我们已经定义了PieChart 类型，接下来将在 QML 中使用它。App.qml 文件会创建一个PieChart 项，并使用标准的 QMLText 项显示饼图的详细信息：

import Charts
import QtQuick

Item {
    width: 300; height: 200

    PieChart {
        id: aPieChart
        anchors.centerIn: parent
        width: 100; height: 100
        name: "A simple pie chart"
        color: "red"
    }

    Text {
        anchors { bottom: parent.bottom; horizontalCenter: parent.horizontalCenter; bottomMargin: 20 }
        text: aPieChart.name
    }
}

请注意，尽管在 QML 中颜色是以字符串形式指定的，但系统会将其自动转换为QColor 对象，以供 PieChart 的color 属性使用。其他多种值类型也支持自动转换。例如，字符串“640x480”可以自动转换为QSize 值。

我们还将创建一个 C++ 应用程序，该应用程序使用QQuickView 来运行并显示App.qml 。

以下是应用程序main.cpp ：

#include "piechart.h"
#include <QtQuick/QQuickView>
#include <QGuiApplication>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQuickView view;
    view.setResizeMode(QQuickView::SizeRootObjectToView);
    view.loadFromModule("Charts", "App");
    view.show();
    return QGuiApplication::exec();
}

项目构建

要构建该项目，我们需要包含相关文件、链接库，并为所有向 QML 公开的类型定义一个名为“Charts”且版本号为 1.0 的类型命名空间。

使用 qmake：

QT += qml quick

CONFIG += qmltypes
QML_IMPORT_NAME = Charts
QML_IMPORT_MAJOR_VERSION = 1

HEADERS += piechart.h
SOURCES += piechart.cpp \
           main.cpp

RESOURCES += chapter1-basics.qrc

DESTPATH = $$[QT_INSTALL_EXAMPLES]/qml/tutorials/extending-qml/chapter1-basics
target.path = $$DESTPATH
INSTALLS += target

使用 CMake：

# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

cmake_minimum_required(VERSION 3.16)
project(chapter1-basics LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml Quick)

qt_standard_project_setup(REQUIRES 6.8)

qt_add_executable(chapter1-basics
    main.cpp
    piechart.cpp piechart.h
)

set_target_properties(chapter1-basics PROPERTIES
    WIN32_EXECUTABLE TRUE
    MACOSX_BUNDLE TRUE
)

target_link_libraries(chapter1-basics PUBLIC
    Qt6::Core
    Qt6::Gui
    Qt6::Qml
    Qt6::Quick
)
qt_add_qml_module(chapter1-basics
    URI Charts
    QML_FILES App.qml
    DEPENDENCIES QtQuick
)
install(TARGETS chapter1-basics
    BUNDLE  DESTINATION .
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

qt_generate_deploy_qml_app_script(
    TARGET chapter1-basics
    OUTPUT_SCRIPT deploy_script
    NO_UNSUPPORTED_PLATFORM_ERROR
    DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
)
install(SCRIPT ${deploy_script})

现在我们可以构建并运行该应用程序：

应用程序根据饼图类型的属性创建饼图

注意：您 可能会看到一条警告“表达式……依赖于不可绑定的属性：PieChart::name”。这是因为我们为可写属性name 添加了绑定，但尚未为其定义notify信号。因此，如果name 的值发生变化，QML引擎将无法更新该绑定。后续章节将解决此问题。

第 2 章：连接到 C++ 方法和信号

extending-qml/chapter2-methods

假设我们希望PieChart 拥有一个“clearChart()”方法，该方法可清除图表并随后发出“chartCleared”信号。此时，我们的App.qml 便能像这样调用clearChart() 并接收chartCleared() 信号：

import Charts
import QtQuick

Item {
    width: 300; height: 200

    PieChart {
        id: aPieChart
        anchors.centerIn: parent
        width: 100; height: 100
        color: "red"

        onChartCleared: console.log("The chart has been cleared")
    }

    MouseArea {
        anchors.fill: parent
        onClicked: aPieChart.clearChart()
    }

    Text {
        anchors { bottom: parent.bottom; horizontalCenter: parent.horizontalCenter; bottomMargin: 20 }
        text: "Click anywhere to clear the chart"
    }
}

用户可以点击应用程序窗口的任意位置来清除图表。这将调用“Clear Chart”方法

为此，我们在 C++ 类中添加了clearChart() 方法和chartCleared() 信号：

class PieChart : public QQuickPaintedItem
{
    ...
public:
    ...
    Q_INVOKABLE void clearChart();

signals:
    void chartCleared();
    ...
};

使用Q_INVOKABLE 可使clearChart() 方法对 Qt 元对象系统可用，进而对 QML 可用。

注意：您 也可以将该方法声明为 Qt 槽，而无需使用 `Q_INVOKABLE`，因为 public 和 protected 槽也可以从 QML 中调用（无法调用 private 槽）。

clearChart() 方法将颜色更改为Qt::transparent ，重新绘制图表，然后发出chartCleared() 信号：

void PieChart::clearChart()
{
    setColor(QColor(Qt::transparent));
    update();

    emit chartCleared();
}

现在，当我们运行应用程序并点击窗口时，饼图会消失，应用程序会输出：

qml: The chart has been cleared

第 3 章：添加属性绑定

extending-qml/chapter3-bindings

属性绑定是 QML 的一项强大功能，它允许不同类型的值自动同步。当属性值发生变化时，它会利用信号通知并更新其他类型的值。

让我们为color 属性启用属性绑定。这意味着如果我们有如下代码：

import Charts
import QtQuick

Item {
    width: 300; height: 200

    Row {
        anchors.centerIn: parent
        spacing: 20

        PieChart {
            id: chartA
            width: 100; height: 100
            color: "red"
        }

        PieChart {
            id: chartB
            width: 100; height: 100
            color: chartA.color
        }
    }

    MouseArea {
        anchors.fill: parent
        onClicked: { chartA.color = "blue" }
    }

    Text {
        anchors { bottom: parent.bottom; horizontalCenter: parent.horizontalCenter; bottomMargin: 20 }
        text: "Click anywhere to change the chart color"
    }
}

饼图 B 的颜色属性与饼图 A 的颜色属性绑定在一起。

“color: chartA.color”语句将chartB 的color 值与chartA 的color 绑定。每当chartA 的color 值发生变化时，chartB 的color 值就会更新为相同的值。当点击窗口时，MouseArea 中的onClicked 处理程序会更改chartA 的颜色，从而将两个图表的颜色都更改为蓝色。

为color 属性启用属性绑定非常简单。我们在其Q_PROPERTY() 声明中添加NOTIFY功能，以指示每当值发生变化时，都会发出“colorChanged”信号。

class PieChart : public QQuickPaintedItem
{
    ...
    Q_PROPERTY(QColor color READ color WRITE setColor NOTIFY colorChanged FINAL)
public:
    ...
signals:
    void colorChanged();
    ...
};

然后，我们在setColor() 中发射该信号：

void PieChart::setColor(const QColor &color)
{
    if (color != m_color) {
        m_color = color;
        update();   // repaint with the new color
        emit colorChanged();
    }
}

对于setColor() 而言，在发出colorChanged() 之前，务必先检查颜色值是否确实发生了变化，这一点至关重要。这既能确保信号不会被不必要地发出，也能防止其他类型在响应值变化时导致循环。

绑定在 QML 中至关重要。如果属性能够实现，您应始终为其添加 NOTIFY 信号，以便这些属性可在绑定中使用。无法进行绑定的属性无法自动更新，在 QML 中也无法灵活使用。此外，由于绑定在 QML 中的调用频率极高且被广泛依赖，如果未实现绑定，您的自定义 QML 类型的使用者可能会遇到意料之外的行为。

第 4 章：使用自定义属性类型

extending-qml/chapter4-customPropertyTypes

PieChart 类型目前包含一个字符串类型的属性和一个颜色类型的属性。它还可以拥有许多其他类型的属性。例如，它可以有一个 int 类型的属性，用于存储每个图表的标识符：

// C++
class PieChart : public QQuickPaintedItem
{
    Q_PROPERTY(int chartId READ chartId WRITE setChartId NOTIFY chartIdChanged)
    ...

public:
    void setChartId(int chartId);
    int chartId() const;
    ...

signals:
    void chartIdChanged();
};

// QML
PieChart {
    ...
    chartId: 100
}

除了 `int` 之外，我们还可以使用其他各种属性类型。许多 Qt 数据类型（如 `QColor`、`QSize ` 和 `QRect `）在 QML 中都得到了自动支持。（完整列表请参阅《QML 与 C++ 之间的数据类型转换》文档。）

如果我们要创建一个 QML 默认不支持其类型的属性，则需要向 QML 引擎注册该类型。

例如，让我们将property 的用法替换为一种名为“PieSlice”的类型，该类型具有color 属性。我们不再直接赋色，而是赋一个PieSlice 值，该值本身包含一个color ：

import Charts
import QtQuick

Item {
    width: 300; height: 200

    PieChart {
        id: chart
        anchors.centerIn: parent
        width: 100; height: 100

        pieSlice: PieSlice {
            anchors.fill: parent
            color: "red"
        }
    }

    Component.onCompleted: console.log("The pie is colored " + chart.pieSlice.color)
}

与PieChart 类似，这个新的PieSlice 类型继承自QQuickPaintedItem ，并使用Q_PROPERTY()声明其属性：

class PieSlice : public QQuickPaintedItem
{
    Q_OBJECT
    Q_PROPERTY(QColor color READ color WRITE setColor FINAL)
    QML_ELEMENT

public:
    PieSlice(QQuickItem *parent = nullptr);

    QColor color() const;
    void setColor(const QColor &color);

    void paint(QPainter *painter) override;

private:
    QColor m_color;
};

要在PieChart 中使用它，我们需要修改color 的属性声明及相关方法签名：

class PieChart : public QQuickItem
{
    Q_OBJECT
    Q_PROPERTY(PieSlice* pieSlice READ pieSlice WRITE setPieSlice FINAL)
    ...
public:
    ...
    PieSlice *pieSlice() const;
    void setPieSlice(PieSlice *pieSlice);
    ...
};

在实现setPieSlice() 时，有一点需要注意。PieSlice 是一个视觉项，因此必须通过QQuickItem::setParentItem() 将其设置为PieChart 的子项，以便PieChart 在绘制其内容时知道要渲染此子项：

void PieChart::setPieSlice(PieSlice *pieSlice)
{
    m_pieSlice = pieSlice;
    pieSlice->setParentItem(this);
}

与PieChart 类型类似，PieSlice 类型也必须通过QML_ELEMENT 向QML进行导出。

class PieSlice : public QQuickPaintedItem
{
    Q_OBJECT
    Q_PROPERTY(QColor color READ color WRITE setColor FINAL)
    QML_ELEMENT

public:
    PieSlice(QQuickItem *parent = nullptr);

    QColor color() const;
    void setColor(const QColor &color);

    void paint(QPainter *painter) override;

private:
    QColor m_color;
};
    ...

与PieChart 类似，我们将“Charts”类型命名空间（版本 1.0）添加到构建文件中：

使用 qmake：

QT += qml quick

CONFIG += qmltypes
QML_IMPORT_NAME = Charts
QML_IMPORT_MAJOR_VERSION = 1

HEADERS += piechart.h \
           pieslice.h
SOURCES += piechart.cpp \
           pieslice.cpp \
           main.cpp

RESOURCES += chapter4-customPropertyTypes.qrc

DESTPATH = $$[QT_INSTALL_EXAMPLES]/qml/tutorials/extending-qml/chapter4-customPropertyTypes
target.path = $$DESTPATH
INSTALLS += target

使用 CMake：

    ...
qt_add_executable(chapter4-customPropertyTypes
    main.cpp
    piechart.cpp piechart.h
    pieslice.cpp pieslice.h
)
qt_add_qml_module(chapter4-customPropertyTypes
    URI Charts
    QML_FILES App.qml
    DEPENDENCIES QtQuick
)
    ...

第 5 章：使用列表属性类型

extending-qml/chapter5-listproperties

目前，PieChart 只能包含一个PieSlice 。理想情况下，一个图表应包含多个切片，且具有不同的颜色和大小。为此，我们可以定义一个slices 属性，该属性接受一个PieSlice 项的列表：

pragma ComponentBehavior: Bound
import Charts
import QtQuick

Item {
    width: 300; height: 200

    PieChart {
        id: chart
        anchors.centerIn: parent
        width: 100; height: 100

        component Slice: PieSlice {
            parent: chart
            anchors.fill: parent
        }

        slices: [
            Slice {
                color: "red"
                fromAngle: 0
                angleSpan: 110
            },
            Slice {
                color: "black"
                fromAngle: 110
                angleSpan: 50
            },
            Slice {
                color: "blue"
                fromAngle: 160
                angleSpan: 100
            }
        ]
    }
}

slices 属性接受一个由饼图扇区项组成的列表。每个 pieslice 项用于设置每个饼图扇区的位置角度和颜色。

为此，我们将PieChart 中的pieSlice 属性替换为slices 属性，并将其声明为QQmlListProperty 类型。QQmlListProperty 类支持在面向QML的类型中创建列表属性。我们将pieSlice() 函数替换为slices() 函数，该函数返回一个切片列表。我们还使用QList 将内部切片列表存储为m_slices ：

class PieChart : public QQuickItem
{
    Q_OBJECT
    Q_PROPERTY(QQmlListProperty<PieSlice> slices READ slices FINAL)
    ...
public:
    ...
    QQmlListProperty<PieSlice> slices();

private:
    QString m_name;
    QList<PieSlice *> m_slices;
};

尽管slices 属性没有关联的WRITE 函数，但由于QQmlListProperty 的工作原理，它仍然可以被修改。在PieChart 的实现中，我们实现了PieChart::slices() 以返回一个QQmlListProperty 值：

QQmlListProperty<PieSlice> PieChart::slices()
{
    return QQmlListProperty<PieSlice>(this, &m_slices);
}

这会合成必要的函数，以便从 QML 与列表进行交互。生成的QQmlListProperty 是一个列表视图。此外，您也可以手动为列表提供单独的访问函数。如果您的列表不是QList ，或者您希望限制或以其他方式自定义 QML 对列表的访问，则必须这样做。但在大多数情况下，使用接受QList 指针的构造函数是最安全且最简便的选择。

PieSlice 类也已进行修改，新增了fromAngle 和angleSpan 属性，并根据这些值绘制切片。如果您已阅读本教程的前几页，这将是一个简单的修改，因此此处不再展示代码。

第 6 章：编写扩展插件

extending-qml/chapter6-plugins

目前，`PieChart ` 和 `PieSlice ` 类型由 `App.qml` 使用，该控件通过 C++ 应用程序中的 `QQuickView ` 进行显示。使用我们的 QML 扩展的另一种方法是创建一个插件库，使其作为新的 QML 导入模块供 QML 引擎使用。这样，PieChart 和PieSlice 这两种类型就可以注册到一个类型命名空间中，任何 QML 应用程序都可以导入该命名空间，而不再将这些类型仅限于由某个特定应用程序使用。

创建插件的具体步骤详见《为 QML 创建 C++ 插件》。首先，我们创建一个名为ChartsPlugin 的插件类。该类继承自QQmlEngineExtensionPlugin ，并使用Q_PLUGIN_METADATA() 宏将插件注册到 Qt 元对象系统中。

以下是chartsplugin.h 中ChartsPlugin 的定义：

#include <QQmlEngineExtensionPlugin>

class ChartsPlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
};

然后，我们配置构建文件，将该项目定义为插件库。

使用 qmake：

TEMPLATE = lib
CONFIG += plugin qmltypes
QT += qml quick

QML_IMPORT_NAME = Charts
QML_IMPORT_MAJOR_VERSION = 1

TARGET = $$qtLibraryTarget(chartsplugin)

HEADERS += piechart.h \
           pieslice.h \
           chartsplugin.h

SOURCES += piechart.cpp \
           pieslice.cpp

DESTPATH=$$[QT_INSTALL_EXAMPLES]/qml/tutorials/extending-qml/chapter6-plugins/$$QML_IMPORT_NAME

target.path=$$DESTPATH
qmldir.files=$$PWD/qmldir
qmldir.path=$$DESTPATH
INSTALLS += target qmldir

CONFIG += install_ok  # Do not cargo-cult this!

OTHER_FILES += qmldir

# Copy the qmldir file to the same folder as the plugin binary
cpqmldir.files = qmldir
cpqmldir.path = .
COPIES += cpqmldir

使用 CMake：

# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

qt6_policy(SET QTP0001 NEW)
qt6_add_qml_module(chartsplugin
    URI "Charts"
    PLUGIN_TARGET chartsplugin
    DEPENDENCIES QtQuick
)

target_sources(chartsplugin PRIVATE
    piechart.cpp piechart.h
    pieslice.cpp pieslice.h
)

target_link_libraries(chartsplugin PRIVATE
    Qt6::Core
    Qt6::Gui
    Qt6::Qml
    Qt6::Quick
)

install(TARGETS chartsplugin
    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}/Charts"
    LIBRARY DESTINATION "${CMAKE_INSTALL_BINDIR}/Charts"
)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/qmldir
    DESTINATION "${CMAKE_INSTALL_BINDIR}/Charts"
)

在 Windows 或 Linux 上构建此示例时，Charts 目录将位于使用我们新导入模块的应用程序的同一层级。这样，QML 引擎就能找到我们的模块，因为 QML 导入的默认搜索路径包含应用程序可执行文件的目录。在 macOS 上，插件二进制文件会被复制到应用程序包中的 `Contents/PlugIns ` 目录下。使用 qmake 时，该路径在 `chapter6-plugins/app.pro` 中设置：

macos:!qtConfig(static) {
    charts.files = $$OUT_PWD/Charts
    charts.path = Contents/PlugIns
    QMAKE_BUNDLE_DATA += charts
}

为此，我们还需要在main.cpp 中将此位置添加为QML 导入路径：

    QQuickView view;
    ...

当有多个应用程序使用相同的 QML 导入时，定义自定义导入路径也很有用。

.pro 文件还包含额外的“魔法”，以确保模块定义的 qmldir 文件始终被复制到与插件二进制文件相同的位置。

qmldir 文件声明了模块名称以及该模块提供的插件：

module Charts
optional plugin chartsplugin
typeinfo plugins.qmltypes
depends QtQuick
prefer :/qt/qml/Charts/

现在，我们拥有了一个可导入到任何应用程序中的 QML 模块，前提是 QML 引擎知道如何找到它。示例中包含一个可执行文件，该文件会加载 `App.qml`，其中使用了 `import Charts 1.0 ` 语句。此外，您还可以使用qml 工具加载 QML 文件，将导入路径设置为当前目录，以便其找到 `qmldir ` 文件：

qml -I . App.qml

“Charts”模块将被 QML 引擎加载，该模块提供的类型可在任何导入该模块的 QML 文档中使用。

第 7 章：总结

在本教程中，我们演示了创建 QML 扩展的基本步骤：

通过继承 `QObject ` 类来定义新的 QML 类型，并使用 `QML_ELEMENT ` 或 `QML_NAMED_ELEMENT()` 进行注册
使用 `Q_INVOKABLE ` 或 Qt 槽添加可调用方法，并使用 `onSignal ` 语法连接到 Qt 信号
通过定义NOTIFY信号来添加属性绑定
如果内置类型不够用，请定义自定义属性类型
使用QQmlListProperty
通过定义 Qt 插件并编写qmldir文件来创建插件库

《QML 与 C++ 集成概述》文档介绍了可添加到 QML 扩展中的其他有用功能。例如，我们可以使用默认属性，从而无需使用 `slices ` 属性即可添加切片：

PieChart {
    PieSlice { ... }
    PieSlice { ... }
    PieSlice { ... }
}

或者利用属性值源不时随机添加和移除切片：

PieChart {
    PieSliceRandomizer on slices {}
}

注意：若要 继续学习 QML 扩展及其功能，请参阅《使用 C++ 编写高级 QML 扩展》教程。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.