Loader3D QML Type

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

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

属性

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

信号

• loaded()

方法

• object setSource(url source, object properties)

详细说明

Loader3D 用于为Qt Quick 3D 动态加载 QML 组件。

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

属性文档

active : bool

如果“Loader3D ”当前处于活动状态，则该属性的值为true 。该属性的默认值为true 。

如果“Loader3D ”处于非活动状态，即使更改“source ”或“sourceComponent ”，该项也不会被实例化，直到将“Loader3D ”设为活动状态为止。

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

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

另请参阅 source 和sourceComponent 。

asynchronous : bool

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

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

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

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

若要避免显示项的渐进式加载效果，请适当设置 `visible `，例如：

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

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

item : object [read-only]

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

progress : real [read-only]

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

另请参阅 status 。

source : url

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

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

另请参阅 sourceComponent 、status 和progress 。

sourceComponent : Component

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

Item {
    Component {
        id: redCube
        Model {
            source: "#Cube"
            materials: DefaultMaterial {
                diffuseColor: "red"
            }
        }
    }

    Loader3D { sourceComponent: redCube }
    Loader3D { sourceComponent: redCube; x: 10 }
}

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

另请参阅 source 和progress 。

status : enumeration [read-only]

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

请使用此状态来提供更新信息，或以某种方式响应状态变化。例如，您可以：

• 触发状态变化：

  State { name: 'loaded'; when: loader.status == Loader3D.Ready }

• 实现onStatusChanged 信号处理程序：

  Loader3D {
      id: loader
      onStatusChanged: if (loader.status == Loader3D.Ready) console.log('Loaded')
  }

• 绑定到状态值：

  Text { text: loader.status == Loader3D.Ready ? 'Loaded' : 'Not loaded' }

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

另请参阅 progress 。

信号文档

loaded()

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

相应的处理程序是onLoaded 。

方法文档

object setSource(url source, object properties)

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

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

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

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

另请参阅 source 和active 。