在 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)
}
}