ListView QML Type

モデルが提供する項目のリスト表示を行います。詳細...

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

プロパティ

• add : Transition
• addDisplaced : Transition
• cacheBuffer : int
• count : int
• currentIndex : int
• currentItem : Item
• currentSection : string
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• displaced : Transition
• displayMarginBeginning : int (since QtQuick 2.3)
• displayMarginEnd : int (since QtQuick 2.3)
• effectiveLayoutDirection : enumeration
• footer : Component
• footerItem : Item
• footerPositioning : enumeration (since Qt 5.4)
• header : Component
• headerItem : Item
• headerPositioning : enumeration (since Qt 5.4)
• highlight : Component
• highlightFollowsCurrentItem : bool
• highlightItem : Item
• highlightMoveDuration : int
• highlightMoveVelocity : real
• highlightRangeMode : enumeration
• highlightResizeDuration : int
• highlightResizeVelocity : real
• keyNavigationEnabled : bool
• keyNavigationWraps : bool
• layoutDirection : enumeration
• model : model
• move : Transition
• moveDisplaced : Transition
• orientation : enumeration
• populate : Transition
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• remove : Transition
• removeDisplaced : Transition
• reuseItems : bool
• section
  • section.criteria : enumeration
  • section.delegate : Component
  • section.labelPositioning : enumeration
  • section.property : string
• snapMode : enumeration
• spacing : real
• verticalLayoutDirection : enumeration

関連するプロパティ

• delayRemove : bool
• isCurrentItem : bool
• nextSection : string
• previousSection : string
• section : string
• view : ListView

添付の信号

• add()
• pooled()
• remove()
• reused()

方法

• void decrementCurrentIndex()
• void forceLayout()
• void incrementCurrentIndex()
• int indexAt(real x, real y)
• Item itemAt(real x, real y)
• Item itemAtIndex(int index)
• void positionViewAtBeginning()
• void positionViewAtEnd()
• void positionViewAtIndex(int index, PositionMode mode)

詳細な説明

ListViewは、ListModel やXmlListModel といった組み込みのQML型から作成されたモデル、あるいはQAbstractItemModel やQAbstractListModel を継承するC++で定義されたカスタムモデルクラスからのデータを表示します。

ListViewには、表示するデータを定義するmodel と、データの表示方法を定義するdelegate があります。ListView内の項目は、水平方向または垂直方向に配置されます。ListViewはFlickable を継承しているため、本質的にフリック操作が可能です。

使用例

次の例は、ContactModel.qml というファイルに定義された単純なリストモデルの定義を示しています：

import QtQuick

ListModel {
    ListElement {
        name: "Bill Smith"
        number: "555 3264"
    }
    ListElement {
        name: "John Brown"
        number: "555 8426"
    }
    ListElement {
        name: "Sam Wise"
        number: "555 0473"
    }
}

別のコンポーネントでは、次のようにしてこのモデルデータをListViewに表示できます：

import QtQuick

ListView {
    width: 180; height: 200

    model: ContactModel {}
    delegate: Text {
        required property string name
        required property string number
        text: name + ": " + number
    }
}

ここでは、ListViewがそのモデル用にContactModel コンポーネントを作成し、デリゲート用にText アイテムを作成します。ビューは、モデル内の各アイテムに対して新しいText コンポーネントを作成します。デリゲートがモデルのname およびnumber データに直接アクセスできる点に注目してください。

改良されたリストビューを以下に示します。デリゲートの外観が改善され、独立したcontactDelegate コンポーネント内に移動されています。

Rectangle {
    width: 180; height: 200

    Component {
        id: contactDelegate
        Item {
            id: myItem
            required property string name
            required property string number
            width: 180; height: 40
            Column {
                Text { text: '<b>Name:</b> ' + myItem.name }
                Text { text: '<b>Number:</b> ' + myItem.number }
            }
        }
    }

    ListView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: contactDelegate
        highlight: Rectangle { color: "lightsteelblue"; radius: 5 }
        focus: true
    }
}

現在選択されている項目は、highlight プロパティを使用して青いRectangle で強調表示され、focus はtrue に設定されており、これによりリストビューでのキーボードナビゲーションが可能になっています。リストビュー自体はフォーカススコープです（詳細については、『Qt Quick 』の「Keyboard Focus」を参照してください）。

デリゲートは必要に応じてインスタンス化され、いつでも破棄される可能性があります。そのため、 state should never be stored in a delegate。デリゲートは通常、ListViewのcontentItem を親としていますが、ビュー内で表示されているかどうかに応じて親が変更されることが多く、場合によってはnull になることもあります。そのため、デリゲート内部から親のプロパティにバインドすることは推奨されません。 デリゲートが ListView の幅いっぱいに広がるようにしたい場合は、代わりに以下のいずれかのアプローチを検討してください。

ListView {
    id: listView
    // ...

    delegate: Item {
        // Incorrect.
        width: parent.width

        // Correct.
        width: listView.width
        width: ListView.view.width
        // ...
    }
}

ListViewは、デリゲートのルートアイテムにいくつかのプロパティをアタッチします。例えば、ListView.isCurrentItem などです。次の例では、ルートデリゲートアイテムはListView.isCurrentItem としてこのアタッチされたプロパティに直接アクセスできますが、子contactInfo オブジェクトはこのプロパティをwrapper.ListView.isCurrentItem として参照する必要があります。

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

ListView のレイアウト

ListView 内の項目のレイアウトは、以下のプロパティによって制御できます。

