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」をコンポーネントとして読み込むLoaderの例です：

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のサイズは同一になります。これにより、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 の「キーボードフォーカス」を参照してください。）読み込まれたアイテムで受信したキーイベントも、Loaderに伝播されないように、accepted に設定する必要があります。

たとえば、次の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 に関連して注意すべき重要な点が 1 つあります。

次の例では、ListView によってdelegateComponent のコンテキストに挿入されたindex コンテキストプロパティは、Text からアクセスできません。これは、Loader が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

このプロパティは、Loaderが現在アクティブな場合、true となります。このプロパティのデフォルト値はtrue です。

Loaderが非アクティブな場合、source またはsourceComponent を変更しても、Loaderがアクティブになるまではそのアイテムはインスタンス化されません。

この値を `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 に設定されると、初期のproperties が設定されたsource コンポーネントのインスタンスが作成されます。

この方法でコンポーネントのインスタンスの初期プロパティ値を設定しても、関連する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も参照してください 。