StackView QML Type

スタックベースのナビゲーションモデルを提供します。詳細...

Import Statement:	`import QtQuick.Controls`
Inherits:	Control

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

プロパティ

busy : bool
currentItem : Item
depth : int
empty : bool (since QtQuick.Controls 2.3 (Qt 5.10))
initialItem : var
popEnter : Transition
popExit : Transition
pushEnter : Transition
pushExit : Transition
replaceEnter : Transition
replaceExit : Transition

添付の信号

activated() (since QtQuick.Controls 2.1 (Qt 5.8))
activating() (since QtQuick.Controls 2.1 (Qt 5.8))
deactivated() (since QtQuick.Controls 2.1 (Qt 5.8))
deactivating() (since QtQuick.Controls 2.1 (Qt 5.8))
removed() (since QtQuick.Controls 2.1 (Qt 5.8))

方法

void clear(transition)
Item find(callback, behavior)
Item get(index, behavior)
Item pop(item, operation)
Item popCurrentItem(operation) (since 6.7)
Item popToIndex(index, operation) (since 6.7)
Item popToItem(item, operation) (since 6.7)
Item push(item, properties, operation)
Item pushItem(item, properties, operation) (since 6.7)
Item pushItem(component, properties, operation) (since 6.7)
Item pushItem(url, properties, operation) (since 6.7)
Item pushItems(items, operation) (since 6.7)
Item replace(target, item, properties, operation)
Item replaceCurrentItem(items, operation) (since 6.7)
Item replaceCurrentItem(item, properties, operation) (since 6.7)
Item replaceCurrentItem(component, properties, operation) (since 6.7)
Item replaceCurrentItem(url, properties, operation) (since 6.7)

詳細説明

ページナビゲーションを示すスタックビューのワイヤーフレーム

StackViewは、相互にリンクされた一連の情報ページで使用できます。例えば、最新のメールを一覧表示するビュー、特定のメールを表示するビュー、添付ファイルを一覧表示・閲覧するビューがそれぞれ独立しているメールアプリケーションなどが挙げられます。ユーザーがメールを開くと、メール一覧ビューがスタックにプッシュされ、戻る操作を行うとスタックからポップされます。

以下のスニペットは、関連するボタンがクリックされた際にmainView がスタックにプッシュされ、ポップアウトされるという単純なユースケースを示しています：

ApplicationWindow {
    title: qsTr("Hello World")
    width: 640
    height: 480
    visible: true

    StackView {
        id: stack
        initialItem: mainView
        anchors.fill: parent
    }

    Component {
        id: mainView

        Row {
            spacing: 10

            Button {
                text: "Push"
                onClicked: stack.push(mainView)
            }
            Button {
                text: "Pop"
                enabled: stack.depth > 1
                onClicked: stack.pop()

            }
            Text {
                text: stack.depth
            }
        }
    }
}

アプリケーションでの StackView の使用

アプリケーションで StackView を使用するには、Window の子要素として追加するだけで済みます。スタックは通常、ウィンドウの端に固定されますが、上部や下部については、ステータスバーやその他の類似した UI コンポーネントに固定される場合があります。スタックは、ナビゲーションメソッドを呼び出すことで利用できます。StackViewに最初に表示されるアイテムは、initialItem に割り当てられたアイテム、またはinitialItem が設定されていない場合は最上位のアイテムです。

StackViewは、push()、pop()、replace()という3つの主要なナビゲーション操作をサポートしています。これらは、従来のスタック操作に対応しており、「push」はスタックの先頭に項目を追加し、「pop」はスタックの先頭から項目を削除し、「replace」は「pop」の後に「push」を行うようなもので、最上位の項目を新しい項目に置き換えます。スタックの最上部の項目は、画面上に表示されている項目（currently ）に対応します。論理的には、「push」はアプリケーションの UI 内で前方またはより深い場所へ移動し、「pop」は後方へ移動し、「replace」はcurrentItem を置き換えます。

項目のプッシュ

次のアニメーションでは、push() 関数を使用して、3つのLabel コントロールがスタックビューにプッシュされています：

スタックには現在、以下の項目が含まれています：[A, B, C] 。

注：スタックが空の場合 、push() 操作では遷移アニメーションは発生しません。これは、遷移元のアイテムが存在しないためです（通常、アプリケーションの起動時など）。

