QML类型：Qt

一、描述

Qt 对象是一个具有实用函数、属性和枚举的全局对象。它不可实例化。

要使用它，直接调用全局 Qt 对象的成员。 例如：

import QtQuick 2.0

Text 
{
    color: Qt.rgba(1, 0, 0, 1)
    text: Qt.md5("hello, world")
}

二、枚举

Qt 对象包含 Qt 命名空间中可用的枚举。

例如，可以以 Qt.LeftButton 和 Qt.RightButton 访问 Qt::LeftButton 和 Qt::RightButton 枚举值。

三、类型

Qt 对象还包含用于创建特定数据类型对象的辅助函数。这在设置项目的属性时有用：

• rect：Qt.rect()
• point：Qt.point()
• size：Qt.size()

如果已导入 QtQuick 模块，则以下用于创建特定数据类型对象的辅助函数也可供使用：

• color：Qt.rgba()、Qt.hsla()、Qt.darker()、Qt.lighter()、Qt.tint()
• font：Qt.font()
• vector2d：Qt.vector2d()
• vector3d：Qt.vector3d()
• vector4d：Qt.vector4d()
• quaternion：Qt.quaternion()
• matrix4x4：Qt.matrix4x4()

四、日期/时间格式化

Qt 对象包含多个用于格式化 QDateTime、QDate 和 QTime 值的函数。

• string Qt.formatDateTime(datetime date, variant format)
• string Qt.formatDate(datetime date, variant format)
• string Qt.formatTime(datetime date, variant format)

五、属性成员

1、application : object

此属性提供对许多 QML 组件共享的全局应用程序状态属性的访问。它与 Application 单例相同。

以下示例使用应用程序对象来指示应用程序当前是否处于活动状态：

import QtQuick 2.9
import QtQuick.Window 2.2

Window {
    id: root
    visible: true
    width: 800
    height: 680

    color: Qt.application.active ? "white" : "lightgray"
    Text {
        text: "应用程序 " + (Qt.application.active ? "活动" : "不活动")
        opacity: Qt.application.active ? 1.0 : 0.5
        anchors.centerIn: parent
    }
}

注意：在没有 QGuiApplication 的情况下使用 QML 时，以下属性将是未定义的：

• application.active
• application.state
• application.layoutDirection
• application.font

2、inputMethod : object

此属性允许访问应用程序的 QInputMethod 对象。

3、platform : object

此属性提供有关底层平台的信息。

platform.os：只读属性，包含操作系统的名称。可能的值为：

• "android"：Android
• "ios"：iOS
• "tvos"：tvOS
• "linux"：Linux
• "osx"：macOS
• "qnx"：QNX
• "unix"：其他基于 Unix 的操作系统
• "windows"：Windows
• "wasm"：WebAssembly

platform.pluginName：QGuiApplication 实例上设置的平台名称，由 QGuiApplication::platformName() 返回。

4、styleHints : object

此属性提供特定于平台的样式提示和设置。仅在使用 Qt Quick 模块时可用。

以下示例使用 styleHints 来确定项目是否应在鼠标按下或触摸释放时获得焦点：

import QtQuick 2.4

MouseArea {
    id: button

    onPressed: {
        if (!Qt.styleHints.setFocusOnTouchRelease)
            button.forceActiveFocus()
    }
    onReleased: {
        if (Qt.styleHints.setFocusOnTouchRelease)
            button.forceActiveFocus()
    }
}

5、uiLanguage : string

此属性包含用于用户界面字符串翻译的语言名称。 它在 C++ 中作为 QQmlEngine::uiLanguage 属性公开。

建议在应用程序中安装翻译器后进行设置。

按照惯例，空字符串意味着不打算从源代码中使用的语言进行翻译。

六、函数成员

1、callLater(function)

      callLater(function, argument1, argument2, ...)

使用此函数可消除对函数或信号的冗余调用。

当 QML 引擎返回到事件循环时，作为第一个参数传递给 Qt.callLater() 的函数将延迟调用。

当此 function 使用与其第一个参数相同的函数快速连续多次调用时，该函数将仅被调用一次。

2、color alpha(color baseColor, real value)

返回一个新的颜色对象，参数1和参数2分别确定rgb值和透明度值。

value 的范围从 0（完全透明）到 1（完全不透明）。

3、string atob(data)

解码并返回 base64 编码的字符串。

    console.log(Qt.atob("aGVsbG8gd29ybGQ=")) //qml: hello world

       string btoa(data)

返回data的 base64 编码。 

4、binding(function)

返回一个表示属性绑定的 JavaScript 对象，以及一个评估绑定的函数。

该函数有两个主要用法：

一、从 JavaScript 代码强制应用属性绑定：

