Qt QML Type

application 对象提供对许多 QML 组件共享的全局应用程序状态属性的访问。

它与Application 单例相同。

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

import QtQuick

Rectangle {
    width: 300; height: 55
    color: Qt.application.active ? "white" : "lightgray"
    Text {
        text: "Application " + (Qt.application.active ? "active" : "inactive")
        opacity: Qt.application.active ? 1.0 : 0.5
        anchors.centerIn: parent
    }
}

• application.active
• application.state
• application.layoutDirection
• 应用程序字体

它与InputMethod 单例相同。

inputMethod 对象允许访问应用程序的QInputMethod 对象及其所有属性和槽。更多详情，请参阅QInputMethod 文档。

platform 对象提供有关底层平台的信息。

其属性如下

styleHints 对象提供特定于平台的样式提示和设置。有关详细信息，请参阅QStyleHints 文档。

您应通过Application::styleHints 访问 StyleHints，因为它能为工具（如 Qt Quick Compiler.

uiLanguage 保存用于用户界面字符串翻译的语言名称。它在 C++ 中显示为 QQmlEngine::uiLanguage 属性。

你可以自由设置该值，并在绑定中使用它。建议在应用程序中安装翻译器后再设置它。按照惯例，空字符串表示不翻译源代码中使用的语言。

如果您正在使用QQmlApplicationEngine ，而值发生了变化，QQmlEngine::retranslate() 将被调用。

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

作为第一个参数传递给 Qt.callLater() 的函数将在 Qt XML 引擎返回事件循环后被调用。

当连续多次调用此函数时，如果其第一个参数是同一个函数，则该函数将只被调用一次。

例如

import QtQuick

Rectangle {
    width: 480
    height: 320

    property int callsToUpdateMinimumWidth: 0
    property bool optimize: true

    property int currentTextModel: 0
    property var columnTexts: [
        ["Click on either", "rectangle above", "and note how the counter", "below updates", "significantly faster using the", "regular (non-optimized)", "implementation"],
        ["The width", "of this column", "is", "no wider than the", "widest item"],
        ["Note how using Qt.callLater()", "the minimum width is", "calculated a bare-minimum", "number", "of times"]
    ]

    Text {
        x: 20; y: 280
        text: "Times minimum width has been calculated: " + callsToUpdateMinimumWidth
    }

    Row {
        y: 25; spacing: 30; anchors.horizontalCenter: parent.horizontalCenter
        Rectangle {
            width: 200; height:  50; color: "lightgreen"
            Text { text: "Optimized behavior\nusing Qt.callLater()"; anchors.centerIn: parent }
            MouseArea { anchors.fill: parent; onClicked: { optimize = true; currentTextModel++ } }
        }
        Rectangle {
            width: 200; height:  50; color: "lightblue"
            Text { text: "Regular behavior"; anchors.centerIn: parent}
            MouseArea { anchors.fill: parent; onClicked: { optimize = false; currentTextModel++ } }
        }
    }

    Column {
        id: column
        anchors.centerIn: parent

        onChildrenChanged: optimize ? Qt.callLater(updateMinimumWidth) : updateMinimumWidth()

        property int widestChild
        function updateMinimumWidth() {
            callsToUpdateMinimumWidth++
            var w = 0;
            for (var i in children) {
                var child = children[i];
                if (child.implicitWidth > w) {
                    w = child.implicitWidth;
                }
            }

            widestChild = w;
        }

        Repeater {
            id: repeater
            model: columnTexts[currentTextModel%3]
            delegate: Text {
                color: "white"
                text: modelData
                width: column.widestChild
                horizontalAlignment: Text.Center
                Rectangle { anchors.fill: parent; z: -1; color: index%2 ? "gray" : "darkgray" }
            }
        }
    }
}

传给 Qt.callLater() 的任何其他参数都将传给被调用的函数。请注意，如果消除了多余的调用，那么只有最后一组参数会传递给函数。

