C

Loader QML 类型

允许从 URL 或组件动态加载子树的 QML 组件。 更多...

导入语句import QtQuick
自Qt Quick Ultralite 2.3

属性

信号

方法

详细描述

Loader 可以加载预编译的 QML 组件（使用 source 属性）或一个 Component 对象（使用 sourceComponent 属性）。它对于延迟组件的创建，直到需要时非常有用：例如，当组件应当被按需创建，或者出于性能原因不应无谓地创建。

如下是一个 Loader，在点击 MouseArea 时将其加载为组件的 "Page1.qml"

import QtQuick 2.15

Item {
    width: 200; height: 200
    Loader { id: pageLoader }

    MouseArea {
        anchors.fill: parent
        onClicked: pageLoader.source = "Page1.qml"
    }
}

如果 source 或 sourceComponent 发生变化，任何之前实例化的项目都将被销毁。将 source 设置为空字符串，或将 sourceComponent 设置为 undefined 将销毁当前加载的对象，释放资源并使 Loader 为空。

分配

Qt Quick Ultralite Loader 使用 QmlDynamicObjects 内存分配器为其项目进行分配。

分配发生在源或 sourceComponent 发生变化时。在每次分配之前完成释放，并在 active 属性更改到 false 时进行。

请注意，Qt Quick Ultralite 中所有分配都在单个线程上执行。根据用户定义的初始化例程（类构造函数）的持续时间，可能发生短暂的 UI 冻结。

Loader 调整大小行为

Loader 应用以下调整大小规则

  • 如果没有为Loader指定显式大小，则在组件加载完成后，Loader会自动调整到加载项的大小。
  • 如果通过设置宽度、高度或锚点来显式指定Loader的大小，则加载项将会调整到Loader的大小。

在这两种情况下，项的大小和Loader的大小相同。这确保了锚定到Loader与锚定到加载项等效。

SizeLoader.qmlSizeItem.qmlMyRect.qml
 
import QtQuick 2.15

Item {
    width: 200; height: 200

    Loader {
        // Explicitly set the size of the
        // Loader to the parent item's size
        anchors.fill: parent
        source: "MyRect.qml"
    }
}
import QtQuick 2.15

Item {
    width: 200; height: 200

    Loader {
        // position the Loader in the center
        // of the parent
        anchors.centerIn: parent
        source: "MyRect.qml"
    }
}
import QtQuick 2.15

Rectangle {
    width: 50
    height: 50
    color: "red"
}
红色矩形的大小将设置为其根项的大小。红色矩形的大小为50x50，在根项中居中。

限制性

与加载项的通信

与Qt Quick Loader不同，Qt Quick Ultralite Loader由于缺乏对象自省系统，不支持使用item属性访问加载项。

这种限制实际上禁用了像使用Loader.item读取或写入属性和调用函数这样的交互。

要解决这个限制，可以创建一个中介单例。例如

import QtQuick 2.15
pragma singleton

QtObject {
    property string text: ""
}

然后，在main.qml文件中使用此单例

import QtQuick 2.15
import Mediator

Column {
    Text {
        text: "Text from loaded item: " + Mediator.text
    }

    Loader {
        source: "MyText.qml"
    }
}

并且是MyText.qml

import QtQuick 2.15
import Mediator

Text {
    text: "mytext"
    Component.onCompleted: Mediator.text = text
}

当使用sourceComponent属性时，不需要中介单例，因为Component可以绑定到文档中的其他项

import QtQuick 2.15

Rectangle {
    id: root

    Item {
        id: globalSettings
        property int usersVisisted: 0
        property color page1Color: "orange"

        signal updatePageStats()
    }

    Component {
        id: page1
        Rectangle {
            color: globalSettings.page1Color
            width: 100
            height: 100

            Connections {
                target: globalSettings
                function onUpdatePageStats() {
                    globalSettings.usersVisisted = 999
                }
            }
        }
    }

    Column {
        Loader {
            id: loader1
            sourceComponent: page1
            Component.onCompleted: {
                globalSettings.page1Color = "pink"
                globalSettings.updatePageStats()
            }
        }
        Text {
            text: "users visited: " + globalSettings.usersVisisted
        }
    }
}

视图代理

Qt Quick Ultralite Loader不能在视图代理中使用。

另请参阅 已知问题或限制.

属性文档

active : bool

如果Loader当前处于活动状态，此属性为true。默认情况下为true。

如果Loader处于非活动状态，更改<篆 translate="no">source将不会在Loader变为活动状态之前实例化项。

将值设置为false将释放Loader加载的所有项，但这不会影响<篆 translate="no">source。


item : ItemBase*

此属性包含当前加载的顶级对象。

另请参阅 与加载项的通信。


source : string

此属性包含要实例化的QML项的URL。

Loader只能加载可视项（继承自Item的项）。

Item {
    Loader {
        source: "MyItem.qml"
    }
}

将此属性设置为空字符串或新URL，将卸载从先前URL加载的项。

source属性的值必须是当前模块中QML项的源文件。如果您想使用来自其他模块的项，请使用sourceComponent代替。考虑以下示例，其中"MyModuleItem.qml"是模块MyModule的一部分

import MyModule

Item {
    Loader {
        sourceComponent: MyModuleItem {}
    }
}

另请参阅 sourceComponent。


[自Qt Quick Ultralite 2.4起] sourceComponent : Component

此属性包含要实例化的Component。

Item {
    Component {
        id: redSquare
        Rectangle { color: "red"; width: 10; height: 10 }
    }

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 10 }
}

要将当前加载的对象卸载，请将此属性设置为undefined。

Loader只能加载可视项（继承自Item的项）。

此属性是在Qt Quick Ultralite 2.4中引入的。

另请参阅 source。


[自 Qt Quick Ultralite 2.6 开始] 状态 : 枚举

此属性持有 QML 组件的加载状态。它可以有以下其中之一

常量描述
Loader.Null加载器处于非活动状态或尚未设置 QML 源。
Loader.Ready已加载 QML 源。
Loader.Error加载 QML 源时发生错误。

使用此状态以提供更新或以某种方式响应该状态的变化。例如，您可以

  • 触发状态变化
    State {
    name: 'loaded'
    when: loader.status == Loader.Ready
}
  • 实现 onStatusChanged 信号处理器
    Loader {
    id: loader
    onStatusChanged: {
        if (loader.status == Loader.Ready)
            console.log('Loaded');
    }
}
  • 绑定到状态值
    Text {
    text: loader.status == Loader.Ready ? 'Loaded' : 'Not loaded'
}

注意： 如果 source 是本地文件，则初始的 status 是 Ready 或 Error。在这种情况下，您只会收到 onLoaded 信号的通知，但不会收到 onStatusChanged 信号。

此属性是在 Qt Quick Ultralite 2.6 中引入的。


信号文档

loaded()

当项目成功加载时，会发射此信号。

加载失败会导致 item 设置为 null。这可以通过 onItemChanged 处理器检测到。

注意： 相应的处理器是 onLoaded。

另请参阅 source 和 setSource。


方法文档

void setSource(string source)

创建给定源组件的对象实例。在加载和实例化完成后，将通过 item 属性访问该实例。

如果在此函数调用时 active 属性为 false，则不会加载给定的 source 组件，但 会将其缓存。当加载器变为 active 时，将创建 source 组件的实例。

另请参阅 与加载项的通信。


在某些 Qt 许可下可用。
了解更多信息。