Item {
    property bool someCondition: true
    property int edgePosition

    Component.onCompleted: {
        if (someCondition == true) {
            //edgePosition 绑定到传递给 Qt.binding() 的绑定表达式的结果
            edgePosition = Qt.binding(function() { return x + width })
        }
    }
}

二、在初始化动态构造对象的属性值时应用属性绑定（通过 Component.createObject() 或 Loader.setSource()）。

例如，假设存在一个 DynamicText 组件，当文本改变时会打印文本：

import QtQuick 2.0

Text
{
    id: textElement
    width: 200
    height: 200
    text: "默认文本"
    property string dynamicText: "动态文本"
    onTextChanged: console.log(textElement.text)
}

动态创建一个该组件作为窗口的子项，创建时绑定DynamicText的 text 属性和窗口的自定义属性dynamicText创建绑定关系，即dynamicText改变时DynamicText的 text 属性跟着变：

import QtQuick 2.14
import QtQuick.Window 2.14

Window
{
    id: root
    width: 640
    height: 480
    visible: true
    title: qsTr("Hello World")
    property string dynamicText: "黄河之水天上来"

    Component.onCompleted:
    {
        var c = Qt.createComponent("DynamicText.qml")

        var obj1 = c.createObject(root, {'text': Qt.binding(function() { return dynamicText + ' extra text' }) })
        root.dynamicText = "奔流到海不复回"
    }
}

同样的效果：

import QtQuick 2.14
import QtQuick.Window 2.14

Window
{
    id: root
    width: 640
    height: 480
    visible: true
    title: qsTr("Hello World")
    property string dynamicText: "黄河之水天上来"
    Loader
    {
        id: loaderOne
        onLoaded: root.dynamicText = "奔流到海不复回"
    }
    Component.onCompleted:
    {
        loaderOne.setSource("DynamicText.qml", { 'text': Qt.binding(function() { return dynamicText + ' extra text' }) })
    }
}

5、color color(string name)

返回与给定名称对应的颜色（即red或 #ff0000）。 如果没有这种颜色，则返回 null。

6、color colorEqual(color lhs, string rhs)

颜色比较。如果 lhs 和 rhs 产生相同的颜色值，则返回 true。两个参数都可以是颜色值或字符串值。如果提供了字符串值，则它必须可转换为颜色。

7、object createComponent(url, mode, parent)

返回使用指定 url 的 QML 文件创建的 Component 对象，如果给出空字符串，则返回 null。

返回的组件的 Component::status 属性指示组件是否已成功创建。如果为 Component.Error，可参阅 Component::errorString() 以获取错误说明。

mode参数：

如果省略此参数默认为 Component.PreferSynchronous。

如果 mode 参数设置为 Component.Asynchronous，则该组件将在后台线程中加载。可根据 Component::status 属性了解组件加载情况。

• 加载时为 Component.Loading
• 加载成功为 Component.Ready
• 加载失败为 Component.Error

如果 mode 设置为 Component.PreferSynchronous，Qt 将尝试同步加载组件，但最终可能会在必要时异步加载它。可能导致异步加载的场景包括但不限于以下几种：

• URL 是指网络资源
• 由于另一个组件正在异步加载，因此正在创建该组件

如果给出了可选的 parent 参数，它应该引用将成为创建的 Component 对象的父对象的对象。

在返回的组件上调用 Component.createObject() 以创建组件的对象实例。例如：

import QtQuick 2.0

Item
{
    id: container
    width: 300; height: 300

    function loadButton() 
    {
        var component = Qt.createComponent("Button.qml");
        if (component.status == Component.Ready)
        {
            var button = component.createObject(container);
            button.color = "red";
        }
    }

    Component.onCompleted: loadButton()
}

8、object createQmlObject(string qml, object parent, string filepath)

返回从给定的 qml 字符串创建的新对象，该对象将具有指定的父对象，如果创建对象时出错，则返回 null。如果指定了filepath，它将用于创建对象的错误报告。

示例（其中 parentItem 是现有 QML 项目的 ID）：

var newObject = Qt.createQmlObject('import QtQuick 2.0; Rectangle {color: "red"; width: 20; height: 20}',
                                   parentItem,"dynamicSnippet1");

在出现错误的情况下，会抛出一个 QQmlError 对象。

这个对象有一个额外的属性 qmlErrors，它表示一个遇到的错误数组。该数组中的每个对象都有成员 lineNumber、columnNumber、fileName 和 message。

例如，如果上面的代码片段将颜色拼错为“colro”，那么该数组将包含一个如下所示的对象：

{
    "lineNumber" : 1, 
    "columnNumber" : 32, 
    "fileName" : "dynamicSnippet1", 
    "message" : “无法分配给不存在的属性“colro””
}

此函数会立即返回，因此如果 qml 字符串加载新组件（即尚未加载的外部 QML 文件），则该函数可能不起作用。如果是这种情况，请考虑改用 Qt.createComponent()。