在给定的context 中标记用于动态翻译的sourceText ；也就是说，存储的sourceText 不会被更改。

如果同一sourceText 在同一翻译上下文中被用于不同角色，则可为disambiguation 传递额外的标识字符串。

返回sourceText 。

QT_TRANSLATE_NOOP 与动态翻译函数qsTr() 和qsTranslate() 结合使用。它将字符串标识为需要翻译（因此可通过lupdate 标识），但将实际翻译工作留给动态函数。

举例说明：

Item {
    property string greeting: QT_TRANSLATE_NOOP("CustomContext", "hello")

    Text { text: qsTranslate("CustomContext", greeting) }
}

另请参阅 Qt 的国际化。

标记id 为动态翻译。

返回id 。

QT_TRID_NOOP 与动态翻译函数qsTrId() 结合使用。它将字符串标识为需要翻译（因此可通过lupdate 标识），但实际翻译工作留给qsTrId() 完成。

举例说明：

Item {
    property string greetingId: QT_TRID_NOOP("hello_id")

    Text { text: qsTrId(greetingId) }
}

另请参阅 qsTrId() 和Qt 的国际化。

标记sourceText 为动态翻译；也就是说，存储的sourceText 不会被更改。

如果同一sourceText 被用于同一翻译上下文中的不同角色，则可为disambiguation 传递额外的标识字符串。

返回sourceText 。

QT_TR_NOOP 与动态翻译函数qsTr() 和qsTranslate() 结合使用。它将字符串标识为需要翻译（因此可通过lupdate 标识），但将实际翻译工作留给动态函数。

举例说明：

Item {
    property string greeting: QT_TR_NOOP("hello")

    Text { text: qsTr(greeting) }
}

另请参阅 Qt 的国际化。

返回baseColor ，alpha 值为value 。

value 是一个从 0（完全透明）到 1（完全不透明）的实数。

ASCII 转二进制--该函数解码 base64 编码的data 字符串并返回。

返回代表属性绑定的 JavaScript 对象，以及评估绑定的function 。

该函数有两个主要用例：第一，从 JavaScript 代码中强制应用属性绑定：

Item {
    property bool someCondition: true
    property int edgePosition

    Component.onCompleted: {
        if (someCondition == true) {
            // bind to the result of the binding expression passed to Qt.binding()
            edgePosition = Qt.binding(function() { return x + width })
        }
    }
}

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

例如，假设存在一个 DynamicText 组件：

import QtQuick

Text {
    id: textElement
    width: 200
    height: 200
    text: "Default text"
    property string dynamicText: "Dynamic text"
    onTextChanged: console.log(text)
}

输出来自

Item {
    id: root
    property string dynamicText: "Root text"

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

        var obj1 = c.createObject(root, { 'text': Qt.binding(function() { return dynamicText + ' extra text' }) })
        root.dynamicText = "Modified root text"

        var obj2 = c.createObject(root, { 'text': Qt.binding(function() { return this.dynamicText + ' extra text' }) })
        obj2.dynamicText = "Modified dynamic text"
    }
}

和 from：

Item {
    id: root
    property string dynamicText: "Root text"

    Loader {
        id: loaderOne
        onLoaded: root.dynamicText = "Modified root text"
    }

    Loader {
        id: loaderTwo
        onLoaded: item.dynamicText = "Modified dynamic text"
    }

    Component.onCompleted: {
        loaderOne.setSource("DynamicText.qml", { 'text': Qt.binding(function() { return dynamicText + ' extra text' }) })
        loaderTwo.setSource("DynamicText.qml", { 'text': Qt.binding(function() { return this.dynamicText + ' extra text' }) })
    }
}

的输出都应为

Root text extra text
Modified root text extra text
Dynamic text extra text
Modified dynamic text extra text

此函数不能用于属性绑定声明（请参阅绑定声明和绑定赋值文档），除非结果存储在绑定到 var 属性的数组中。

