QML和C++之间的数据类型转换

在 QML 和 C++ 之间交换数据值时，QML 引擎会将它们转换为适合在 QML 或 C++ 中使用的正确数据类型。这要求交换的数据属于引擎可识别的类型。

QML 引擎为大量 Qt C++ 数据类型提供内置支持。此外，自定义 C++ 类型可以在 QML 类型系统中注册，以使它们可用于引擎。

一、数据所有权

当数据从 C++ 传输到 QML 时，数据的所有权始终属于 C++。唯一的例外是当从显式 C++ 方法调用返回 QObject 时：在这种情况下，QML 引擎假定对象的所有权，除非调用了QQmlEngine::setObjectOwnership(QQmlEngine::CppOwnership) 将对象的所有权显式设置为保留在 C++ 中。

此外，QML 引擎尊重 Qt C++ 对象的正常 QObject 父所有权语义，并且永远不会删除具有父对象的 QObject 实例。

二、基本 Qt 数据类型

默认情况下，QML 识别以下 Qt 数据类型，当从 C++ 传递到 QML 时，它们会自动转换为相应的 QML 基本类型，反之亦然：

bool — bool
unsigned int, int — int
double — double
float, qreal — real
QString — string
QUrl — url
QColor — color
QFont — font
QDateTime — date
QPoint, QPointF — point
QSize, QSizeF — size
QRect, QRectF — rect
QMatrix4x4 — matrix4x4
QQuaternion — quaternion
QVector2D, QVector3D, QVector4D — vector2d, vector3d, vector4d
用 Q_ENUM() 或 Q_ENUMS() 声明的枚举 — enumeration

Qt GUI 模块提供的类，例如 QColor、QFont、QQuaternion 和 QMatrix4x4，仅当包含 Qt Quick 模块时才可从 QML 获得。

为方便起见，许多这些类型可以在 QML 中通过字符串值或 QtQml::Qt 对象提供的相关方法指定。例如，Image::sourceSize 属性是 size 类型（它会自动转换为 QSize 类型），并且可以由格式化为“widthxheight”的字符串值或 Qt.size() 函数指定：

Item 
{
    Image { sourceSize: "100x200" }
    Image { sourceSize: Qt.size(100, 200) }
}

三、QObject 派生类型

任何 QObject 派生类都可以用作 QML 和 C++ 之间数据交换的类型，前提是该类已在 QML 类型系统中注册。

QML 引擎允许注册可实例化和不可实例化的类型。一旦一个类被注册为 QML 类型，它就可以用作在 QML 和 C++ 之间交换数据的数据类型。

四、Qt 和 JavaScript 类型之间的转换

在 QML 和 C++ 之间传输数据时，QML 引擎内置支持将许多 Qt 类型转换为相关的 JavaScript 类型，反之亦然。

4.1、QVariantList 和 QVariantMap 到 JavaScript 数组和对象

QML 引擎提供 QVariantList （QList<QVariant>）和 JavaScript 数组之间以及 QVariantMap（QMap<QString, QVariant>）和 JavaScript 对象之间的自动类型转换。

// MyItem.qml
Item 
{
    function readValues(anArray, anObject) 
    {
        for (var i=0; i<anArray.length; i++)
            console.log("Array item:", anArray[i])

        for (var prop in anObject) 
        {
            console.log("Object item:", prop, "=", anObject[prop])
        }
    }
}

// C++
QQuickView view(QUrl::fromLocalFile("MyItem.qml"));

QVariantList list;
list << 10 << QColor(Qt::green) << "bottles";

QVariantMap map;
map.insert("language", "QML");
map.insert("released", QDate(2010, 9, 21));

QMetaObject::invokeMethod(view.rootObject(), "readValues",
                          Q_ARG(QVariant, QVariant::fromValue(list)),
                          Q_ARG(QVariant, QVariant::fromValue(map)));

输出：

Array item: 10

Array item: #00ff00

Array item: bottles

Object item: language = QML

Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST)

注意，C++ 类型的 QVariantList 和 QVariantMap 属性存储为值，不能由 QML 代码更改。只能替换整个Map或List，而不能操作其内容。例，以下代码不起作用：