9、color darker(color baseColor, real factor)

根据提供的 factor 返回比 baseColor 更暗的颜色。

该函数将当前 RGB 颜色转换为 HSV，将值 (V) 分量除以 factor 并将颜色转换回 RGB。

• 如果 factor 大于 1.0，则此函数返回较深的颜色。将 factor 设置为 3.0 会返回亮度为三分之一的颜色。
• 如果 factor 小于 1.0，则返回颜色较浅，但建议为此使用 Qt.lighter() 函数。
• 如果 factor 为 0 或负数，则返回值未指定。
• 如果未提供 factor ，则返回比 baseColor深 50% 的颜色（factor 2.0）。

       color lighter(color baseColor, real factor)

根据提供的 factor 返回比 baseColor 浅的颜色。

该函数将当前 RGB 颜色转换为 HSV，将值 (V) 分量乘以 factor 并将颜色转换回 RGB。

• 如果 factor 大于 1.0，则此函数返回较浅的颜色。将 factor 设置为 1.5 会返回亮 50% 的颜色。
• 如果 factor 小于 1.0，则返回颜色更深，但建议为此使用 Qt.darker() 函数。
• 如果 factor 为 0 或负数，则返回值未指定。
• 如果未提供 factor，则返回比 baseColor亮 50% 的颜色（factor1.5）。

10、exit(int retCode)

这个函数会导致 QQmlEngine::exit(int) 信号被发射。在使用 qmlscene 进行原型设计时，这会导致启动器应用程序退出指定的返回代码 (retCode)。

要在调用此方法时使用指定的返回码退出事件循环，C++ 应用程序可以将 QQmlEngine::exit(int) 信号连接到 QCoreApplication::exit(int) 槽。

11、font font(object fontSpecifier)

返回具有在 fontSpecifier 对象中指定的属性的字体或最接近的匹配字体。

fontSpecifier 对象应包含键值对，其中有效键是字体类型的子属性名称，值是每个子属性的有效值。 无效的键将被忽略。

12、list<string> fontFamilies()

返回应用程序可用的字体系列列表。

13、string formatDate(datetime date, variant format, variant localeFormatOption)

返回日期的字符串表示形式，可选择使用 format 进行格式化。

date 参数可以是 JavaScript 日期对象、日期属性、QDate 或 QDateTime 值。

format 和 localeFormatOption 参数可以是 Qt.formatDateTime() 中描述的任何格式值。

如果未指定 format ，则使用默认语言环境使用 Locale.ShortFormat 格式化日期。

14、string formatDateTime(datetime dateTime, variant format, variant localeFormatOption)

返回 dateTime 的字符串表示形式，可选择使用 format 和 localeFormatOption 进行格式化。

dateTime 参数可以是 JavaScript 日期对象、日期属性、QDate、QTime 、QDateTime 值。

如果未提供 format，则 dateTime 将使用 Locale.ShortFormat 使用默认语言环境进行格式化。 否则，format 应该是：

• Qt::DateFormat 枚举值。
• 指定返回字符串格式的字符串。
• locale 对象。

如果 format 指定了 locale 对象，则 dateTime 使用 QLocale::toString 进行格式化。在这种情况下， localeFormatOption 可以保存 QLocale::FormatType 类型的值以进一步调整格式。 如果没有提供，则使用 Locale.ShortFormat。

如果 format 指定格式字符串，则应使用以下表达式来指定日期：

• d：没有前导零的数字（1 到 31）
• dd：将日期添加为带有前导零的数字（01 到 31）
• ddd：缩写的本地化日期名称（“Mon”~“Sun”）。使用 QDate::shortDayName()。
• dddd：本地化的长日期名称（“Monday”~“Qt::Sunday”）。使用 QDate::longDayName()。
• M：月份作为没有前导零的数字 (1-12)
• MM：月份为带前导零的数字 (01-12)
• MMM：缩写的本地化月份名称（“Jan”~“Dec”）。使用 QDate::shortMonthName()。
• MMMM：本地化的长月份名称（“January”~“December”）。使用 QDate::longMonthName()。
• yy：以两位数表示的年份 (00-99)
• yyyy：四位数的年份

此外，以下表达式可用于指定时间：

• h：没有前导零的小时（0 到 23 或 1 到 12，如果 AM/PM 显示）
• hh：带前导零的小时（00 到 23 或 01 到 12，如果 AM/PM 显示）
• m：没有前导零的分钟（0 到 59）
• mm：带前导零的分钟（00 到 59）
• s：没有前导零的第二个（0 到 59）
• ss：带有前导零的第二个（00 到 59）
• z：没有前导零的毫秒数（0 到 999）
• zzz：带前导零的毫秒数（000 到 999）
• AP：使用 AM/PM 显示。
• ap：使用 am/pm 显示。
• t：时区指示器。

