Back to Qt.io
Contact Us Blog Download Qt

ScrollBar QML Type

縦または横のインタラクティブスクロールバー。詳細...

Import Statement: import QtQuick.Controls
Inherits:

Control

プロパティ

付属物件

方法

詳細説明

ScrollBar は、特定の位置にスクロールするために使用できるインタラクティブなバーです。スクロールバーは、vertical またはhorizontal のどちらかであり、ListView やGridView など、任意のFlickable に取り付けることができます。 また、ScrollView と一緒に使用することもできます。

Flickable {
    // ...
    ScrollBar.vertical: ScrollBar { }
}

ScrollBar を Flickable に取り付ける

ScrollBar をvertically またはhorizontally の Flickable にアタッチすると、そのジオメトリと以下のプロパティが自動的に設定され、適宜更新されます：

アタッチされた ScrollBar は、ターゲットの Flickable に再度ペアレント化されます。垂直方向にアタッチされた ScrollBar は、Flickable の高さに合わせてサイズが変更され、layout direction に基づいて Flickable の両側に配置されます。水平方向にアタッチされた ScrollBar は、Flickable の幅に合わせてサイズが変更され、下側に配置されます。アタッチされた ScrollBar に別の親を指定することで、自動ジオメトリ管理を無効にできます。これは、ScrollBar をクリッピング Flickable の外側に配置する場合などに便利です。これは、次の例で示されています：

Flickable {
    id: flickable
    clip: true
    // ...
    ScrollBar.vertical: ScrollBar {
        parent: flickable.parent
        anchors.top: flickable.top
        anchors.left: flickable.right
        anchors.bottom: flickable.bottom
    }
}

ScrollBar は、アタッチされている Flickable のキーイベントをフィルタリングしないことに注意してください。次の例は、上下キーによるスクロールを実装する方法を示しています：

Flickable {
    focus: true

    Keys.onUpPressed: scrollBar.decrease()
    Keys.onDownPressed: scrollBar.increase()

    ScrollBar.vertical: ScrollBar { id: scrollBar }
}

水平スクロールバーと垂直スクロールバーのアクティブ状態のバインド

デフォルトでは、水平スクロールバーと垂直スクロールバーは、active の状態を共有しません。どちらかの方向にスクロールしている間、両方のバーを表示し続けるには、次の例で示すように、アクティブな状態の間で双方向のバインドを確立します：

Flickable {
    anchors.fill: parent

    contentWidth: parent.width * 2
    contentHeight: parent.height * 2

    ScrollBar.horizontal: ScrollBar { id: hbar; active: vbar.active }
    ScrollBar.vertical: ScrollBar { id: vbar; active: hbar.active }
}

アタッチされていないスクロールバー

アタッチされたプロパティ API を使用せずに ScrollBar のインスタンスを作成することもできます。これは、アタッチされたスクロールバーの動作が十分でない場合や、Flickable を使用していない場合に便利です。次の例では、Flickable を使用せずに、水平スクロールバーと垂直スクロールバーを使用してテキストをスクロールしています：

Rectangle {
    id: frame
    clip: true
    width: 160
    height: 160
    border.color: "black"
    anchors.centerIn: parent

    Text {
        id: content
        text: "ABC"
        font.pixelSize: 160
        x: -hbar.position * width
        y: -vbar.position * height
    }

    ScrollBar {
        id: vbar
        hoverEnabled: true
        active: hovered || pressed
        orientation: Qt.Vertical
        size: frame.height / content.height
        anchors.top: parent.top
        anchors.right: parent.right
        anchors.bottom: parent.bottom
    }

    ScrollBar {
        id: hbar
        hoverEnabled: true
        active: hovered || pressed
        orientation: Qt.Horizontal
        size: frame.width / content.width
        anchors.left: parent.left
        anchors.right: parent.right
        anchors.bottom: parent.bottom
    }
}

付属していないスクロールバーを使用する場合は、以下を手動で行う必要があります：

  • スクロールバーをレイアウトする（例えば、x とy またはanchors プロパティで）。
  • size およびposition プロパティを設定して、スクロールされたアイテムに対するスクロールバーのサイズと位置を決定します。
  • active プロパティを設定して、スクロールバーがいつ表示されるかを決めます。

ScrollIndicator 、ScrollView 、ScrollBar のカスタマイズ、およびインジケータ・コントロールも参照してください 。

プロパティの説明

active : bool

このプロパティは、スクロールバーがアクティブであるかどうか、つまり、pressed またはアタッチされている Flickable がmoving であるかどうかを保持します。

どちらの方向にもスクロールしながらboth horizontal and vertical bars visible を維持することが可能です。

このプロパティは、スクロールバーがattached to a flickable のときに自動的に設定されます。


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

このプロパティは、スクロールバーが水平かどうかを保持します。

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

orientationも参照してください 。


interactive : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

このプロパティは、スクロールバーがインタラクティブかどうかを保持します。デフォルト値はtrue です。