Item {
    width: 50
    property var storedBindings: [ Qt.binding(function() { return x + width }) ] // stored
    property int a: Qt.binding(function() { return x + width }) // error!
    property int b

    Component.onCompleted: {
        b = storedBindings[0] // causes binding assignment
    }
}

二进制转 ASCII - 此函数返回data 的 base64 编码。

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

如果lhs 和rhs 产生的颜色值相等，则返回true 。两个参数可以是颜色值或字符串值。如果提供的是字符串值，则必须能转换为颜色，如color 值类型所述。

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

返回组件的Component::status 属性表示组件是否成功创建。如果状态为Component.Error ，请参阅Component::errorString() 了解错误说明。

如果可选的mode 参数设置为Component.Asynchronous ，组件将在后台线程中加载。在加载过程中，Component::status 属性将为Component.Loading 。如果组件加载成功，状态将变为Component.Ready ；如果加载失败，状态将变为Component.Error 。如果省略此参数，默认值为Component.PreferSynchronous 。

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

• URL 指向网络资源
• 该组件是由于异步加载另一个组件而创建的

如果给出了可选的parent 参数，它应指向将成为所创建Component 对象父对象的对象。如果没有传递模式，则可将其作为第二个参数。

对返回的组件调用Component.createObject() 来创建该组件的对象实例。

例如

import QtQuick

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

有关使用此函数的更多信息，请参阅《从 JavaScript 创建动态 QML 对象》（Dynamic QML Object Creation from JavaScript）。

要从任意 QML 字符串（而不是文件）创建 QML 对象，请使用Qt.createQmlObject()。

这是一个重载函数。

返回为moduleUri 和typeName 指定的类型创建的Component 对象。

import QtQml
QtObject {
    id: root
    property Component myComponent: Qt.createComponent("QtQuick", "Rectangle", Component.Asynchronous, root)
}

该重载函数的大部分功能与基于url 的版本相同，但可用于实例化没有 URL 的类型（例如通过QML_ELEMENT 注册的 C++ 类型）。

• 类型是用 C++ 实现的
• 类型是内联组件。

如果给出了可选的parent 参数，它应指向将成为所创建Component 对象父对象的对象。如果没有传递模式，则可将其作为第二个参数。

此方法在 Qt 6.5 中引入。

将给定的qml 字符串编译成一个组件，然后返回从该组件创建的新对象。新对象将具有指定的parent 。如果在创建组件或对象时出现错误，则返回null 。

如果指定了url ，它将被用作组件的 URL。这对错误报告非常有用。

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

const newObject = Qt.createQmlObject(`
    import QtQuick

    Rectangle {
        color: "red"
        width: 20
        height: 20
    }
    `,
    parentItem,
    "myDynamicSnippet"
);

在出错的情况下，会抛出一个QQmlError 对象。该对象有一个附加属性qmlErrors ，它是一个包含所遇错误的数组。数组中的每个对象都有lineNumber 、columnNumber 、fileName 和message 。例如，如果上述代码段将 color 错写成了 "colro"，那么数组中将包含如下对象：{ "lineNumber" : 1, "columnNumber" : 32, "fileName" : "dynamicSnippet1", "message" : "Cannot assign to nonexistent property "colro""}。

有关使用此函数的更多信息，请参阅从 JavaScript 动态创建 QML 对象。

根据所提供的factor ，返回比baseColor 更深的颜色。

如果系数大于 1.0，此函数将返回更深的颜色。将因数设置为 3.0 会返回亮度为其三分之一的颜色。如果因数小于 1.0，返回的颜色较浅，但我们建议为此使用 Qt XML.lighter() 函数。如果因数为 0 或负数，返回值则未指定。

该函数将当前的 RGB 颜色转换为 HSV，用因子除以值 (V) 分量，然后将颜色转换回 RGB。

如果未提供factor ，则返回比baseColor 暗 50%（系数 2.0）的颜色。