項目のポップ

上記の例に続き、pop() を呼び出すことで、スタックの最上位の項目が削除されます:

これにより、スタックには以下のアイテムが含まれるようになります：[A, B] 。

注：深さが 1 または 0 のスタックに対して` pop()` を実行しても、何も起こりません。そのような場合は、`clear()` メソッドを使用してスタックを空にすることができます。

Pop による項目の巻き戻し

場合によっては、スタックを 1 ステップ以上遡る必要があります。たとえば、アプリケーション内の「メイン」項目や、ある種のセクション項目に戻る場合などです。そのような場合、pop() のパラメータとして項目を指定することができます。これは「アンワインド」操作と呼ばれ、スタックは指定された項目まで巻き戻されます。指定したアイテムが見つからない場合、スタックはアイテムが1つになるまで巻き戻され、そのアイテムがcurrentItem となります。スタックの最下層まで明示的に巻き戻すには、pop(null)を使用することを推奨しますが、存在しない任意のアイテムでも代用可能です。

次のアニメーションでは、pop(null) を呼び出して、スタックを最初の項目までアンワインドしています：

スタックには現在、[A] という1つの項目が含まれています。

項目の置換

次のアニメーションでは、replace を使用して、最上位の項目をD に置き換えます：

スタックには現在、[A, B, D] という要素が含まれています。

ディープリンク

ディープリンクとは、アプリケーションを特定の状態から起動することを意味します。例えば、新聞アプリの場合、最上位のアイテムをスキップして、特定の記事を表示した状態から起動することが可能です。 StackViewの観点から言えば、ディープリンクとはスタックの状態を変更する機能を意味します。具体的には、一連のアイテムをスタックの先頭にプッシュしたり、スタックを所定の状態に完全にリセットしたりすることが可能です。

StackView におけるディープリンク用の API は、基本的なナビゲーションの場合と同じです。単一のアイテムの代わりに配列をプッシュすると、その配列内のすべてのアイテムがスタックに追加されます。ただし、遷移アニメーションは配列の最後のアイテムに対してのみ適用されます。push() の通常の動作はディープリンクにも適用されます。つまり、スタックにプッシュされたものはすべて追加されます。

注：ロードされるのは配列の最後の項目のみです 。残りの項目は、その後の pop の呼び出し時、またはget() を使用して項目を取得するリクエストがあった際に、必要に応じてのみロードされます。

スタックが [A, B, C] である場合、以下の結果が得られます：

push([D, E, F]) => [A, B, C, D, E, F] - CとF間の「push」遷移アニメーション
replace([D, E, F]) => [A, B, D, E, F] - CとF間の「置換」遷移アニメーション
clear() の後に `push` を実行すると：([D, E, F]) => [D, E, F] — スタックが空だったため、アイテムをプッシュする際の遷移アニメーションは発生しません。

アイテムの検索

アプリケーションが参照を持っていない項目は、find() を呼び出すことで見つけることができます。このメソッドにはコールバック関数が必要であり、一致する項目が見つかるまで、スタック内の各項目（先頭から順に）に対してこのコールバック関数が呼び出されます。コールバックが `true` を返した場合、find() は処理を中止して一致した項目を返します。それ以外の場合は `null ` が返されます。

以下のコードは、スタック内で「order_id」という名前の項目を検索し、その項目までスタックを巻き戻します。

stackView.pop(stackView.find(function(item) {
    return item.name == "order_id";
}));

また、get(index) を使用して、スタック内の項目にアクセスすることもできます。

previousItem = stackView.get(myItem.StackView.index - 1));

遷移

push または pop 操作が行われるたびに、スタックに入るアイテムとスタックから出るアイテムに、それぞれ異なる遷移アニメーションが適用されます。これらのアニメーションは、スタックに入るアイテムがどのようにアニメーションで登場し、スタックから出るアイテムがどのようにアニメーションで退場するかを定義します。StackView のpushEnter 、pushExit 、popEnter 、popExit 、replaceEnter 、およびreplaceExit プロパティに異なるTransitions を割り当てることで、アニメーションをカスタマイズできます。

注：トランジションアニメーションは、互いの遷移動作に影響を及ぼします。一方のアニメーションをカスタマイズし、もう一方をそのままにしておくと、予期しない結果になる可能性があります。

以下のスニペットは、push および pop 操作に対する単純なフェード遷移を定義しています：