非インタラクティブスクロールバーは、視覚的にも動作的にもScrollIndicator に似ています。 このプロパティは、インタラクティブスクロールバーと非インタラクティブスクロールバーをそれぞれ持つ、典型的なマウス指向とタッチ指向の UI を切り替えるのに便利です。

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


minimumSize : real [since QtQuick.Controls 2.4 (Qt 5.11)]

このプロパティは、スクロールバーの最小サイズを保持し、0.0 - 1.0 にスケーリングされます。

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

size,visualSize,visualPositionも参照してください 。


orientation : enumeration

このプロパティは、スクロールバーの向きを保持します。

可能な値

定数説明
Qt.Horizontal水平
Qt.Vertical垂直（デフォルト）

このプロパティは、スクロールバーがattached to a flickable であるときに自動的に設定されます。

horizontal およびverticalも参照のこと 。


policy : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]

このプロパティは、スクロールバーのポリシーを保持します。デフォルトのポリシーはScrollBar.AsNeeded です。

可能な値：

定数説明
ScrollBar.AsNeededスクロールバーは、コンテンツが大きすぎて収まらない場合にのみ表示されます。
ScrollBar.AlwaysOffスクロールバーは表示されません。
ScrollBar.AlwaysOnスクロールバーは常に表示される。

以下の例では、垂直スクロールバーは常に表示されます：

Flickable {
    contentHeight: 2000
    ScrollBar.vertical: ScrollBar {
        policy: ScrollBar.AlwaysOn
    }
}

スタイルは、一時的なスクロールバーを実装するために、このプロパティをactive プロパティと組み合わせて使用することができます。トランジェント・スクロールバーは、最後のインタラクション・イベント（ホバーまたはプレス）の直後に非表示になります。これは通常、スクロールバーの不透明度をアニメーション化することによって行われます。この動作をオーバーライドするには、ビューと比較したコンテンツのサイズに応じて、ポリシーをScrollBar.AlwaysOn またはScrollBar.AlwaysOff に設定します。例えば、垂直のListView の場合：

policy: listView.contentHeight > listView.height ? ScrollBar.AlwaysOn : ScrollBar.AlwaysOff

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


position : real

このプロパティはスクロールバーの位置を保持し、0.0 - 1.0 にスケーリングされます。

スクロールバーの最大有効位置は(1.0 - size) です。これは、スクロールバーを端に移動すると、ドキュメントの端が接続された Flickable の可視領域の下端に来るような、最も使用されるケースで正しい動作を提供します。

このプロパティは、スクロールバーがattached to a flickable のときに自動的に設定されます。

Flickable::visibleArea およびvisualPositionも参照してください 。


pressed : bool

このプロパティは、スクロールバーが押されているかどうかを保持します。


size : real

このプロパティは、スクロールバーのサイズを保持し、0.0 - 1.0 にスケーリングされます。

このプロパティは、スクロールバーがattached to a flickable のときに自動的に設定されます。

Flickable::visibleArea 、minimumSize 、およびvisualSizeも参照してください 。


snapMode : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]

このプロパティはスナップ・モードを保持する。

可能な値：

定数説明
ScrollBar.NoSnapスクロールバーはスナップしない（デフォルト）。
ScrollBar.SnapAlwaysスクロールバーはドラッグ中にスナップする。
ScrollBar.SnapOnReleaseスクロールバーはドラッグされている間はスナップせず、リリースされた後にのみスナップする。

次の表では、さまざまなモードがアニメーションで説明されています。動きとstepSize (0.25) は各アニメーションで同じです。
値例
ScrollBar.NoSnap

ScrollBar.SnapAlways

ScrollBar.SnapOnRelease

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

stepSizeも参照してください 。


stepSize : real

このプロパティは、ステップサイズを保持します。デフォルト値は0.0 です。

snapMode 、increase()、decrease() も参照して ください。


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

このプロパティは、スクロールバーが垂直かどうかを保持します。

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

orientationも参照してください 。


visualPosition : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

このプロパティは、スクロールバーの有効な視覚的位置を保持します。minimum size によって制限される場合があります。

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

position およびminimumSizeも参照してください 。


visualSize : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

このプロパティは、minimum size によって制限される可能性のある、スクロールバーの有効な視覚的サイズを保持します。

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

size およびminimumSizeも参照してください 。


Attached Property ドキュメント

ScrollBar.horizontal : ScrollBar

このプロパティは、水平スクロールバーをFlickable にアタッチします。

Flickable {
    contentWidth: 2000
    ScrollBar.horizontal: ScrollBar { }
}

Attaching ScrollBar to a Flickableも参照して ください。


ScrollBar.vertical : ScrollBar

このプロパティは、Flickable に垂直スクロールバーをアタッチします。

Flickable {
    contentHeight: 2000
    ScrollBar.vertical: ScrollBar { }
}

Attaching ScrollBar to a Flickableも参照して ください。


メソッド ドキュメント

void decrease()

stepSize またはstepSize が0.0 の場合は0.1 だけ位置を下げます。

stepSizeも参照 。


void increase()

stepSize またはstepSize が0.0 の場合は0.1 だけポジションを上げる。

stepSizeも参照 。


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.