MyListExposingItem 
{
   list: [1, 2, 3]
   Component.onCompleted: list[0] = 10
}

MyListExposingItem 
{
   list: [1, 2, 3]
   Component.onCompleted: list = [10, 2, 3]
}

4.2、QDateTime 到 JavaScript 日期

QML 引擎提供 QDateTime 值和 JavaScript Date 对象之间的自动类型转换。

// MyItem.qml
Item 
{
    function readDate(dt) 
    {
        console.log("The given date is:", dt.toUTCString());
        return new Date();
    }
}

// C++
QQuickView view(QUrl::fromLocalFile("MyItem.qml"));

QDateTime dateTime = QDateTime::currentDateTime();
QDateTime retValue;

QMetaObject::invokeMethod(view.rootObject(), "readDate",
                          Q_RETURN_ARG(QVariant, retValue),
                          Q_ARG(QVariant, QVariant::fromValue(dateTime)));

qDebug() << "readDate()返回值:" << retValue;

上面的 C++ 代码调用 QML 函数时传递一个 QDateTime 值，当它传递给 readDate() 函数时，引擎会自动将其转换为 Date 对象。反过来， readDate() 函数返回一个 Date 对象，该对象在 C++ 中接收时会自动转换为 QDateTime 值。

与之类似的还有 QDate 和 JavaScript 日期、QTime 和 JavaScript 日期。

4.3、序列类型到 JavaScript 数组

QML 支持某些 C++ 序列类型，使其表现得像 JavaScript 数组类型。

特别是，QML 目前支持：

QList<int>
QList<qreal>
QList<bool>
QList<QString> 和 QStringList
QVector<QString>
std::vector<QString>
QList<QUrl>
QVector<QUrl>
std::vector<QUrl>
QVector<int>
QVector<qreal>
QVector<bool>
std::vector<int>
std::vector<qreal>
std::vector<bool>

以及所有注册的 QList、QVector、QQueue、QStack、QSet、std::list、std::vector 包含标记为 Q_DECLARE_METATYPE 的类型。

这些序列类型是根据底层 C++ 序列直接实现的。有两种方式可以将此类序列暴露给 QML：

作为给定序列类型的 Q_PROPERTY，通过索引访问序列中的任何值将导致从 QObject 的属性读取序列数据，然后再读取。同样，修改序列中的任何值都会导致读取序列数据，然后执行修改并将修改后的序列写回到QObject的属性中
作为 Q_INVOKABLE 方法的返回类型，访问和修改代价会低得多，因为不会发生 QObject 属性读取或写入。

在 Q_PROPERTY 和从 Q_INVOKABLE 返回的情况下，都会复制 std::vector 的元素。这种复制可能是一个昂贵的操作。

还可以通过使用 QJSEngine::newArray() 构造 QJSValue 来创建类似列表的数据结构。这样的 JavaScript 数组在 QML 和 C++ 之间传递时不需要任何转换。此类序列数组类型与默认 JavaScript 数组类型的语义之间存在一些细微差别，这是由于在实现中使用 C++ 存储类型造成的。特别是：

从 Array 中删除元素将导致替换该元素的默认构造值，而不是 Undefined 值。
将 Array 的 length 属性设置为大于其当前值的值将导致 Array 被填充到指定的长度，并使用默认构造的元素而不是 Undefined 的元素。
Qt 容器类支持有符号（而不是无符号）整数索引；因此，尝试访问任何大于 INT_MAX 的索引都会失败。

每个序列类型的默认构造值如下：

QList<int> - 0
QList<qreal> - 0.0
QList<bool> - false
QList<QString> 和 QStringList - 空 QString
QVector<QString> - 空 QString
std::vector<QString> - 空 QString
QList<QUrl> - 空 QUrl
QVector<QUrl> - 空 QUrl
std::vector<QUrl> - 空 QUrl
QVector<int> - 0
QVector<qreal> - 0.0
QVector<bool> - false
std::vector<int> - 0
std::vector<qreal> - 0.0
std::vector<bool> - false