• orientation - アイテムが水平方向か垂直方向に配置されるかを制御します。この値は Qt.Horizontal または Qt.Vertical のいずれかです。
• layoutDirection - 水平方向のビューにおける水平レイアウトの方向を制御します。つまり、アイテムがビューの左側から右側へ配置されるか、その逆かを指定します。この値は Qt.LeftToRight または Qt.RightToLeft のいずれかです。
• verticalLayoutDirection - 垂直方向のビューにおける水平レイアウトの方向を制御します。つまり、アイテムがビューの上部から下部に向かって配置されるか、その逆になるかを指定します。この値は ListView.TopToBottom または ListView.BottomToTop のいずれかです。

デフォルトでは、ListViewは垂直方向の配置となり、アイテムは上から下へと配置されます。以下の表は、上記のプロパティの値に応じてListViewが取り得るさまざまなレイアウトを示しています。

フリック可能方向

デフォルトでは、縦方向の ListView では `flickableDirection ` が`Flickable.Vertical` に、横方向の ListView では`Flickable.Horizontal` に設定されます。さらに、縦方向の ListView では `contentHeight` のみが計算（推定）され、横方向の ListView では `contentWidth` のみが計算されます。もう一方の次元は-1 に設定されます。

Qt 5.9（Qt Quick 2.9）以降では、両方向にフリックできる ListView を作成することが可能になりました。 これを行うには、flickableDirection をFlickable.AutoFlickDirectionまたはFlickable.AutoFlickIfNeededに設定し、必要なcontentWidthまたはcontentHeightを指定する必要があります。

ListView {
    width: 180; height: 200

    contentWidth: 320
    flickableDirection: Flickable.AutoFlickDirection

    model: ContactModel {}
    delegate: Row {
        Text { text: '<b>Name:</b> ' + name; width: 160 }
        Text { text: '<b>Number:</b> ' + number; width: 160 }
    }
}

ListView におけるスタック順

項目のZ value は、その項目が他の項目の上か下かにレンダリングされるかを決定します。ListViewは、作成される項目のタイプに応じて、いくつかの異なるデフォルトのZ値を使用します：

これらのデフォルト値は、アイテムのZ値が0 の場合に設定されるため、これらのアイテムのZ値を0 に設定しても効果はありません。なお、Z値の型はreal であるため、0.1 のような小数値を設定することが可能です。

項目の再利用

バージョン5.15以降、ListViewでは、新しい行がフリック操作によって表示領域に表示されるたびに、delegate からインスタンス化を行う代わりに、アイテムを再利用するように設定できるようになりました。このアプローチは、デリゲートの複雑さに応じてパフォーマンスを向上させます。アイテムの再利用は（下位互換性の理由から）デフォルトではオフになっていますが、reuseItems プロパティをtrue に設定することで有効にできます。

アイテムがフリックされて画面外に出されると、そのアイテムは未使用アイテムの内部キャッシュである再利用プールに移動します。この際、その旨をアイテムに通知するために `ListView::pooled ` シグナルが発信されます。同様に、アイテムがプールから画面に戻された際には、`ListView::reused ` シグナルが発信されます。

アイテムが再利用されると、モデルから取得されたアイテムのプロパティはすべて更新されます。これにはindex やrow だけでなく、モデルのロールも含まれます。

アイテムにタイマーやアニメーションがある場合は、ListView::pooled シグナルを受信した際にそれらを一時停止することを検討してください。そうすることで、表示されていないアイテムに対してCPUリソースが消費されるのを防ぐことができます。同様に、アイテムに再利用できないリソースがある場合は、それらを解放することができます。

次の例は、回転する長方形をアニメーション化するデリゲートを示しています。プールされると、アニメーションは一時的に一時停止されます：

Component {
    id: listViewDelegate
    Rectangle {
        width: 100
        height: 50

        ListView.onPooled: rotationAnimation.pause()
        ListView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

デリゲートのサイズ変動とセクションラベル

デリゲートのサイズが変動すると、サイズ変更が発生したり、添付されたScrollBar がスキップされたりする可能性があります。これは、ListViewが割り当てられたアイテム（通常は表示されているアイテムのみ。残りは同様のサイズであると想定される）からコンテンツのサイズを推定するためであり、デリゲートのサイズが変動すると正確な推定が妨げられるためです。 この影響を軽減するには、cacheBuffer の値を大きく設定します。これにより、実質的にアイテム数が増加し、未割り当てアイテムのサイズ推定精度が向上しますが、その代償としてメモリ使用量が増加します。Sections を使用しても同様の効果が得られます。これは、セクション内の最初のアイテムにセクションラベルを添付し、その長さに合わせて伸ばすためです。

デリゲートへの状態の保存は避ける

ListView のデリゲートは必要に応じてインスタンス化され、表示範囲外になると破棄される可能性があります。これを確認するには、次の例を実行してください：

ListView {
    anchors.fill: parent
    model: 3
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)

        required property int index
        property bool channelActivated

        onClicked: channelActivated = checked
    }
}

項目がクリックされると、channelActivated はtrue に設定されます。しかし、デリゲートはreused され、破棄される可能性があるため、ビューが十分に遠くに移動すると、すべての状態が失われます。デリゲートが再び表示されるようになると、その状態は変更されていないデフォルトの状態（または、項目が再利用された場合は、以前の項目からの古い状態）に戻ります。

これを回避するには、状態をモデルに保存する必要があります：

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement {
            channelActivated: true
        }
        // ...
    }
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)
        checked: model.channelActivated

        required property int index
        required property var model

        onClicked: model.channelActivated = checked
    }
}

デリゲートの非表示

デリゲートの `visible ` プロパティを `false ` に設定すると、そのアイテムは非表示になりますが、ビュー内でそのアイテムが占めていたスペースは残ります。アイテムの `height ` を `0 ` に設定することも可能です（vertical の ListView の場合）：

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement { hidden: false }
        ListElement { hidden: false }
        ListElement { hidden: false }
        // ...
    }
    delegate: ItemDelegate {
        text: qsTr("Item %1").arg(index)
        visible: !model.hidden
        height: visible ? implicitHeight : 0

        required property int index
        required property var model

        onClicked: model.hidden = true
    }
}