StackView {
    id: stackview
    anchors.fill: parent

    pushEnter: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 0
            to:1
            duration: 200
        }
    }
    pushExit: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 1
            to:0
            duration: 200
        }
    }
    popEnter: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 0
            to:1
            duration: 200
        }
    }
    popExit: Transition {
        PropertyAnimation {
            property: "opacity"
            from: 1
            to:0
            duration: 200
        }
    }
}

注： StackViewに追加されたアイテムでのアンカーの使用は サポートされていません。通常、push、pop、およびreplaceの遷移では位置がアニメーション化されますが、アンカーが適用されている場合はこれが不可能です。これはアイテムのルート要素にのみ適用される点に注意してください。子要素に対してアンカーを使用する場合は、期待どおりに動作します。

アイテムの所有権

StackViewは、自身で作成したアイテムのみを所有します。つまり、StackViewにプッシュされたアイテムは、StackViewによって破棄されることはありません。StackViewがComponents やURLs から作成したアイテムのみが、StackViewによって破棄されます。これを説明するために、以下の例のメッセージは、アイテムがスタックからポップされたときではなく、StackViewが破棄されたときにのみ出力されます:

Component {
    id: itemComponent

    Item {
        Component.onDestruction: print("Destroying second item")
    }
}

StackView {
    initialItem: Item {
        Component.onDestruction: print("Destroying initial item")
    }

    Component.onCompleted: push(itemComponent.createObject(window))
}

一方、次の例で URL および Component から作成された 2 つのアイテムは、スタックからポップされた際に StackView によって破棄されます：

Component {
    id: itemComponent

    Item {
        Component.onDestruction: print("Destroying second item")
    }
}

StackView {
    initialItem: "Item1.qml"

    Component.onCompleted: push(itemComponent)
}

サイズ

StackViewは、プッシュされたアイテムから暗黙的なサイズを継承しません。つまり、例えばDialog のcontentItem として使用した場合、期待どおりに動作しません:

Dialog {
    StackView {
        initialItem: Rectangle {
            width: 200
            height: 200
            color: "salmon"
        }
    }
}

この状況でStackViewにサイズを確保するには、いくつかの方法があります：

StackView 自体に `implicitWidth ` と `implicitHeight ` を設定します。
Rectangle に対してimplicitWidth およびimplicitHeight を設定する。
ダイアログに対して、contentWidth およびcontentHeight を設定します。
Dialogのサイズを指定します。

『Qt Quick コントロール』の「StackView のカスタマイズ」、「StackView によるナビゲーション」、「ナビゲーションコントロール」、「コンテナコントロール」、「フォーカス管理」も参照してください 。

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

busy : bool `[read-only]`

このプロパティは、遷移が実行中かどうかを表します。

currentItem : Item `[read-only]`

このプロパティには、スタックの最上位にある現在の項目が格納されます。

depth : int `[read-only]`

このプロパティには、現在スタックにプッシュされている項目の数が格納されます。

empty : bool `[read-only, since QtQuick.Controls 2.3 (Qt 5.10)]`

このプロパティは、スタックが空であるかどうかを表します。

このプロパティは、QtQuick.Controls 2.3 (Qt 5.10) で導入されました。

depthも参照してください。

initialItem : var

このプロパティには、StackView の作成時に表示されるべき初期アイテムが格納されます。初期アイテムとしては、Item 、Component 、またはurl を指定できます。初期アイテムを指定することは、以下と同じ意味になります：

Component.onCompleted: stackView.push(myInitialItem)

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

popEnter : Transition

このプロパティは、スタックから別のアイテムがポップされた際に、スタックに追加されるアイテムに適用されるトランジションを保持します。

「StackViewのカスタマイズ」も参照してください 。

popExit : Transition

このプロパティは、スタックからポップされたアイテムに対して適用されるトランジションを保持します。

「StackViewのカスタマイズ」も参照してください 。

pushEnter : Transition

このプロパティは、スタックにアイテムがプッシュされた際に、そのスタックに入ったアイテムに適用されるトランジションを保持します。

「StackViewのカスタマイズ」も参照してください 。

pushExit : Transition

このプロパティは、スタックに別のアイテムがプッシュされた際に、スタックから排出されるアイテムに適用されるトランジションを保持します。

「StackViewのカスタマイズ」も参照してください 。

