Loader QML Type

Loader QML Type

允许从URL或组件动态加载子树。
导入方式：import QtQuick 2.11
继承于：Item

描述

加载器用于动态加载QML组件。

加载器可以加载QML文件（使用source属性）或Component对象（使用sourceComponent属性）。它有助于将组件的创建推迟到需要的时候：例如，当应该按需创建组件时，或者当出于性能原因不应该不必要地创建组件时。

这是一个加载器，当单击鼠标区域时，它会加载“Page1.qml”作为组件：

 import QtQuick 2.0

  Item {
      width: 200; height: 200

      Loader { id: pageLoader }

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

可以使用item属性访问加载的对象。

如果源或sourceComponent发生更改，则任何先前实例化的项都将被销毁。将源设置为空字符串或将sourceComponent设置为undefined会破坏当前加载的对象，释放资源并使加载器为空。

属性（Properties）

active : bool

如果加载器当前处于活动状态，则此属性为真。此属性的默认值为true。
如果加载器处于非活动状态，则在加载器处于活动状态之前，更改源或源组件不会导致项目被实例化。
将该值设置为非活动状态将导致加载器加载的任何项目被释放，但不会影响源或源组件。非活动加载器的状态始终为空。

asynchronous : bool（异步）

此属性保存组件是否将异步实例化。默认情况下，它为false。
当与源属性结合使用时，加载和编译也将在后台线程中执行。
异步加载会在多个帧中创建组件声明的对象，并降低动画中出现故障的可能性。异步加载时，状态将更改为Loader.Loaderling 一旦创建了整个组件，该项目将可用，状态将更改为Loader.Ready
在异步加载过程中将此属性的值更改为false将强制立即同步完成。这允许开始异步加载，然后在异步加载完成之前必须访问加载器内容时强制完成。
注意：为了避免项目被逐渐加载请适当设置可见

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

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

item : object

此属性保存当前加载的顶级对象

progress : real

此属性保存从网络加载QML数据的进度，从0.0（未加载）到1.0（已完成）。大多数QML文件都很小，因此该值将从0快速更改为1。

source : url

此属性保存要实例化的QML组件的URL。

从QtQuick 2.0开始，Loader可以加载任何类型的对象；它不限于项目类型。

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

sourceComponent : 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可以加载任何类型的对象；它不限于项目类型。

status : enumeration

This property holds the status of QML loading. It can be one of:

• 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' }

请注意，如果源是本地文件，则状态最初将为“就绪”（或“错误”）。虽然在这种情况下不会有onStatusChanged信号，但onLoaded仍将被调用。

信号（Signal Documentation）

loaded()

当状态变为Loader时，会发出此信号。准备就绪，或初始加载成功。
相应的处理程序为onLoaded。

方法（Method Documentation）

object setSource(url source, object properties)

创建具有给定属性的给定源组件的对象实例。properties参数是可选的。加载和实例化完成后，可以通过item属性访问实例。
如果调用此函数时活动属性为false，则不会加载给定的源组件，但会缓存源和初始属性。当加载器处于活动状态时，将创建一个源组件的实例，并设置初始属性。
以这种方式设置组件实例的初始属性值不会触发任何关联的行为。
请注意，如果在调用此函数后但在将加载器设置为活动状态之前更改了源或源组件，则缓存的属性将被清除。

loader 尺寸方面的行为

如果源组件不是Item类型，则Loader不会应用任何特殊的大小规则。当用于加载视觉类型时，Loader应用以下大小规则：

如果没有为加载器指定明确的大小，则加载组件后，加载器会自动调整为加载项的大小。

如果通过设置宽度、高度或锚定明确指定了加载器的大小，则加载的物品将调整为加载器的大小。

在这两种情况下，项目和加载器的大小是相同的。这确保了锚定到装载机上相当于锚定到所装载的物品上。

import QtQuick 2.0
import QtQuick.Window 2.0

Window {
    visible: true
    id: root
    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 2.0
import QtQuick.Window 2.0

Window {
    visible: true
    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"
        }
    }
}

红色矩形将为50x50，位于根项目的中心。

从loader 里面收到信号

可以使用Connections类型接收从加载对象发出的任何信号。例如，以下application.qml加载MyItem.qml，并能够通过Connections对象从加载的项目接收消息信号：
application.qml

  import QtQuick 2.0

  Item {
      width: 100; height: 100

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

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

MyItem.qml

  import QtQuick 2.0

  Rectangle {
     id: myItem
     signal message(string msg)

     width: 100; height: 100

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

或者，由于MyItem.qml是在Loader的作用域内加载的，它也可以直接调用Loader或其父Item中定义的任何函数。

Focus and Key Events(聚焦和键盘事件)

加载器是一个焦点范围。它的focus属性必须设置为true，以便它的任何子项都能获得活动焦点。加载项中收到的任何关键事件也应该被接受，这样它们就不会传播到加载器。

例如，当单击鼠标区域时，以下application.qml会加载KeyReader.qml。请注意，加载器的focus属性以及动态加载对象中的Item都设置为true：

application.qml

  import QtQuick 2.0

  Rectangle {
      width: 200; height: 200

      Loader {
          id: loader
          focus: true
      }

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

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

KeyReader.qml

import QtQuick 2.0

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

加载KeyReader.qml后，它接受关键事件并将event.accepted设置为true，这样事件就不会传播到父矩形。

Using a Loader within a View Delegate（使用一个视图代理 和 Loader一起）

在某些情况下，您可能希望在视图委托中使用加载器来提高委托加载性能。这在大多数情况下都很有效，但有一个重要的问题需要注意，这与组件的创建上下文有关。

在以下示例中，Text将无法访问ListView插入delegateComponent上下文中的索引上下文属性，因为加载器在实例化myComponent时将其创建上下文用作父上下文，而索引不引用该上下文链中的任何内容。

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

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