此函数将发出QQmlEngine::exit(int) 信号。在qml 工具中，这会导致启动程序以指定的返回代码（retCode ）退出。要在调用此方法时以指定的返回代码退出事件循环，C++ 应用程序可以将QQmlEngine::exit(int) 信号连接到QCoreApplication::exit(int) 槽。

另请参阅 quit() 。

返回具有fontSpecifier 对象中指定属性的字体或最匹配的字体。fontSpecifier 对象应包含键值对，其中有效键是font 类型的子属性名称，值是每个子属性的有效值。无效键将被忽略。

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

返回date 的字符串表示，可选择使用format 格式化。

date 参数可以是 JavaScriptDate 对象、date 属性、QDate 或QDateTime 值。format 和localeFormatOption 参数可以是任何可能的格式值，如Qt.formatDateTime() 所述。

如果未指定format ，则date 将使用Locale.ShortFormat 和默认的 locale 格式化。

另请参阅 Locale 。

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

dateTime 参数可以是 JavaScriptDate 对象、date 属性、QDate 、QTime 或QDateTime 值。

如果未提供format ，则dateTime 将使用Locale.ShortFormat 和默认语言格式化。否则，format 应为

• Qt::DateFormat 枚举值之一，如Qt.RFC2822Date 或Qt.ISODate 。
• 指定返回字符串格式的字符串，详见下文。
• locale 对象。

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

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

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

所有其他输入字符将被忽略。任何用单引号括起来的字符序列都将被视为文本，不能用作表达式。在输出中，两个连续的单引号（"''"）将被一个单引号取代。

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

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

可将dateTime 值与下面的format 值一起传递给Qt.formatDateTime() 、Qt.formatDate() 或Qt.formatTime() 以产生以下结果：

另请参阅 Locale 。

返回time 的字符串表示，可选择使用format 格式化，如果提供，则返回localeFormatOption 。

time 参数可以是 JavaScriptDate 对象、QTime 或QDateTime 值。format 和localeFormatOption 参数可以是任何可能的格式值，如Qt.formatDateTime() 所述。

如果未指定format ，则time 将使用Locale.ShortFormat 和默认的 locale 格式化。

另请参阅 Locale 。

运行垃圾回收器。

这相当于调用QJSEngine::collectGarbage() 。

另请参阅 垃圾回收。

返回具有指定hue,saturation,lightness 和alpha 组件的颜色。所有成分的范围应为 0-1（含）。

使用指定的hue,saturation,value 和alpha 组件返回颜色。所有分量的范围应为 0-1（含）。

如果object 是对 Qt 或 QML 对象的有效引用，则返回true ，否则返回false 。

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

如果系数大于 1.0，该函数将返回更浅的颜色。将系数设置为 1.5 会返回亮度高 50%的颜色。如果因子小于 1.0，返回的颜色会更深，但我们建议为此使用 Qt XML.darker() 函数。如果因数为 0 或负数，返回值则未指定。

该函数将当前的 RGB 颜色转换为 HSV，将值 (V) 部分乘以因子，然后将颜色转换回 RGB。

如果未提供factor ，则返回比baseColor 淡 50%（系数 1.5）的颜色。

返回一个 JS 对象，该对象代表带有指定name 的本地语言，格式为 "language[_territory][.codeset][@modifier]"或 "C"，其中：

• language 是小写的双字母 ISO 639 语言代码、
• territory 是大写的双字母 ISO 3166 国家代码，而
• codeset 和 将被忽略。modifier

如果字符串违反了本地设置格式，或者语言不是有效的 ISO 369 代码，则使用 "C "本地设置。如果不存在国家代码或国家代码不是有效的 ISO 3166 代码，则为指定语言选择最合适的国家。

另请参阅 Locale 。

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

返回标识矩阵 4x4。

values values 预计是一个有 16 个条目的 JavaScript 数组。

数组索引与矩阵中的位置对应如下：