所有其他输入字符将被忽略。用单引号括起来的任何字符序列都将被视为文本，而不是用作表达式。两个连续的单引号 ("''") 在输出中被单引号替换。

例如，如果指定了以下日期/时间值：

// 2001年5月21日14:13:09
var dateTime = new Date(2001, 5, 21, 14, 13, 09)

可以将此日期时间值传递给 Qt.formatDateTime()、Qt.formatDate() 或 Qt.formatTime() 并使用以下格式值以产生以下结果：

• "dd.MM.yyyy"——21.05.2001
• "ddd MMMM d yy"——Tue May 21 01
• "hh:mm:ss.zzz"——14:13:09.042
• "h:m:s ap"——2:13:9 pm

15、string formatTime(datetime time, variant format, variant localeFormatOption)

返回时间的字符串表示形式，可选择使用 format 和 localeFormatOption 进行格式化。

time 参数可以是 JavaScript 日期对象、QTime 或 QDateTime 值。

format 和 localeFormatOption 参数可以是 Qt.formatDateTime() 中描述的任何可能的格式值。

如果未指定格式，则使用默认语言环境使用 Locale.ShortFormat 格式化时间。

16、color hsva(real hue, real saturation, real value, real alpha)

根据色调（H）、饱和度（S）、明度（V）和 alpha 分量返回颜色。参数都应在 0-1（含）范围内。

       color hsla(real hue, real saturation, real lightness, real alpha)

根据色调（H）、饱和度（S）、亮度（V）和 alpha 分量返回颜色。参数都应在 0-1（含）范围内。

Ps中这里的明度和亮度有什么区别？

17、bool isQtObject(object)

object 是否对 Qt 或 QML 对象的有效引用。

18、locale(name)

返回一个 JS 对象，表示具有指定名称的语言环境。

19、string md5(data)

返回data的 md5 哈希的十六进制字符串。

20、matrix4x4 matrix4x4(real m11, real m12, real m13, real m14, real m21, real m22, real m23, real m24, real m31, real m32, real m33, real m34, real m41, real m42, real m43, real m44)

返回具有指定值的 matrix4x4。

参数对应于它们在矩阵中的位置：

也可以使用包含十六个矩阵值的单个参数 JavaScript 数组调用此函数。

也可以不带参数调用此函数，结果矩阵将是单位矩阵。

21、bool openUrlExternally(url target)

根据用户的桌面首选项，尝试在外部应用程序中打开指定的目标 url。返回打开结果。

警告：返回值为 true 表示应用程序已成功请求操作系统打开外部应用程序中的 URL。 外部应用程序可能仍无法启动或无法打开请求的 URL。此结果将不会报告回应用程序。

22、point point(real x, real y)

返回具有指定 x 和 y 坐标的点。

23、string qsTr(string sourceText, string disambiguation, int n)

返回 sourceText 的翻译版本，如果没有合适的翻译字符串可用，则返回 sourceText 本身。

参数2是标识字符串，用作：如果上下文有两个一样的源字符串但在翻译里表示不同的意思，则可以用标识字符串消除歧义。

Text { text: qsTr("hello") }

---- 省略几个翻译相关的函数，以后再来看看 ----

24、quaternion quaternion(real scalar, real x, real y, real z)

返回四元数。

25、quit()

此函数导致 QQmlEngine::quit() 信号被发射。在使用 qmlscene 进行原型设计时，这会导致启动器应用程序退出； 要在调用此方法时退出 C++ 应用程序，请将 QQmlEngine::quit() 信号连接到 QCoreApplication::quit() 槽。

26、rect rect(real x, real y, real width, real height)

返回一个矩形。

27、url resolvedUrl(url url, object context)

       url resolvedUrl(url url)

相对路径转绝对路径。

28、color rgba(real red, real green, real blue, real alpha)

返回颜色。所有参数都应在 0-1（含）范围内。

29、size size(real width, real height)

返回 size 对象。 

30、color tint(color baseColor, color tintColor)

此函数允许将一种颜色 (baseColor) 着色为另一种 (tintColor)。

tintColor 通常应该大部分是透明的，否则将看不到底层颜色。

下面的示例通过使 tintColor 为纯红色（只有 1/16 不透明）来提供轻微的红色色调。

Item {
    Rectangle {
        x: 0; width: 80; height: 80
        color: "lightsteelblue"
    }
    Rectangle {
        x: 100; width: 80; height: 80
        color: Qt.tint("lightsteelblue", "#10FF0000")
    }
}

当由于某些事件而要传达微妙的变化时，此函数非常有用。 

31、vector2d vector2d(real x, real y)

返回 vector2d 对象。

       vector3d vector3d(real x, real y, real z)

返回 vector3d 对象。

       vector4d vector4d(real x, real y, real z, real w)

返回 vector4d 对象。