Loader QML Type

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

• 所有成员的列表，包括继承的成员

属性

• active : bool
• asynchronous : bool
• item : QtObject
• progress : real
• source : url
• sourceComponent : Component
• status : enumeration

信号

• loaded()

方法

• void setSource(url source, var properties)

详细说明

Loader 用于动态加载 QML 组件。

Loader 可以加载 QML 文件（使用 `source ` 属性）或Component 对象（使用 `sourceComponent ` 属性）。它有助于延迟组件的创建，直到需要时才创建：例如，当组件应按需创建时，或者出于性能考虑不应不必要地创建组件时。

以下是一个加载器，当点击MouseArea 时，它会将“Page1.qml”作为组件加载：

import QtQuick

Item {
    width: 200; height: 200

    Loader { id: pageLoader }

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

可通过item 属性访问已加载的对象。

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

加载器的尺寸调整行为

当用于加载可视化类型时，Loader 会应用以下尺寸调整规则：

• 如果未为 Loader 显式指定大小，则组件加载完成后，Loader 会自动调整为与所加载项相同的大小。
• 如果通过设置宽度、高度或锚点显式指定了 Loader 的大小，则加载项将调整为与 Loader 相同的大小。

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

import QtQuick

Item {
  width: 200; height: 200

  Loader {
    // Explicitly set the size of the
    // Loader to the parent item's size
    anchors.fill: parent
    sourceComponent: rect
  }

  Component {
    id: rect
    Rectangle {
      width: 50
      height: 50
      color: "red"
      }
  }
}

import QtQuick

Item {
  width: 200; height: 200

  Loader {
    // position the Loader in the center
    // of the parent
    anchors.centerIn: parent
    sourceComponent: rect
  }

  Component {
      id: rect
      Rectangle {
          width: 50
          height: 50
          color: "red"
      }
  }
}

如果源组件不是 Item 类型，Loader 不会应用任何特殊的尺寸调整规则。

从已加载对象接收信号

可以通过Connections 类型接收加载对象发出的任何信号。例如，下面的application.qml 加载了MyItem.qml ，并能通过Connections 对象接收来自已加载项的message 信号：

import QtQuick

Item {
    width: 100; height: 100

    Loader {
       id: myLoader
       source: "MyItem.qml"
    }

    Connections {
        target: myLoader.item
        function onMessage(msg) { console.log(msg) }
    }
}

import QtQuick

Rectangle {
   id: myItem
   signal message(string msg)

   width: 100; height: 100

   MouseArea {
       anchors.fill: parent
       onClicked: myItem.message("clicked!")
   }
}

焦点和键盘事件

Loader 是一个焦点作用域。其focus 属性必须设置为true ，其任何子项才能获得活动焦点。（更多详细信息请参阅 Qt Quick 中的“键盘焦点”。）在已加载项中接收的任何键事件也应设置为accepted ，以免其传播到 Loader。

例如，以下application.qml 在点击MouseArea 时会加载KeyReader.qml 。请注意，Loader 的focus 属性以及动态加载对象中的Item 均被设置为true ：

import QtQuick

Rectangle {
    width: 200; height: 200

    Loader {
        id: loader
        focus: true
    }

    MouseArea {
        anchors.fill: parent
        onClicked: {
            loader.source = "KeyReader.qml"
        }
    }

    Keys.onPressed: (event)=> {
        console.log("Captured:",
                    event.text);
    }
}

import QtQuick

Item {
    Item {
        focus: true
        Keys.onPressed: (event)=> {
            console.log("KeyReader captured:",
                        event.text);
            event.accepted = true;
        }
    }
}

一旦KeyReader.qml 加载完成，它便会接收键盘事件，并将event.accepted 设置为true ，从而确保该事件不会传播到父级Rectangle 。

由于QtQuick 2.0 ，Loader 还可以加载非视觉组件。

在视图委托中使用 Loader

在某些情况下，您可能希望在视图代理中使用 Loader 来提高代理的加载性能。这在大多数情况下效果良好，但需要注意一个与组件的creation context 相关的重要问题。

在下面的示例中，ListView 插入到delegateComponent 上下文中的index 上下文属性将无法被Text访问，因为Loader在实例化Text时会将myComponent 的创建上下文用作父上下文，而index 并不引用该上下文链中的任何内容。

Item {
    width: 400
    height: 400

    Component {
        id: myComponent
        Text { text: index }    //fails
    }

    ListView {
        anchors.fill: parent
        model: 5
        delegate: Component {
            id: delegateComponent
            Loader {
                sourceComponent: myComponent
            }
        }
    }
}

在这种情况下，我们可以将该组件移至内联，

        delegate: Component {
            Loader {
                sourceComponent: Component {
                    Text { text: index }    //okay
                }
            }
        }

将其移至单独的文件中，

        delegate: Component {
            Loader {
                source: "MyComponent.qml" //okay
            }
        }

或者显式地将所需信息设置为 Loader 的属性（此方法有效，因为 Loader 会将自身设为所加载组件的上下文对象）。

Item {
    width: 400
    height: 400

    Component {
        id: myComponent
        Text { text: modelIndex }    //okay
    }

    ListView {
        anchors.fill: parent
        model: 5
        delegate: Component {
            Loader {
                property int modelIndex: index
                sourceComponent: myComponent
            }
        }
    }
}

另请参阅 Dynamic Object Creation 。

属性文档

active : bool

如果加载器当前处于活动状态，则该属性的值为true 。该属性的默认值为true 。

如果加载器处于非活动状态，更改source 或sourceComponent 不会导致该项被实例化，直到加载器被设为活动状态为止。

将该值设置为“inactive”将导致加载器加载的任何item 被释放，但不会影响source 或sourceComponent 。

非活动加载器的status 始终为Null 。

另请参阅 source 和sourceComponent 。

asynchronous : bool

该属性用于控制组件是否以异步方式实例化。默认值为false 。

当与source 属性结合使用时，加载和编译操作也将在后台线程中进行。

异步加载会在多个帧中创建组件声明的对象，并降低动画出现卡顿的可能性。进行异步加载时，状态将变为 Loader.Loading。一旦整个组件创建完成，item 即可使用，且状态将变为 Loader.Ready。

在异步加载进行期间，将该属性的值更改为 `false ` 将强制立即以同步方式完成加载。这允许先开始异步加载，然后在必须在异步加载完成前访问 Loader 内容时强制完成加载。

若要避免显示项目渐进式加载过程，请适当设置visible ，例如：

Loader {
    source: "mycomponent.qml"
    asynchronous: true
    visible: status == Loader.Ready
}

请注意，此属性仅影响对象的实例化；它与通过网络异步加载组件无关。

item : QtObject [read-only]

该属性保存当前已加载的顶级对象。

自QtQuick 2.0 起，Loader 可以加载任何类型的对象。

progress : real [read-only]

该属性记录从网络加载 QML 数据的进度，范围从 0.0（尚未加载）到 1.0（已完成）。由于大多数 QML 文件体积较小，因此该值会迅速从 0 变为 1。

另请参阅 status 。

source : url

该属性存储要实例化的 QML 组件的 URL。

自QtQuick 2.0 起，Loader能够加载任何类型的对象；它不再仅限于Item类型。

要卸载当前加载的对象，请将此属性设置为空字符串，或将sourceComponent 设置为undefined 。将source 设置为新的URL也会导致由前一个URL创建的项被卸载。

另请参阅 sourceComponent 、status 和progress 。

sourceComponent : Component

该属性保存待实例化的Component 。

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

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

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

由于QtQuick 2.0 ，Loader 能够加载任何类型的对象；它并不局限于 Item 类型。

另请参阅 source 和progress 。

status : enumeration [read-only]

该属性用于表示 QML 的加载状态。其取值可能为以下之一：

• Loader.Null — 加载器处于非活动状态，或未设置任何 QML 源文件
• Loader.Ready — QML 源文件已加载完毕
• Loader.Loading - 当前正在加载 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' }

请注意，如果源是本地文件，状态初始值为 Ready（或 Error）。虽然这种情况下不会触发 onStatusChanged 信号，但 onLoaded 仍会被调用。

另请参阅 progress 。

信号文档

loaded()

当status 变为Loader.Ready 时，或在初始加载成功时，会触发此信号。

方法文档

void setSource(url source, var properties)

创建指定source 组件的对象实例，该实例将具有指定的properties 。properties 参数是可选的。加载和实例化完成后，可通过item 属性访问该实例。

如果在调用此函数时，active 属性为false ，则不会加载给定的source 组件，但会缓存source 和初始properties 。当加载器被设为active 时，将创建source 组件的实例，并设置初始properties 。

以这种方式设置组件实例的初始属性值不会触发任何相关的Behavior。

请注意，如果在调用此函数后、但设置加载器active 之前，source 或sourceComponent 发生变化，则缓存的properties 将被清空。

示例：

// ExampleComponent.qml
import QtQuick 2.0
Rectangle {
    id: rect
    color: "red"
    width: 10
    height: 10

    Behavior on color {
        NumberAnimation {
            target: rect
            property: "width"
            to: (rect.width + 20)
            duration: 0
        }
    }
}

// example.qml
import QtQuick 2.0
Item {
    Loader {
        id: squareLoader
        onLoaded: console.log(squareLoader.item.width);
        // prints [10], not [30]
    }

    Component.onCompleted: {
        squareLoader.setSource("ExampleComponent.qml",
                             { "color": "blue" });
        // will trigger the onLoaded code when complete.
    }
}

另请参阅 source 和active 。