「Avoid Storing State in Delegates 」セクションのアドバイスに従い、非表示の状態はモデルに保存される点に注意してください。

ただし、spacing が0以外の場合、デリゲート間に不均一な間隔が生じます。

より良い方法は、表示すべきでない項目がビューによって読み込まれないように、モデルをフィルタリングすることです。これはQSortFilterProxyModel を使用して実現できます。

もう一つの選択肢は、デリゲートを非表示にする代わりに、disable を適用することです。

関連項目： QML データモデル、GridView 、PathView 、およびQt Quick Examples - Views。

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

add : Transition

このプロパティは、ビューに追加されるアイテムに適用するトランジションを指定します。

たとえば、次のようなビューでは、そのような遷移が指定されています:

ListView {
    ...
    add: Transition {
        NumberAnimation { properties: "x,y"; from: 100; duration: 1000 }
    }
}

上記のビューにアイテムが追加されるたびに、そのアイテムは (100,100) の位置から、ビュー内の最終的な x、y 座標まで、1 秒かけてアニメーション表示されます。 このトランジションは、ビューに追加された新しいアイテムにのみ適用され、新しいアイテムの追加によって押し出された下位のアイテムには適用されません。押し出されたアイテムにアニメーションを適用するには、displaced またはaddDisplaced プロパティを設定してください。

ビュー遷移の使用方法に関する詳細や例については、ViewTransition のドキュメントを参照してください。

addDisplaced 、populate 、およびViewTransitionも参照してください 。

addDisplaced : Transition

このプロパティは、ビューへの他の項目の追加によって位置がずれてしまったビュー内の項目に適用される遷移を保持します。

たとえば、次のようなビューでは、そのような遷移が指定されています。