replaceEnter : Transition

このプロパティは、あるアイテムが別のアイテムと入れ替わってスタックに入る際に、そのアイテムに適用されるトランジションを保持します。

「StackViewのカスタマイズ」も参照してください 。

replaceExit : Transition

このプロパティには、スタックから退出するアイテムが別のアイテムに置き換えられる際に適用されるトランジションが格納されます。

「StackViewのカスタマイズ」も参照してください 。

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

StackView.index : int `[read-only attached]`

このアタッチされたプロパティには、それがアタッチされているアイテムのスタックインデックスが格納されます。ただし、そのアイテムがスタックに含まれていない場合は、-1 が格納されます。

StackView.status : enumeration `[read-only attached]`

このアタッチメントプロパティは、それがアタッチされているアイテムのスタック状態を保持します。アイテムがスタックに属していない場合は、StackView.Inactive となります。

利用可能な値：

定数	説明
`StackView.Inactive`	アイテムは非アクティブ（またはスタックに属していない）状態です。
`StackView.Deactivating`	アイテムの非アクティブ化（スタックからのポップ）が行われています。
`StackView.Activating`	そのアイテムがアクティブ化されている（現在のアイテムになりつつある）。
`StackView.Active`	そのアイテムはアクティブ、つまり現在のアイテムです。

StackView.view : StackView `[read-only attached]`

このアタッチされたプロパティには、それがアタッチされているアイテムのスタックビューが保持されます。アイテムがスタックに含まれていない場合は、null が保持されます。

StackView.visible : bool `[attached, since QtQuick.Controls 2.2 (Qt 5.9)]`

この関連付けられたプロパティは、関連付けられている項目の表示状態を保持します。その値は、Item::visible の値に従います。

デフォルトでは、StackView は、enterトランジションの開始時に表示されるアイテムを表示し、exitトランジションの終了時に非表示になるアイテムを非表示にします。このプロパティを明示的に設定することで、デフォルトの動作を上書きし、最上部のアイテムの下にあるアイテムを表示したままにすることができます。

注：ほとんどのスタイルのデフォルトの遷移では 、表示されなくなるアイテムがビューの外へスライドして移動し、不透明度のアニメーションが行われる場合もあります。アイテムのスタック全体を表示したままにするには、transitions をカスタマイズして、下にあるアイテムが見えるようにすることを検討してください。

可視性の挙動を示すスタックビュー

StackView {
    id: stackView
    property real offset: 10
    width: 100; height: 100

    initialItem: Component {
        id: page
        Rectangle {
            property real pos: StackView.index * stackView.offset
            property real hue: Math.random()
            color: Qt.hsla(hue, 0.5, 0.8, 0.6)
            border.color: Qt.hsla(hue, 0.5, 0.5, 0.9)
            StackView.visible: true
        }
    }

    pushEnter: Transition {
        id: pushEnter
        ParallelAnimation {
            PropertyAction { property: "x"; value: pushEnter.ViewTransition.item.pos }
            NumberAnimation { properties: "y"; from: pushEnter.ViewTransition.item.pos + stackView.offset; to: pushEnter.ViewTransition.item.pos; duration: 400; easing.type: Easing.OutCubic }
            NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 400; easing.type: Easing.OutCubic }
        }
    }
    popExit: Transition {
        id: popExit
        ParallelAnimation {
            PropertyAction { property: "x"; value: popExit.ViewTransition.item.pos }
            NumberAnimation { properties: "y"; from: popExit.ViewTransition.item.pos; to: popExit.ViewTransition.item.pos + stackView.offset; duration: 400; easing.type: Easing.OutCubic }
            NumberAnimation { property: "opacity"; from: 1; to: 0; duration: 400; easing.type: Easing.OutCubic }
        }
    }

    pushExit: Transition {
        id: pushExit
        PropertyAction { property: "x"; value: pushExit.ViewTransition.item.pos }
        PropertyAction { property: "y"; value: pushExit.ViewTransition.item.pos }
    }
    popEnter: Transition {
        id: popEnter
        PropertyAction { property: "x"; value: popEnter.ViewTransition.item.pos }
        PropertyAction { property: "y"; value: popEnter.ViewTransition.item.pos }
    }
}

このプロパティは、QtQuick.Controls 2.2 (Qt 5.9) で導入されました。