返回包含指定值的矩阵 4x4。

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

根据用户的桌面偏好，尝试在外部应用程序中打开指定的target 网址。如果成功则返回true ，否则返回false 。

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

返回sourceText 的翻译版本，对于包含复数的字符串，可选择基于disambiguation 字符串和n 的值；否则，如果没有合适的翻译字符串，则返回sourceText 本身。

使用sourceText 和n 的示例：

    Text { text: qsTr("hello") }

    // Translates the source text into the correct
    // plural form and replaces %n with the value of total.
    Text {
        text: qsTr("%n message(s) saved", "", total)
    }

如果同一sourceText 在同一翻译上下文的不同角色中使用，则可以为disambiguation 传递额外的标识字符串。有关详细信息和示例，请参阅 "消除相同文本的歧义"。

另请参阅 qsTranslate()、Qt XML 的国际化和为翻译编写源代码。

返回由id 标识的翻译字符串。如果找不到匹配字符串，则返回 id 本身。正常情况下不会出现这种情况。

如果n >= 0，那么结果字符串中所有出现的%n 都将被替换为n 的十进制表示。此外，根据n 的值，翻译文本可能会有所不同。

举例说明

Text { text: qsTrId("hello_id") }

可以提供一个源字符串模板，如

//% <string>

    Text {
        //% "hello"
        text: qsTrId("hello_id")
    }

或

/*% <string> */

    Text {
        /*% "hello" */
        text: qsTrId("hello_id")
    }

要创建适合该函数使用的二进制翻译 (QM) 文件，需要向lrelease 工具传递-idbased 选项。

另请参阅 QT_TRID_NOOP() 和Qt 的国际化。

在给定的context 中返回sourceText 的翻译版本，对于包含复数的字符串，可选择基于disambiguation 字符串和n 的值；否则，如果没有合适的翻译字符串，则返回sourceText 本身。

如果同一个sourceText 在同一个翻译context 中被用于不同的角色，可以为disambiguation 传递一个额外的标识字符串。

举例说明：

Text { text: qsTranslate("CustomContext", "hello") }

如果您的翻译context 与文件context 不同，请使用。

另请参阅 Qt XML 的国际化和qsTr()。

返回具有指定scalar,x,y 和z 值的四元数。

此函数将发出QQmlEngine::quit() 信号。在qml 工具中，这会导致启动程序退出；要在调用此方法时退出 C++ 应用程序，请将QQmlEngine::quit() 信号连接到QCoreApplication::quit() 槽。

另请参阅 exit() 。

返回一个矩形，其左上角位于x 、y 以及指定的width 和height 。

返回相对于调用者 URL 解析的url 。

如果没有调用者或调用者与 QML 上下文无关，则返回相对于 QML 引擎基本 URL 解析的url 。如果 QML 引擎没有基本 URL，则只返回url 。

另请参阅 url() 。

Returnsurl resolved relative to the URL of the QML context ofcontext. 如果context 与 QML 上下文无关，则返回url resolved relative to the QML engine's base URL.如果 QML 引擎没有基本 URL，则只返回url 。

另请参阅 url() 。

返回具有指定red,green,blue 和alpha 组件的颜色。所有分量的范围应为 0-1（含）。

用指定的width 和height 返回大小。

该函数允许将一种颜色 (baseColor) 染成另一种颜色 (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")
    }
}

当由于某些事件的发生而需要传达微妙的变化时，着色效果最为有用；这时，您可以使用着色来更有效地调整可见颜色。

逐字返回url 。这可用于强制类型胁迫到url 。与 Qt XML 相反，resolvedUrl() 会保留任何相对 URL。由于字符串被隐式转换为 url，因此可以使用字符串作为参数调用该函数，然后返回 url。

另请参见 resolvedUrl()。

返回包含指定x 和y 值的 vector2d。

用指定的x 、y 和z 值返回向量 3d。

用指定的x,y,z 和w 值返回 vector4d。