ListView {
    ...
    addDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

上記のビューにアイテムが追加されるたびに、新しいアイテムの下にあるすべてのアイテムが押し出され、ビュー内で下方向（水平方向の場合は横方向）に移動します。 この位置ずれが発生すると、指定どおり、ビュー内の新しい x、y 座標への項目の移動が、NumberAnimation によって 1 秒かけてアニメーション化されます。この遷移は、ビューに追加された新しい項目には適用されません。追加された項目をアニメーション化するには、add プロパティを設定してください。

アイテムが複数の種類の操作によって同時に変位された場合、addDisplaced、moveDisplaced 、またはremoveDisplaced のどの遷移が適用されるかは定義されていません。また、アイテムが追加、移動、削除のいずれの操作によって変位されたかによって異なる遷移を指定する必要がない場合は、代わりにdisplaced プロパティを設定することを検討してください。

ビュー遷移の使用方法に関する詳細や例については、ViewTransition のドキュメントを参照してください。

関連項目： displaced 、add 、populate 、およびViewTransition 。

cacheBuffer : int

このプロパティは、デリゲートがビューの表示領域外でも保持されるかどうかを決定します。

この値が 0 より大きい場合、ビューは指定されたバッファ内に収まる限り、できるだけ多くのデリゲートをインスタンス化して保持することができます。たとえば、縦方向のビューでデリゲートの高さが 20 ピクセルであり、cacheBuffer が 40 に設定されている場合、表示領域の上下に最大 2 つのデリゲートが作成・保持される可能性があります。 バッファリングされたデリゲートは非同期で作成されるため、複数のフレームにまたがって作成が行われ、フレームスキップの可能性が低減されます。描画パフォーマンスを向上させるため、表示領域外のデリゲートは描画されません。

このプロパティのデフォルト値はプラットフォームに依存しますが、通常は 0 より大きい値になります。負の値は無視されます。

cacheBuffer はピクセルバッファではない点に注意してください。これは、インスタンス化された追加のデリゲートを保持するだけです。

cacheBuffer は、displayMarginBeginning またはdisplayMarginEnd で指定された表示マージンの外側で動作します。

count : int [read-only]

このプロパティは、ListView のモデルに含まれるアイテムの数を反映します。これらは、表示されているか、あるいはデリゲートコンポーネントのItem としてインスタンス化されているかどうかにかかわらず、すべて含まれます。

currentIndex プロパティには現在の項目のインデックスが格納され、currentItem には現在の項目が格納されます。currentIndex を -1 に設定すると、ハイライトが解除され、currentItem が null に設定されます。

highlightFollowsCurrentItem がtrue の場合、これらのプロパティのいずれかを設定すると、ListView が滑らかにスクロールされ、現在の項目が表示されるようになります。

なお、現在の項目の位置は、ビュー内に表示されるまではおおよその位置に過ぎない場合があることに注意してください。

currentItem はあらゆるデリゲートに対応する必要があるため、その型はItem です。しかし、多くの場合、ListView は厳密に1種類のデリゲートとともに使用されます。その場合、currentItem をデリゲートの型にキャストすることで、ツールでの作業が容易になり、より効率的なコードが生成されます:

component Message : Item {
    required property string sender
    required property string text
}
ListView {
    id: messageView
    delegate: Message {}
    model: messageModel
}
Button {
    text: "Reply to %1".arg((messageView.currentItem) as Message).sender
}

currentSection : string [read-only]

このプロパティには、現在ビューの先頭にあるセクションが格納されます。

delegate : Component

デリゲートは、ビューによってインスタンス化される各項目を定義するテンプレートを提供します。インデックスは、index というアクセス可能なプロパティとして公開されます。また、データモデルのタイプに応じて、モデルのプロパティも利用可能です。

デリゲート内のオブジェクト数とバインディング数は、ビューのフリック操作のパフォーマンスに直接影響します。可能な限り、デリゲートの通常の表示には必要のない機能は、Loader 内に配置し、必要に応じて追加のコンポーネントを読み込めるようにしてください。

ListView は、デリゲート内のルート項目のサイズに基づいて項目のレイアウトを行います。

項目のサブピクセル単位での配置を避けるため、デリゲートのサイズを整数にすることを推奨します。

デリゲートインスタンスのデフォルトのstacking order は、1 です。

「Stacking Order in ListView」も参照してください 。

delegateModelAccess : enumeration [since 6.10]

このプロパティは、デリゲートがモデルにアクセスする方法を決定します。

デフォルトはDelegateModel.Qt5ReadWrite です。

このプロパティは Qt 6.10 で導入されました。

「 Qt Quick におけるモデルとビュー」の「モデルデータの変更」も参照してください 。

displaced : Transition

このプロパティには、ビューに影響を与えるモデル操作によって位置が変更されたアイテムに適用される汎用遷移が格納されます。

これは、追加、移動、削除操作によって位置が変更されたすべてのアイテムに適用される汎用遷移を指定するための便利な機能であり、個々のaddDisplaced 、moveDisplaced 、removeDisplaced プロパティを指定する必要がありません。例えば、以下は位置変更遷移を指定したビューの例です：

ListView {
    ...
    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

上記のビュー内でアイテムが追加、移動、または削除されると、その下にあるアイテムは押し出され、ビュー内で下方向（水平配置の場合は横方向）に移動します。この押し出しが発生すると、指定どおり、アイテムがビュー内の新しい x、y 座標へ移動する過程が、NumberAnimation によって 1 秒かけてアニメーション化されます。

ビューがこの汎用的な「displaced」遷移に加え、特定のaddDisplaced 、moveDisplaced 、またはremoveDisplaced 遷移も指定している場合、関連する操作が発生した際には、より具体的な遷移が無効化されていない限り（enabled をfalseに設定していない限り）、汎用的な「displaced」遷移の代わりにその具体的な遷移が使用されます。もし無効化されている場合は、代わりに汎用的な「displaced」遷移が適用されます。

ビュー遷移の使用方法に関する詳細や例については、『ViewTransition 』のドキュメントを参照してください。

関連項目：addDisplaced 、moveDisplaced 、removeDisplaced 、およびViewTransitionも参照してください 。

このプロパティを設定すると、デリゲートをビューのジオメトリの外側に表示できるようになります。

この値が 0 以外の場合、ビューはビューの開始前または終了後に追加のデリゲートを作成します。ビューは、指定されたピクセルサイズに収まる限り、可能な限り多くのデリゲートを作成します。

たとえば、縦方向のビューで、デリゲートの高さが 20 ピクセル、displayMarginBeginning およびdisplayMarginEnd が両方とも 40 に設定されている場合、上部に 2 つ、下部に 2 つのデリゲートが作成され、表示されます。

デフォルト値は 0 です。

このプロパティは、特定の UI 構成を可能にするためのものであり、パフォーマンスの最適化を目的としたものではありません。パフォーマンス上の理由から、ビューのジオメトリの外側にデリゲートを作成したい場合は、代わりにcacheBuffer プロパティを使用することをお勧めします。

これらのプロパティは QtQuick 2.3 で導入されました。

effectiveLayoutDirection : enumeration [read-only]

このプロパティは、水平方向のリストの実際のレイアウト方向を指定します。

ロケールレイアウト用に添付プロパティ `LayoutMirroring::enabled ` を使用すると、水平リストの視覚的なレイアウト方向が反転します。ただし、プロパティ `layoutDirection ` の値は変更されません。

「 ListView::layoutDirection 」および「LayoutMirroring 」も参照してください 。

footer : Component

このプロパティには、フッターとして使用するコンポーネントが格納されます。

各ビューに対して、フッターコンポーネントのインスタンスが作成されます。フッターは、ビューの最後、すべての項目の後に配置されます。フッターのデフォルトのstacking order は1 です。

「 header 」、「footerItem 」、および「Stacking Order in ListView 」も参照してください 。

footerItem : Item [read-only]

ここには、footer コンポーネントから作成されたフッターアイテムが格納されます。

各ビューに対して、フッターコンポーネントのインスタンスが1つずつ作成されます。フッターは、ビューの末尾、他のすべての項目の後に配置されます。フッターのデフォルトのstacking order は1 です。

「 footer 」、「headerItem 」、および「Stacking Order in ListView 」も参照してください 。

footerPositioning : enumeration [since Qt 5.4]

このプロパティは、footer item の位置を決定します。

このプロパティは Qt 5.4 で導入されました。

header : Component

このプロパティには、ヘッダーとして使用するコンポーネントが格納されます。

各ビューに対して、ヘッダーコンポーネントのインスタンスが作成されます。ヘッダーは、ビューの先頭、つまりどの項目よりも前に配置されます。ヘッダーのデフォルトのstacking order は1 です。

「 footer 」、「headerItem 」、および「Stacking Order in ListView 」も参照してください 。

headerItem : Item [read-only]

ここには、header コンポーネントから作成されたヘッダー項目が格納されます。

各ビューに対して、ヘッダーコンポーネントのインスタンスが1つ作成されます。ヘッダーは、ビューの先頭、他のアイテムよりも前に配置されます。ヘッダーのデフォルトのstacking order は1 です。

「 header 」、「footerItem 」、および「Stacking Order in ListView 」も参照してください 。

headerPositioning : enumeration [since Qt 5.4]

このプロパティは、header item の配置を決定します。

このプロパティは Qt 5.4 で導入されました。

highlight : Component

このプロパティには、ハイライトとして使用するコンポーネントが格納されます。

各リストに対して、ハイライトコンポーネントのインスタンスが作成されます。結果として生成されるコンポーネントインスタンスのジオメトリは、highlightFollowsCurrentItem プロパティがfalseでない限り、現在の項目に追従するようにリストによって管理されます。ハイライト項目のデフォルトのstacking order は、0 です。

「 highlightItem 」、「highlightFollowsCurrentItem 」、「ListView Highlight Example」、および「Stacking Order in ListView 」も参照してください 。

highlightFollowsCurrentItem : bool

このプロパティは、ハイライトがビューによって管理されるかどうかを示します。

このプロパティが true の場合（デフォルト値）、ハイライトは現在のアイテムを追従するように滑らかに移動します。そうでない場合、ハイライトはビューによって移動されず、移動処理はハイライト側で実装する必要があります。

以下は、SpringAnimation 項目によって動きが定義されたハイライトの例です：

Component {
    id: highlight
    Rectangle {
        width: 180; height: 40
        color: "lightsteelblue"; radius: 5
        y: list.currentItem.y
        Behavior on y {
            SpringAnimation {
                spring: 3
                damping: 0.2
            }
        }
    }
}

ListView {
    id: list
    width: 180; height: 200
    model: ContactModel {}
    delegate: Text { text: name }

    highlight: highlight
    highlightFollowsCurrentItem: false
    focus: true
}

なお、ハイライトのアニメーションはビューのスクロール方法にも影響を与えます。これは、ハイライトを所定のハイライト範囲（または表示可能なビューポート）内に維持するために、ビューが移動するためです。

「 highlight 」および「highlightMoveVelocity 」も参照してください 。

highlightItem : Item [read-only]

ここには、highlight コンポーネントから作成されたハイライト項目が格納されます。

highlightFollowsCurrentItem がfalseに設定されていない限り、highlightItem はビューによって管理されます。ハイライト項目のデフォルトのstacking order は0 です。

「 highlight 」、「highlightFollowsCurrentItem 」、および「Stacking Order in ListView 」も参照してください 。

これらのプロパティは、ハイライトデリゲートの移動およびサイズ変更アニメーションの速度を制御します。

highlightFollowsCurrentItem これらのプロパティが有効になるには、trueに設定する必要があります。

velocity プロパティのデフォルト値は 400 ピクセル/秒です。duration プロパティのデフォルト値は -1 です。つまり、ハイライトは設定された速度で移動するのに必要なだけの時間がかかります。

これらのプロパティは、SmoothedAnimation と同じ特性を持っています。velocityとdurationの両方が設定されている場合、アニメーションでは、より短い期間となる方が優先されます。

moveのvelocityおよびdurationプロパティは、インデックスの変更による移動を制御するために使用されます。例えば、incrementCurrentIndex()が呼び出された場合などです。ユーザーがListView をフリックした場合は、そのフリックによる速度が代わりに移動の制御に使用されます。

一方のプロパティのみを設定するには、もう一方を `-1` に設定します。たとえば、速度ではなく持続時間のみをアニメーション化したい場合は、次のコードを使用します：

highlightMoveDuration: 1000
highlightMoveVelocity: -1

「highlightFollowsCurrentItem」も参照してください 。

これらのプロパティは、ビュー内での（現在の項目に対する）ハイライトの推奨範囲を定義します。preferredHighlightBegin の値は、preferredHighlightEnd の値よりも小さくなければなりません。

これらのプロパティは、リストがスクロールされた際の現在の項目の位置に影響を与えます。たとえば、ビューがスクロールされた際に現在選択されている項目をリストの中央に保持したい場合は、preferredHighlightBegin およびpreferredHighlightEnd の値を、中央の項目が位置する場所の上端および下端の座標に設定します。currentItem がプログラムによって変更された場合、リストは自動的にスクロールされ、現在の項目がビューの中央に配置されます。さらに、この動作は、ハイライトの有無にかかわらず発生します。

highlightRangeMode の有効な値は以下の通りです：

keyNavigationEnabled : bool

このプロパティは、リストのキーナビゲーションが有効かどうかを指定します。

このプロパティの値が `true` の場合、ユーザーはキーボードを使用してビュー内を移動できます。これは、マウスやキーボードによる操作を選択的に有効または無効にする必要があるアプリケーションで役立ちます。

デフォルトでは、既存のアプリケーションとの動作互換性を確保するため、このプロパティの値はinteractive にバインドされています。明示的に設定された場合、interactiveプロパティへのバインドは解除されます。

「interactive」も参照してください 。

keyNavigationWraps : bool

このプロパティは、リストでキーによるナビゲーションが行き詰まった際に折り返し処理が行われるかどうかを指定します。

これが true の場合、現在の項目の選択位置をリストの末尾より先へ移動させるはずのキーナビゲーションは、代わりにリストの先頭へ移動するように動作し、その逆も同様です。

デフォルトでは、キーによるナビゲーションはループしません。

layoutDirection : enumeration

このプロパティは、横向きのリストのレイアウト方向を指定します。

取り得る値：

orientation が Qt.Vertical の場合、このプロパティを設定しても効果はありません。

関連項目： ListView::effectiveLayoutDirection およびListView::verticalLayoutDirection 。

model : model

このプロパティには、リストにデータを供給するモデルが格納されます。

このモデルは、ビュー内の項目を作成するために使用されるデータセットを提供します。モデルは、ListModel やObjectModel を使用してQML内で直接作成することも、C++のモデルクラスによって提供されることもできます。C++のモデルクラスを使用する場合、そのクラスはQAbstractItemModel のサブクラスであるか、単純なリストでなければなりません。

「データモデル」も参照してください 。

move : Transition

このプロパティは、ビューのmodel で実行される移動操作によって移動されるビュー内のアイテムに適用される遷移を保持します。

たとえば、次のようなビューでは、そのような遷移が指定されています。

ListView {
    ...
    move: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

model が特定のインデックスセットを移動させる移動操作を実行するたびに、ビュー内の対応するアイテムは、1秒かけてビュー内の新しい位置へとアニメーションで移動します。 この遷移は、モデル内の移動操作の対象となっているアイテムにのみ適用され、移動操作によって位置がずれたその下のアイテムには適用されません。位置がずれたアイテムにアニメーションを適用するには、displaced またはmoveDisplaced プロパティを設定してください。

ビュートランジションの使用方法に関する詳細や例については、『ViewTransition 』のドキュメントを参照してください。

「 moveDisplaced 」および「ViewTransition 」も参照してください 。

moveDisplaced : Transition

このプロパティは、ビューのmodel 内で移動操作によって位置が変更されたアイテムに適用される遷移を保持します。

たとえば、次のようなビューでは、そのような遷移が指定されています。

ListView {
    ...
    moveDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

model が特定のインデックス範囲を移動させる操作を実行するたびに、その移動操作の開始インデックスと終了インデックスの間に位置するアイテムがずらされ、ビュー内で上方向または下方向（水平方向の場合は横方向）に移動します。 この変位が発生すると、指定どおり、アイテムがビュー内の新しい x,y 位置へ移動する様子が、NumberAnimation によって 1 秒間にわたってアニメーション化されます。この遷移効果は、移動操作の実際の対象となるアイテムには適用されません。移動されたアイテムをアニメーション化するには、move プロパティを設定してください。

1つのアイテムが同時に複数の種類の操作によって移動された場合、addDisplaced 、moveDisplaced、またはremoveDisplaced のどのトランジションが適用されるかは定義されていません。また、アイテムがadd、move、removeのいずれの操作によって移動されたかによって異なるトランジションを指定する必要がない場合は、代わりにdisplaced プロパティを設定することを検討してください。

ビュートランジションの使用方法に関する詳細や例については、『ViewTransition 』のドキュメントを参照してください。

「 displaced 」、「move 」、および「ViewTransition 」も参照してください 。

orientation : enumeration

このプロパティは、リストの向きを保持します。

取り得る値：

定数	説明
ListView.Horizontal	項目は水平方向に配置されます
ListView.Vertical	(既定値) 項目が縦方向に配置される

関連項目： Flickable Direction 。

populate : Transition

このプロパティは、ビュー用に最初に作成されるアイテムに適用される遷移を保持します。

これは、以下の場合に作成されるすべてのアイテムに適用されます。

• ビューが最初に作成されたとき
• ビューのmodel が変更され、表示されるデリゲートが完全に置き換えられる場合
• ビューのmodel がreset であり、かつモデルがQAbstractItemModel のサブクラスである場合

たとえば、次のようなビューでは、このような遷移が指定されています：

ListView {
    ...
    populate: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

ビューが初期化されると、ビューはビューに必要なすべてのアイテムを作成し、1 秒かけてそれらをビュー内の正しい位置にアニメーションで配置します。

しかし、後でビューをスクロールしても、デリゲートが可視になった時点でインスタンス化されるにもかかわらず、`populate`トランジションは実行されません。モデルが変更され、新しいデリゲートが可視になった場合には、`add `トランジションが実行されます。したがって、デリゲート内のプロパティを初期化するために`populate `トランジションに依存すべきではありません。これは、すべてのデリゲートに適用されるわけではないからです。 アニメーションでプロパティの `to ` 値を設定する場合、そのプロパティは初期状態で `to ` 値を持つようにし、アニメーションの対象となる場合は、アニメーションによって `from ` 値が設定されるようにする必要があります。

ListView {
    ...
    delegate: Rectangle {
        opacity: 1 // not necessary because it's the default
    }
    populate: Transition {
        NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 1000 }
    }
}

ビュートランジションの使用方法に関する詳細や例については、ViewTransition のドキュメントを参照してください。

「 add 」および「ViewTransition 」も参照してください 。

remove : Transition

このプロパティは、ビューから削除されるアイテムに適用される遷移を指定します。

たとえば、次のようなビューでは、そのような遷移が指定されています。

ListView {
    ...
    remove: Transition {
        ParallelAnimation {
            NumberAnimation { property: "opacity"; to: 0; duration: 1000 }
            NumberAnimation { properties: "x,y"; to: 100; duration: 1000 }
        }
    }
}

上記のビューからアイテムが削除されるたびに、そのアイテムは1秒かけて位置(100,100)へ移動するアニメーションが適用され、同時に不透明度も0に変化します。 このトランジションは、ビューから削除されたアイテムにのみ適用され、その削除によって位置がずれた下位のアイテムには適用されません。位置がずれたアイテムにアニメーションを適用するには、displaced またはremoveDisplaced プロパティを設定してください。

なお、トランジションが適用される時点では、そのアイテムはすでにモデルから削除されているため、削除されたインデックスのモデルデータへの参照はすべて無効になります。

さらに、デリゲート項目に対してdelayRemove アタッチドプロパティが設定されている場合、delayRemove が再びfalseになるまで、removeトランジションは適用されません。

ビュー遷移の使用方法の詳細および例については、「ViewTransition 」のドキュメントを参照してください。

「 removeDisplaced 」および「ViewTransition 」も参照してください 。

removeDisplaced : Transition

このプロパティには、ビュー内の他のアイテムが削除されたことで位置がずれてしまったアイテムに適用されるトランジションが格納されます。

たとえば、次のようなビューでは、そのような遷移が指定されています。

ListView {
    ...
    removeDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

上記のビューからアイテムが削除されるたびに、その下にあるすべてのアイテムが位置をずらされ、ビュー内で上方向（または横向きの場合は横方向）に移動します。 この位置ずれが発生すると、指定どおり、ビュー内の新しい x、y 位置への項目の移動は、NumberAnimation によって 1 秒かけてアニメーション化されます。このトランジションは、実際にビューから削除された項目には適用されません。削除された項目をアニメーション化するには、remove プロパティを設定してください。

アイテムが同時に複数の種類の操作によって変位された場合、addDisplaced 、moveDisplaced 、removeDisplacedのいずれの遷移が適用されるかは定義されていません。また、アイテムが追加、移動、削除のいずれの操作によって変位されたかによって異なる遷移を指定する必要がない場合は、代わりにdisplaced プロパティを設定することを検討してください。

ビュートランジションの使用方法に関する詳細や例については、ViewTransition のドキュメントを参照してください。

「 displaced 」、「remove 」、および「ViewTransition 」も参照してください 。

reuseItems : bool

このプロパティを使用すると、delegate からインスタンス化されたアイテムを再利用できます。false に設定すると、現在プールされているアイテムはすべて破棄されます。

このプロパティのデフォルト値は `false ` です。

「 Reusing items 」、「pooled()」、および「reused()」も参照してください 。

section group

これらのプロパティは、評価される式およびセクションラベルの表示形式を決定します。

section.property には、各セクションの基礎となるプロパティの名前が格納されます。

section.criteria には、section.property に基づいて各セクションを形成するための基準が格納されます。この値は、以下のいずれかになります：

セクションの境界を決定する際には、大文字と小文字を区別しない比較が行われます。

section.delegate 各セクションのデリゲートコンポーネントを保持します。セクションデリゲートインスタンスのデフォルトのstacking order は、2 です。その中に「section」という名前のrequired プロパティを宣言すると、そのプロパティにはセクションのタイトルが含まれます。

section.labelPositioning は、現在および／または次のセクションのラベルがビューの先頭／末尾に固定されるかどうか、およびラベルがインラインで表示されるかどうかを決定します。この値は、以下の組み合わせのいずれかになります：

リスト内の各アイテムには、「ListView.section 」、「ListView.previousSection 」、「ListView.nextSection 」という名前のプロパティが関連付けられています。

たとえば、以下は、動物のリストをセクションごとに分けて表示する「ListView 」です。「ListView 」内の各項目は、モデル項目の「size」プロパティに応じて、異なるセクションに配置されます。「sectionHeading 」デリゲートコンポーネントは、各セクションの開始位置を示す水色のバーを提供します。

    // The delegate for each section header
    Component {
        id: sectionHeading
        Rectangle {
            width: ListView.view.width
            height: childrenRect.height
            color: "lightsteelblue"

            required property string section

            Text {
                text: parent.section
                font.bold: true
                font.pixelSize: 20
            }
        }
    }

    ListView {
        id: view
        anchors.top: parent.top
        anchors.bottom: buttonBar.top
        width: parent.width
        model: animalsModel
        delegate: Text {
            required property string name

            text: name
            font.pixelSize: 18
        }

        section.property: "size"
        section.criteria: ViewSection.FullString
        section.delegate: sectionHeading
    }

「ListView の例」および「Stacking Order in ListView 」も参照してください 。

snapMode : enumeration

このプロパティは、ドラッグやフリックの後にビューのスクロールがどのように落ち着くかを決定します。設定可能な値は次のとおりです。

snapMode currentIndex には影響しません。リストが移動する際に を更新するには、 を に設定してください。currentIndex highlightRangeMode ListView.StrictlyEnforceRange

「highlightRangeMode」も参照してください 。

spacing : real

このプロパティは、項目間の間隔を指定します。

デフォルト値は 0 です。

verticalLayoutDirection : enumeration

このプロパティは、縦方向のリストのレイアウト方向を指定します。

取り得る値：

orientation が Qt.Horizontal の場合、このプロパティを設定しても効果はありません。

関連項目： ListView::layoutDirection 。

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

ListView.delayRemove : bool [attached]

このアタッチメントプロパティは、デリゲートが破棄可能かどうかを示すものです。これはデリゲートの各インスタンスにアタッチされます。デフォルト値は false です。

アニメーションが完了するまで、項目の破棄を遅らせる必要がある場合があります。以下の例に示すデリゲートは、項目がリストから削除される前に、アニメーションが確実に完了するようにしています。

Component {
    id: delegate
    Item {
        SequentialAnimation {
            id: removeAnimation
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: true }
            NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: false }
        }
        ListView.onRemove: removeAnimation.start()
    }
}

remove の遷移が指定されている場合、delayRemoveがfalse に返されるまで、その遷移は適用されません。

ListView.isCurrentItem : bool [read-only attached]

この添付プロパティは、このデリゲートが現在のアイテムである場合に true を返し、そうでない場合は false を返します。

このプロパティは、デリゲートの各インスタンスに紐付けられています。

このプロパティは、現在の項目の外観を調整するために使用できます。例えば、次のような場合です。

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

ListView.nextSection : string [read-only attached]

この添付プロパティには、次の要素のセクションが格納されます。

これは、デリゲートの各インスタンスに紐付けられています。

このセクションは、section プロパティを使用して評価されます。

ListView.previousSection : string [read-only attached]

この添付プロパティには、前の要素のセクションが格納されます。

これは、デリゲートの各インスタンスに紐付けられています。

このセクションは、section プロパティを使用して評価されます。

ListView.section : string [read-only attached]

この添付プロパティには、この要素のセクションが格納されます。

これは、デリゲートの各インスタンスに紐付けられています。

このセクションは、section プロパティを使用して評価されます。

ListView.view : ListView [read-only attached]

この添付プロパティには、このデリゲートインスタンスを管理するビューが保持されています。

これは、各デリゲートインスタンスに加え、ヘッダー、フッター、セクション、およびハイライトの各デリゲートにもアタッチされています。

アタッチされたシグナルのドキュメント

[attached] add()

この添付シグナルは、アイテムがビューに追加された直後に発生します。

addトランジションが指定されている場合、このシグナルが処理された直後にそれが適用されます。

[attached] pooled()

このシグナルは、アイテムが再利用プールに追加された後に発火します。これを使用して、アイテム内で実行中のタイマーやアニメーションを一時停止したり、再利用できないリソースを解放したりすることができます。

このシグナルは、reuseItems プロパティがtrue に設定されている場合にのみ発火します。

関連項目： Reusing items 、reuseItems 、およびreused()。

[attached] remove()

この添付のシグナルは、アイテムがビューから削除される直前に発火します。

削除トランジションが指定されている場合、delayRemove がfalseである限り、このシグナルが処理された後にそのトランジションが適用されます。

[attached] reused()

このシグナルは、アイテムが再利用された後に発火します。この時点で、アイテムはプールから取り出されてコンテンツビュー内に配置され、index やrow などのモデルプロパティが更新されています。

モデルによって提供されていないその他のプロパティは、アイテムが再利用されても変更されません。デリゲート内に状態を保存することは避けるべきですが、やむを得ず保存する場合は、このシグナルを受信した際にその状態を手動でリセットしてください。

このシグナルは、アイテムが最初に作成されたときではなく、アイテムが再利用されたときに発火します。

このシグナルは、reuseItems プロパティがtrue である場合にのみ発火します。

Reusing items 、reuseItems 、およびpooled()も参照してください 。

メソッドのドキュメント

void decrementCurrentIndex()

現在のインデックスを1減らします。keyNavigationWraps がtrueで、かつ現在インデックスが先頭にある場合、インデックスはループバックします。count が0の場合、このメソッドは効果を持ちません。

注：メソッドは、コンポーネントの処理が完了した後にのみ呼び出す必要があります。

void forceLayout()

モデルの変更に対する反応は、通常、1フレームにつき1回のみ行われるようバッチ処理されます。つまり、スクリプトブロック内では、基盤となるモデルが変更されているにもかかわらず、ListView がまだその変更を反映していない場合があります。

このメソッドは、ListView に対し、モデルにおける未処理の変更に直ちに対応するよう強制します。

注：このメソッドは、コンポーネントの処理が完了した後にのみ呼び出す必要があります。

void incrementCurrentIndex()

現在のインデックスを1増やします。keyNavigationWraps がtrueで、かつ現在インデックスが末尾にある場合、インデックスはループバックします。count が0の場合、このメソッドは効果を持ちません。

注：メソッドは、コンポーネントの処理が完了した後にのみ呼び出す必要があります。

int indexAt(real x, real y)

コンテンツ座標における点x 、y を含む、表示中のアイテムのインデックスを返します。指定された点にアイテムが存在しない場合、またはそのアイテムが表示されていない場合は、-1が返されます。

アイテムが表示領域外にある場合、スクロールによってその位置が画面内に表示されるようになった際にアイテムが存在するかどうかに関わらず、-1 が返されます。

注：メソッドは、コンポーネントの処理が完了した後にのみ呼び出す必要があります。

Item itemAt(real x, real y)

コンテンツ座標において、点x 、y を含む表示中のアイテムを返します。指定された点にアイテムが存在しない場合、またはそのアイテムが表示されていない場合は、nullが返されます。

アイテムが表示領域外にある場合、スクロールによってその位置が画面内に表示されるようになるかどうかに関係なく、nullが返されます。

注：メソッドは、コンポーネントの処理が完了してから呼び出す必要があります。

Item itemAtIndex(int index)

index に対応するアイテムを返します。そのインデックスに対応するアイテムが存在しない場合（たとえば、まだ作成されていない、または画面外へスクロールされてキャッシュから削除された場合など）、nullが返されます。

注：このメソッドは、コンポーネントの処理が完了した後にのみ呼び出す必要があります。また、ビューがそのアイテムを解放した場合、呼び出しスコープから制御が外れるやいなや返り値が null になる可能性があるため、返り値を保存してはいけません。

ヘッダーやフッターの位置を考慮して、ビューを先頭または末尾に配置します。

contentX やcontentY を使用してビューを特定のインデックスに配置することは推奨されません。リストの先頭から項目を削除しても、他のすべての項目の位置が再配置されるわけではないため、また、デリゲートのサイズによってビューの実際の開始位置が変動する可能性があるため、この方法は信頼性が低いからです。

注：メソッドは、Componentが完了した後にのみ呼び出す必要があります。起動時にビューを配置するには、Component.onCompleted からこのメソッドを呼び出す必要があります。たとえば、起動時にビューを末尾に配置するには：

Component.onCompleted: positionViewAtEnd()

void positionViewAtIndex(int index, PositionMode mode)

index がmode で指定された位置に来るようにビューを配置します：

index にビューを配置することで、ビューの先頭または末尾に空白が表示される場合、ビューは境界に配置されます。

contentX やcontentY を使用してビューを特定のインデックスに配置することは推奨されません。これは、リストの先頭から項目を削除しても他のすべての項目の位置が再配置されるわけではないこと、またビューの実際の開始位置がデリゲートのサイズによって変動する可能性があるため、信頼性が低いからです。項目をビュー内に表示させる正しい方法は、positionViewAtIndex を使用することです。

注：メソッドは、Component が完了した後にのみ呼び出す必要があります。起動時にビューを配置するには、Component.onCompleted からこのメソッドを呼び出す必要があります。たとえば、ビューを末尾に配置するには：

Component.onCompleted: positionViewAtIndex(count - 1, ListView.Beginning)