QML Value Types

QML supports built-in and custom value types.

A value type is one that is passed by value rather than by reference, such as an int 或 string . This contrasts with QML 对象类型 . Object types are passed by reference. If you assign an instance of an object type to two different properties, both properties carry the same value. Modifying the object is reflected in both properties. If you assign an instance of a value type to two different properties, the properties carry separate values. If you modify one of them, the other one stays the same. Unlike an object type, a value type cannot be used to declare QML objects: it is not possible, for example, to declare an int{} object or a size{} 对象。

Value types can be used to refer to:

• A single value (e.g. int refers to a single number)
• A value that contains properties and methods (e.g. size refers to a value with width and height properties)
• The generic type var . It can hold values of any other type but is itself a value type.

When a variable or property holds a value type and it is assigned to another variable or property, then a copy of the value is made.

Available Value Types

Some value types are supported by the engine by default and do not require an import statement to be used, while others do require the client to import the module which provides them. All of the value types listed below may be used as a property type in a QML document, with the following exceptions:

• void , which marks the absence of a value
• list must be used in conjunction with an object or value type as element
• enumeration cannot be used directly as the enumeration must be defined by a registered QML object type

Built-in Value Types Provided By The QML Language

The built-in value types supported natively in the QML language are listed below:

bool	二进制 true/false 值
date	日期值
double	带小数点的数字，以双精度存储
enumeration	命名枚举值
int	Whole number, e.g. 0, 10, or -20
list	QML 对象列表
real	带小数点的数字
string	A free form text string
url	资源定位器
var	Generic property type
variant	Generic property type
void	Empty value type

Value Types Provided By QML Modules

QML modules may extend the QML language with more value types.

The value types provided by the QtQml module are:

point	Value with x and y attributes
rect	Value with x, y, width and height attributes
size	Value with width and height attributes

The value types provided by the QtQuick module are:

color	ARGB color value
font	Font value with the properties of QFont. The font type refers to a font value with the properties of QFont
matrix4x4	A matrix4x4 type is a 4-row and 4-column matrix
quaternion	A quaternion type has scalar, x, y, and z attributes
vector2d	A vector2d type has x and y attributes
vector3d	Value with x, y, and z attributes
vector4d	A vector4d type has x, y, z and w attributes

The Qt global object provides useful functions for manipulating values of value types.

You may define your own value types as described in 从 C++ 定义 QML 类型 . In order to use types provided by a particular QML module, clients must import that module in their QML documents.

Property Change Behavior for Value Types

Some value types have properties: for example, the font type has pixelSize , family and bold properties. Unlike properties of object types , properties of value types do not provide their own property change signals. It is only possible to create a property change signal handler for the value type property itself:

Text {
    // invalid!
    onFont.pixelSizeChanged: doSomething()
    // also invalid!
    font {
        onPixelSizeChanged: doSomething()
    }
    // but this is ok
    onFontChanged: doSomething()
}
					

Be aware, however, that a property change signal for a value type is emitted whenever any of its attributes have changed, as well as when the property itself changes. Take the following code, for example:

Text {
    onFontChanged: console.log("font changed")
    Text { id: otherText }
    focus: true
    // changing any of the font attributes, or reassigning the property
    // to a different font value, will invoke the onFontChanged handler
    Keys.onDigit1Pressed: font.pixelSize += 1
    Keys.onDigit2Pressed: font.b = !font.b
    Keys.onDigit3Pressed: font = otherText.font
}
					

In contrast, properties of an 对象类型 emit their own property change signals, and a property change signal handler for an object-type property is only invoked when the property is reassigned to a different object value.

另请参阅 QML 类型系统 .

内容

• Available Value Types

• Built-in Value Types Provided By The QML Language

• Value Types Provided By QML Modules

• Property Change Behavior for Value Types