Qt QML 类型

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
• application.font

它与InputMethod单例相同。

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

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

其属性包括：

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

您应通过Application::styleHints访问StyleHints。

uiLanguage包含用于用户界面字符串翻译的语言名称。它在C++中以QQmlEngine::uiLanguage属性暴露。

您可以随意设置此值并用于绑定。建议在您的应用程序中安装翻译器后设置。按照惯例，空字符串表示从源代码中使用的语言不打算发生翻译。

如果使用QQmlApplicationEngine，并且值更改，将调用QQmlEngine::retranslate()。

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

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

如果将此函数连续多次以相同的第一个参数调用，该函数只会调用一次。

例如

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进行国际化。

返回具有 value 的 Alpha 值的 baseColor。

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"
    }
}

和从

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() 获取错误描述。

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

如果模式设置为Component.PreferSynchronous，Qt将尝试同步加载组件，但如果有必要，可能会异步加载。可能引起异步加载的情况包括但不限于以下

• URL 指的是网络资源
• 组件是通过正在异步加载的组件创建的

如果提供了可选的父参数，则它应引用将成为创建的组件对象的父对象。如果没有传递模式，这可以是第二个参数。

在返回的组件上调用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对象。

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

这是一个重载函数。

返回一个为moduleUri和typeName指定的类型创建的组件对象。

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

此重载版本的行为主要与基于url的版本相似，但可以用于实例化没有URL的类型（例如，通过QML_ELEMENT注册的C++类型）。

• 该类型是在C++中实现的
• 该类型是内联组件。

如果提供了可选的父参数，则它应引用将成为创建的组件对象的父对象。如果没有传递模式，这可以是第二个参数。

返回一个从给定的qml字符串创建的新对象，该对象将具有指定的parent，如果创建对象时发生错误，则为null。

如果指定了filepath，它将用于创建对象时错误报告。

示例（其中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" : "无法将值分配给不存在的属性 "colro"}}"。

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

通过提供的 factor 值返回一个比 baseColor 更暗的颜色。

如果因子大于 1.0，则此函数返回一个更暗的颜色。将因子设置为 3.0 返回亮度减一三分之一的颜色。如果因子小于 1.0，则返回的颜色更亮，但我们建议使用 Qt.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 对象应包含键值对，其中有效的键是 字体 类型的子属性名称，每个子属性的值是子属性的有效值。无效键将被忽略。

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

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

date 参数可以是 JavaScript Date 对象、date 属性、QDate 或 QDateTime 值。《i translate="no">format》和《i translate="no">localeFormatOption 参数可以是 Qt.formatDateTime 中描述的可能格式值。

如果未指定 format，则使用默认区域设置通过 Locale.ShortFormat 格式化 date。

另请参阅：Locale。

以字符串形式返回dateTime，可选地使用format和localeFormatOption进行格式化。

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

如果未提供format，则使用默认区域设置通过Locale.ShortFormat对dateTime进行格式化。否则，format应具有以下之一：

• 以下之一的Qt::DateFormat枚举值，例如Qt.RFC2822Date或Qt.ISODate。
• 一个指定返回字符串格式的字符串，如下所述。
• 一个locale对象。

如果format指定了区域对象，则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值可以传递给Qt.formatDateTime()、Qt.formatDate()或Qt.formatTime()，以下format值将产生以下结果

另请参阅：Locale。

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

time 参数可以是 JavaScript Date 对象，QTime 或 QDateTime 值。参数 format 和 localeFormatOption 可以是 Qt.formatDateTime 方法描述的所有可能的格式值之一。

如果未指定 format，则使用默认区域设置通过 Locale.ShortFormat 格式化 time。

另请参阅：Locale。

返回具有指定 hue、saturation、lightness 和 alpha 组成的颜色。所有组成部分应在 0-1 范围内（包含端点）。

返回具有指定 hue、saturation、value 和 alpha 组成的颜色。所有组件应在 0-1 范围内（包含端点）。

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

返回一个比 baseColor 淡的颜色的值。

如果因子大于 1.0，该函数返回一个比 baseColor 更浅的颜色。将因子设置为 1.5 返回一个亮 50% 的颜色。如果因子小于 1.0，返回的颜色会暗，但我们建议使用 Qt.darker() 函数来完成此操作。如果因子为 0 或负数，返回值是不确定的。

此函数将当前的 RGB 颜色转换为 HSV，乘以因子并转换回 RGB。

如果没有提供 factor，则返回一个比 baseColor 浅 50% 的颜色（因子为 1.5）。

返回一个表示具有指定 name 的区域的 JS 对象，其格式为 "language[_territory][.codeset][@modifier]" 或 "C"，其中

• language 是小写、两位的 ISO 639 语言代码，
• territory 是大写、两位的 ISO 3166 国家代码，
• codeset 和 modifier 不受重视。

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

另请参阅：Locale。

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

返回一个单位 4x4 矩阵。

返回一个具有指定 values 的 4x4 矩阵。期望 values 是一个包含 16 个条目的 JavaScript 数组。

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

返回一个具有指定值的 4x4 矩阵。

参数对应于矩阵中的位置

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

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

返回 sourceText 的翻译版本，可选地基于 disambiguation 字符串和 n 的值，用于包含复数字符串；如果不存在适当的翻译字符串，则返回 sourceText 本身。

如果在同一翻译上下文中的不同角色中使用相同sourceText，则可以传递一个附加的标识字符串作为disambiguation。

示例

Text { text: qsTr("hello") }

另请参阅：使用Qt进行国际化。

返回由 id 标识的翻译字符串。如果没有找到匹配的字符串，则返回 id 本身。这不应该在正常条件下发生。

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

示例

Text { text: qsTrId("hello_id") }

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

//% <字符串>

或者

\begincomment% <字符串> \endcomment

示例

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

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

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

返回给定 context 中 sourceText 的翻译版本，可选地基于翻译文本中的 disambiguation 字符串和 n 的值；如果没有合适的翻译字符串可用，则返回原 sourceText。

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

示例

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

另请参阅：使用Qt进行国际化。

返回一个具有指定的 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。

返回相对于url解析的QML上下文URL的URL。如果context未与QML上下文关联，则返回相对于QML引擎的基本URL解析的url。如果QML引擎没有基本URL，则仅返回url。

请参阅url。

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

返回具有指定width和height的大小。

此函数允许用一种颜色（《i translate="no">baseColor）来着色另一种颜色（《i translate="no">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.resolvedUrl()相反，此方法保留了任何相对URL。由于字符串默认转换为URL，因此可以使用字符串作为参数调用此函数，然后返回一个URL。

另请参阅resolvedUrl。

返回具有指定x和y值的vector2d。

返回具有指定x、y和z值的vector3d。

返回具有指定x、y、z和w值的vector4d。