如果希望从序列中删除元素而不是简单地用默认构造值替换它们，请不要使用索引删除运算符（“delete sequence[i]”），而是使用 splice 函数（“sequence.splice(startIndex, deleteCount )”)。

4.4、QByteArray 到 JavaScript ArrayBuffer

QML 引擎提供 QByteArray 值和 JavaScript ArrayBuffer 对象之间的自动类型转换。

4.5、值类型

Qt 中的某些值类型（例如 QPoint）在 JavaScript 中表示为具有与 C++ API 中相同的属性和功能的对象。

自定义 C++ 值类型也可以进行相同的表示。要使用 QML 引擎启用自定义值类型，类声明需要使用 Q_GADGET 进行注释。要在 JavaScript 可见的属性需要使用 Q_PROPERTY 进行声明。函数需要用 Q_INVOKABLE 标记。这与基于 QObject 的 C++ API 相同。示例：

class Actor
{
    Q_GADGET
    Q_PROPERTY(QString name READ name WRITE setName)
public:
    QString name() const { return m_name; }
    void setName(const QString &name) { m_name = name; }

private:
    QString m_name;
};

Q_DECLARE_METATYPE(Actor)

以上面定义的 Actor 为例，一般使用 Actor 类作为属性的类型，或者作为信号的参数。在这种情况下，Actor 实例在 C++ 和 QML 之间按值传递。如果 QML 代码更改了 Actor 的属性，则会重新创建整个 Actor 并将其传递回 C++ 属性设置器。

五、枚举类型

要将自定义枚举用作数据类型，必须注册其类，并且还必须使用 Q_ENUM() 声明枚举以将其注册到 Qt 的元对象系统。例如，下面的 Message 类有一个 Status 枚举：

class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Status status READ status NOTIFY statusChanged)
public:
    enum Status 
    {
        Ready,
        Loading,
        Error
    };
    Q_ENUM(Status)
    Status status() const;
signals:
    void statusChanged();
};

如果 Message 类已注册到 QML 类型系统，则可以从 QML 使用其 Status 枚举：

Message 
{
     onStatusChanged: 
    {
         if (status == Message.Ready)
             console.log("Message is loaded!")
     }
 }

要将枚举用作 QML 中的标志类型，需使用 Q_FLAG()。

注意：枚举值的名称必须以大写字母开头才能从 QML 访问。

5.1、枚举类

enum class Status 
{
    Ready,
    Loading,
    Error
}
Q_ENUM(Status)

枚举类在 QML 中注册为作用域属性和无作用域属性。

如 Ready 值将注册为 Message.Status.Ready（作用域属性）和 Message.Ready（无作用域属性）。

5.2、名称冲突

    class Message : public QObject
    {
        Q_OBJECT
        Q_CLASSINFO("RegisterEnumClassesUnscoped", "false")
        Q_ENUM(ScopedEnum)
        Q_ENUM(OtherValue)

    public:
        enum class ScopedEnum {
              Value1,
              Value2,
              OtherValue
        };
        enum class OtherValue {
              Value1,
              Value2
        };
    };

ScopedEnum 中的Value1将注册为 Message.ScopedEnum.Value1和 Message.Value1

OtherValue 中的Value1将注册为 Message.OtherValue .Value1和 Message.Value1

这样就会起冲突。

可以通过使用 Q_CLASSINFO 宏注释类来禁用无作用域注册。设置RegisterEnumClassesUnscoped 为false以防止作用域枚举合并到同一名称空间中。

5.3、枚举类型作为信号和方法参数

如果枚举和信号或方法都在同一个类中声明，或者枚举值是在 Qt 命名空间中声明的值之一，则可以从 QML 使用带有枚举类型参数的 C++ 信号和方法。

此外，如果带有枚举参数的 C++ 信号可以使用 connect() 函数连接到 QML 函数，则必须使用 qRegisterMetaType() 注册枚举类型。

对于 QML 信号，枚举值可以使用 int 类型作为信号参数传递：

Message 
{
    signal someOtherSignal(int statusValue)

    Component.onCompleted: 
    {
        someOtherSignal(Message.Loading)
    }
}