Component QML Type

QMLコンポーネントの定義をカプセル化します。詳細...

• 継承されたメンバーを含む、すべてのメンバーの一覧

プロパティ

• progress : real
• status : enumeration
• url : url

添付の信号

• completed()
• destruction()

方法

• QtObject createObject(QtObject parent, var properties)
• string errorString()
• var incubateObject(QtObject parent, var properties, enumeration mode)

詳細な説明

コンポーネントとは、明確に定義されたインターフェースを持つ、再利用可能でカプセル化されたQML型です。

コンポーネントは、多くの場合、コンポーネントファイル、つまり.qml ファイルによって定義されます。Component型を使用すると、QML コンポーネントを個別の QML ファイルとしてではなく、QML ドキュメント内でインラインで定義することができます。これは、QML ファイル内で小さなコンポーネントを再利用する場合や、ファイル内の他の QML コンポーネントと論理的に関連するコンポーネントを定義する場合に役立ちます。

たとえば、以下は複数の `Loader ` オブジェクトで使用されるコンポーネントです。これには、Rectangle という単一のアイテムが含まれています：

import QtQuick

Item {
    width: 100; height: 100

    Component {
        id: redSquare

        Rectangle {
            color: "red"
            width: 10
            height: 10
        }
    }

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

Rectangle 自体は自動的にレンダリングされて表示されますが、上記の矩形はComponent 内に定義されているため、そうはならない点に注意してください。このコンポーネントは、あたかも別のQMLファイルで定義されているかのように内部のQML型をカプセル化しており、要求されるまで（この場合は2つのLoader オブジェクトによって）読み込まれません。 ComponentはItemを継承していないため、これに何かをアンカーすることはできません。

Component の定義は、QMLドキュメントの定義と似ています。QMLドキュメントには、そのコンポーネントの挙動やプロパティを定義する単一のトップレベルアイテムがあり、そのトップレベルアイテムの外側でプロパティや挙動を定義することはできません。 同様に、Component の定義には単一のトップレベル項目（上記の例ではRectangle ）が含まれており、id（上記の例ではredSquare）を除き、この項目の外でデータを定義することはできません。

Component 型は、ビュー用のグラフィカルコンポーネントを提供するために一般的に使用されます。たとえば、ListView::delegate プロパティでは、各リスト項目をどのように表示するかを指定するためにComponent が必要です。

Component Qt.createComponent() を使用すると、オブジェクトを動的に作成することもできます。

Componentsは、新しいファイルを丸ごと追加することなく、その型のインスタンスのみが必要な場合に型を宣言するのに便利です。ただし、この型に名前を付けることはできず、その結果、プロパティの宣言や型アノテーションでの使用には利用できません。これが必要な場合は、インラインコンポーネントの使用を優先してください。

作成コンテキスト

コンポーネントの作成コンテキストは、そのコンポーネントが宣言されたコンテキストに対応します。このコンテキストは、ListView やLoaderなどのオブジェクトによってコンポーネントがインスタンス化される際、親コンテキストとして使用され（コンテキスト階層を形成します）。

次の例では、comp1 はMyItem.qmlのルートコンテキスト内で作成されており、このコンポーネントからインスタンス化されたオブジェクトはすべて、internalSettings.color など、そのコンテキスト内のIDやプロパティにアクセスできます。comp1 が別のコンテキスト（以下の main.qml のように）でListView デリゲートとして使用される場合、そのコンテキストは引き続き、作成コンテキストのプロパティにアクセスできます（そうでなければ、外部ユーザーに対しては非公開となります）。

Item {
    property Component mycomponent: comp1

    QtObject {
        id: internalSettings
        property color color: "green"
    }

    Component {
        id: comp1
        Rectangle { color: internalSettings.color; width: 400; height: 50 }
    }
}

ListView {
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //will create green Rectangles

    MyItem { id: myItem }
}

作成コンテキストのライフタイムは、作成されたオブジェクトのライフタイムよりも長く続くことが重要です。詳細については、「動的に作成されたオブジェクトの維持」を参照してください。

プロパティのドキュメント

progress : real [read-only]

コンポーネントの読み込みの進行状況。0.0（読み込みなし）から1.0（完了）まで。

status : enumeration [read-only]

このプロパティは、コンポーネントの読み込み状態を表します。状態は以下のいずれかになります：

url : url [read-only]

コンポーネントのURL。これは、コンポーネントの構築に使用されたURLです。

添付のシグナルに関するドキュメント

[attached] completed()

オブジェクトのインスタンス化後に発行されます。これは、完全な QML 環境が構築された後、起動時にスクリプトコードを実行するために使用できます。

onCompleted シグナルハンドラは、任意のオブジェクトで宣言できます。ハンドラの実行順序は未定義です。

Rectangle {
    Component.onCompleted: console.log("Completed Running!")
    Rectangle {
        Component.onCompleted: console.log("Nested Completed Running!")
    }
}

[attached] destruction()

オブジェクトの破棄が開始される際に発火します。これは、completed() シグナルへの応答として実行された処理や、アプリケーション内のその他の命令型コードを元に戻すために使用できます。

onDestruction シグナルのハンドラは、どのオブジェクトに対しても宣言できます。ハンドラの実行順序は未定義です。

Rectangle {
    Component.onDestruction: console.log("Destruction Beginning!")
    Rectangle {
        Component.onDestruction: console.log("Nested Destruction Beginning!")
    }
}

関連項目 Qt Qml。

メソッドのドキュメント

QtObject createObject(QtObject parent, var properties)

指定されたparent およびproperties を持つ、このコンポーネントのオブジェクトインスタンスを作成して返します。properties 引数はオプションです。オブジェクトの作成に失敗した場合はnullを返します。

オブジェクトは、コンポーネントが作成されたのと同じコンテキスト内で作成されます。QML以外で作成されたコンポーネントに対してこの関数を呼び出した場合、常にnullが返されます。

親を設定せずにオブジェクトを作成したい場合は、parent の値としてnull を指定してください。なお、返されたオブジェクトを表示する場合は、有効なparent の値を指定するか、返されたオブジェクトのparent プロパティを設定する必要があります。そうしないと、オブジェクトは表示されません。

createObject() にparent が指定されていない場合、ガベージコレクタによって破棄されないよう、返されたオブジェクトへの参照を保持する必要があります。これは、後でItem::parent が設定されるかどうかに関係なく当てはまります。なぜなら、Item 親を設定してもオブジェクトの所有権は変更されず、グラフィカルな親のみが変更されるからです。

このメソッドは、作成されるオブジェクトの初期プロパティ値のマップを指定するオプションのproperties 引数を受け付けます。これらの値は、オブジェクトの作成が完了する前に適用されます。これは、オブジェクト作成後にプロパティ値を設定するよりも効率的であり、特に大量のプロパティ値が定義されている場合に有効です。また、オブジェクトが作成される前に（Qt.binding を使用して）プロパティのバインディングを設定することも可能になります。

properties 引数は、プロパティと値のペアからなるマップとして指定します。たとえば、以下のコードは、x とy の初期値をそれぞれ100と100に設定したオブジェクトを作成します。

const component = Qt.createComponent("Button.qml");
if (component.status === Component.Ready) {
    component.createObject(parent, { x: 100, y: 100 });
}

動的に作成されたインスタンスは、destroy() メソッドを使用して削除できます。詳細については、「JavaScriptからの動的なQMLオブジェクトの作成」を参照してください。

「incubateObject()」も参照してください 。

string errorString()

エラーに関する、人間が読みやすい説明を返します。

この文字列には、各エラーのファイル名、発生場所、および説明が含まれます。複数のエラーがある場合は、改行文字で区切られます。

エラーが存在しない場合は、空の文字列が返されます。

var incubateObject(QtObject parent, var properties, enumeration mode)

このコンポーネントのインスタンス用のインキュベーターを作成します。インキュベーターを使用すると、新しいコンポーネントのインスタンスを非同期で生成でき、UIのフリーズを防ぐことができます。

parent 引数は、作成されるインスタンスの親を指定します。このパラメータを省略するかnullを渡すと、親を持たないオブジェクトが作成されます。この場合、ガベージコレクタによってオブジェクトが破棄されないように、作成されたオブジェクトへの参照を保持しておく必要があります。

properties 引数は、プロパティと値のペアからなるマップとして指定され、作成されたオブジェクトの構築時にそのオブジェクトに設定されます。mode はQt.SynchronousまたはQt.Asynchronousのいずれかを指定でき、インスタンスが同期的に作成されるか非同期的に作成されるかを制御します。 デフォルトは非同期です。状況によっては、Qt.Synchronousが指定されていても、incubatorがオブジェクトを非同期で生成する場合があります。これは、incubateObject()を呼び出すコンポーネント自体が非同期で生成されている場合に発生します。

3つの引数すべてがオプションです。

成功した場合、このメソッドはインキュベーターを返し、失敗した場合は null を返します。インキュベーターには以下のプロパティがあります：

• status - インキュベータの状態。有効な値は Component.Ready、Component.Loading、Component.Error です。
• object - 作成されたオブジェクトのインスタンス。インキュベーターが Ready 状態になって初めて利用可能になります。
• onStatusChanged - ステータスが変更された際に呼び出されるコールバック関数を指定します。ステータスはコールバックのパラメータとして渡されます。
• forceCompletion() - インキュベーションを同期的に完了させるための呼び出し。

以下の例は、インキュベーターの使用方法を示しています：

const component = Qt.createComponent("Button.qml");

const incubator = component.incubateObject(parent, { x: 10, y: 10 });
if (incubator.status !== Component.Ready) {
    incubator.onStatusChanged = function(status) {
        if (status === Component.Ready) {
            print("Object", incubator.object, "is now ready!");
        }
    };
} else {
    print("Object", incubator.object, "is ready immediately!");
}

動的に作成されたインスタンスは、destroy() メソッドを使用して削除できます。詳細については、「JavaScript からの動的な QML オブジェクトの作成」を参照してください。

createObject()も参照してください 。