Flickable QML Type

提供一个可“轻扫”的界面。更多...

• 所有成员的列表，包括继承的成员

属性

• acceptedButtons : flags (since 6.9)
• atXBeginning : bool
• atXEnd : bool
• atYBeginning : bool
• atYEnd : bool
• bottomMargin : real
• boundsBehavior : enumeration
• boundsMovement : enumeration
• contentHeight : real
• contentItem : Item
• contentWidth : real
• contentX : real
• contentY : real
• dragging : bool
• draggingHorizontally : bool
• draggingVertically : bool
• flickDeceleration : real
• flickableDirection : enumeration
• flicking : bool
• flickingHorizontally : bool
• flickingVertically : bool
• horizontalOvershoot : real
• horizontalVelocity : real
• interactive : bool
• leftMargin : real
• maximumFlickVelocity : real
• moving : bool
• movingHorizontally : bool
• movingVertically : bool
• originX : real
• originY : real
• pixelAligned : bool
• pressDelay : int
• rebound : Transition
• rightMargin : real
• synchronousDrag : bool
• topMargin : real
• verticalOvershoot : real
• verticalVelocity : real
• visibleArea
  • visibleArea.heightRatio : real
  • visibleArea.widthRatio : real
  • visibleArea.xPosition : real
  • visibleArea.yPosition : real

信号

• dragEnded()
• dragStarted()
• flickEnded()
• flickStarted()
• movementEnded()
• movementStarted()

方法

• void cancelFlick()
• void flick(qreal xVelocity, qreal yVelocity)
• void flickTo(point position) (since 6.11)
• void flickToChild(QQuickItem *child, PositionMode mode, point offset) (since 6.11)
• void positionViewAtChild(QQuickItem *child, PositionMode mode, point offset) (since 6.11)
• void resizeContent(real width, real height, point center)
• void returnToBounds()

详细说明

“Flickable” 控件将其子项放置在一个可拖动和轻扫的表面上，从而使子项的视图发生滚动。这种行为构成了旨在显示大量子项的控件的基础，例如ListView 和GridView 。

在传统用户界面中，可以通过标准控件（如滚动条和箭头按钮）来滚动视图。在某些情况下，也可以通过按住鼠标按钮并移动光标来直接拖动视图。 在基于触控的用户界面中，这种拖动操作通常会辅以轻扫动作，即用户停止触摸视图后，滚动仍会继续。

Flickable 不会自动裁剪其内容。如果未将其用作全屏项，应考虑将 `clip ` 属性设置为 `true`。

使用示例

以下示例展示了一个大型图像的小视图，用户可以通过拖动或轻扫图像来查看其不同部分。

import QtQuick

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

声明为 Flickable 子元素的项会自动成为 Flickable 的contentItem 的子元素。在操作 Flickable 的子元素时应考虑到这一点；通常与之相关的是contentItem 的子元素。例如，可通过以下方式获取添加到 Flickable 中的项的边界：contentItem.childrenRect

contentX 和 contentY 的示例

下图演示了 Flickable 在不同方向上被轻扫时的效果，以及相应的contentX 和contentY 值。蓝色方块代表 Flickable 的内容，黑色边框代表 Flickable 的边界。

限制

属性文档

acceptedButtons : flags [since 6.9]

可用于通过拖动来滚动此 Flickable 的鼠标按钮。

默认情况下，此属性设置为Qt.LeftButton ，其行为与之前的 Qt 版本相同；但在大多数用户界面中，这种行为会出乎意料。用户通常期望仅在触摸屏上进行轻扫操作，并使用鼠标滚轮、触控板手势或滚动条（通过鼠标或触控板）进行滚动。将其设置为Qt.NoButton 可禁用拖动功能。

该属性可设置为鼠标按钮的“或”组合，并将忽略来自其他按钮的事件。

该属性于 Qt 6.9 中引入。

如果可滑动视图分别位于起始位置或末尾位置，则这些属性为真。

这些属性控制内容周围的边距。除了contentWidth 和contentHeight 之外，还会额外预留这部分空间。

boundsBehavior : enumeration

该属性决定表面是否可以被拖动到 Flickable 的边界之外，或者在轻扫时是否会超出 Flickable 的边界。

当boundsMovement 的值为Flickable.FollowBoundsBehavior 时，若该属性值不为Flickable.StopAtBounds ，则会给人一种视图边缘较为柔和的感觉，而非坚硬的物理边界。

boundsBehavior 可以是以下值之一：

• Flickable.StopAtBounds — 内容无法被拖拽至可滑动区域（flickable）边界之外，且滑动操作不会超出边界。
• Flickable.DragOverBounds - 内容可被拖拽至 Flickable 边界之外，但滑动操作不会超出边界。
• Flickable.OvershootBounds — 内容在轻扫时可以超出边界，但无法被拖动到 Flickable 的边界之外。（自QtQuick 2.5 起）
• Flickable.DragAndOvershootBounds（默认）——内容既可以被拖动到 Flickable 的边界之外，在轻扫时也可以超出边界。

另请参阅 horizontalOvershoot 、verticalOvershoot 以及boundsMovement 。

boundsMovement : enumeration

该属性决定了可滑动视图是否会给人一种视图边缘是柔和的、而非硬性的物理边界的感觉。

boundsMovement 的取值可以是以下之一：

• Flickable.StopAtBounds — 允许实现自定义边缘效果，即内容不会跟随拖动或轻扫操作超出可轻扫区域的边界。可通过调整 `horizontalOvershoot ` 和 `verticalOvershoot ` 的值来实现自定义边缘效果。
• Flickable.FollowBoundsBehavior（默认）——内容是否跟随拖动或轻扫动作超出可轻扫区域的边界，由boundsBehavior 决定。

以下示例将内容限制在边界内，并在横向滑出边界时应用翻转效果：

Flickable {
    id: flickable
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragAndOvershootBounds
    transform: Rotation {
        axis { x: 0; y: 1; z: 0 }
        origin.x: flickable.width / 2
        origin.y: flickable.height / 2
        angle: Math.min(30, Math.max(-30, flickable.horizontalOvershoot))
    }
}

以下示例将内容限制在边界内，并在横向超出边界时应用不透明度效果：

Flickable {
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragOverBounds
    opacity: Math.max(0.5, 1.0 - Math.abs(verticalOvershoot) / height)
}

另请参阅 boundsBehavior 、verticalOvershoot 和horizontalOvershoot 。

内容的尺寸（即由 Flickable 控制的区域）。通常应将其设置为放置在 Flickable 中的各项元素的总尺寸。

以下代码片段演示了如何利用这些属性来显示一张比 Flickable 项目本身更大的图片：

import QtQuick

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

在某些情况下，可以根据contentItem 的childrenRect.width 和childrenRect.height 属性自动设置内容尺寸。例如，前面的代码片段可以重写为：

contentWidth: contentItem.childrenRect.width; contentHeight: contentItem.childrenRect.height

不过这假设 childrenRect 的原点为 (0, 0)。

contentItem : Item [read-only]

Flickable 中包含待移动项的内部项。

声明为 Flickable 子元素的项目会自动成为 Flickable 的 contentItem 的子元素。

动态创建的项需要显式地将其父项设置为contentItem：

Flickable {
    id: myFlickable
    function addItem(file) {
        var component = Qt.createComponent(file)
        component.createObject(myFlickable.contentItem);
    }
}

这些属性存储了当前位于 Flickable 左上角的表面坐标。例如，如果你将图片向上滑动 100 像素，contentY 的值就会增加 100。

另请参阅 Examples of contentX and contentY 、originX 以及originY 。

这些属性描述了视图当前是否因用户拖动而正在水平、垂直或双向移动。

flickDeceleration : real

该属性控制轻扫动作的减速速率：数值越大，当用户停止轻扫时，减速速度就越快。例如，0.0001 几乎“无摩擦”，而 10000 则感觉相当“粘滞”。

默认值因平台而异。不允许设置为零或负值。

flickableDirection : enumeration

该属性用于确定视图可进行哪些方向的轻扫操作。

• Flickable.AutoFlickDirection（默认）——当contentHeight不等于 Flickable 的高度时，允许垂直滑动；当contentWidth不等于 Flickable 的宽度时，允许水平滑动。
• Flickable.AutoFlickIfNeeded - 当contentHeight大于 Flickable 的高度时，允许垂直滑动。当contentWidth大于 Flickable 的宽度时，允许水平滑动。（自QtQuick 2.7 起）
• Flickable.HorizontalFlick - 允许水平滑动。
• Flickable.VerticalFlick - 允许垂直滑动。
• Flickable.HorizontalAndVerticalFlick - 允许双向滑动。

这些属性描述了视图当前是正在水平移动、垂直移动，还是由于用户轻扫视图而在两个方向上同时移动。

horizontalOvershoot : real [read-only]

该属性存储水平超距，即内容被拖动或轻扫超出可轻扫区域边界的水平距离。当内容被拖动或轻扫至起始位置之外时，该值为负；当超出结束位置时，该值为正；否则，该值为0.0 。

是否报告拖动和/或弹指操作的超调距离由boundsBehavior 决定。即使boundsMovement 为Flickable.StopAtBounds ，也会报告超调距离。

另请参阅 verticalOvershoot 、boundsBehavior 和boundsMovement 。

沿 x 轴和 y 轴的瞬时移动速度，单位为像素/秒。

报告的速度值经过平滑处理，以避免输出结果出现波动。

请注意，对于内容体积较大的视图（超过视图大小的10倍），当连续快速进行多次轻扫时，轻扫速度可能会超过触摸速度。这使用户能够更快地浏览大容量内容。

interactive : bool

该属性描述了用户是否可以与 Flickable 进行交互。如果 Flickable 不具备交互性，用户将无法对其进行拖动或轻扫操作。

默认情况下，该属性的值为 true。

该属性可用于临时禁用弹指操作。这使得与 Flickable 的子元素进行特殊交互成为可能；例如，当您在滚动浏览作为 Flickable 子元素的弹出对话框时，可能需要冻结可弹指地图。

maximumFlickVelocity : real

该属性表示用户可以以每秒多少像素的速度快速滑动视图。

默认值取决于平台。

这些属性描述了视图当前是否因用户拖动或轻扫而正在水平、垂直或双向移动。

这些属性保存了内容的原点。无论布局方向如何，该值始终指代内容的左上角位置。

通常为 (0,0)，但ListView 和GridView 可能因委托对象大小变化，或项目在可见区域外插入/移除，而具有任意原点。

另请参阅 contentX 和contentY 。

pixelAligned : bool

此属性将contentX 和contentY 的对齐方式设置为像素（true ）或亚像素（false ）。

启用 `pixelAligned` 可针对静态内容或具有高对比度边缘的动态内容（例如 1 像素宽的线条、文本或矢量图形）进行优化。在优化动画质量时，请禁用 `pixelAligned`。

默认值为false 。

pressDelay : int

该属性用于设置向 Flickable 的子元素发送按压事件前的延迟时间（毫秒）。当在滑动操作完成前对按压事件做出响应会产生不良影响时，此属性非常有用。

如果在延迟超时之前对 Flickable 进行了拖动或轻扫，则按下事件不会被传递。如果按钮在超时内被释放，则按下和释放事件都会被传递。

请注意，对于设置了 pressDelay 的嵌套 Flickable，最内层的 Flickable 会覆盖外层 Flickable 的 pressDelay 设置。如果拖动操作超过了平台的拖动阈值，无论此属性如何设置，按压事件都将被传递。

另请参阅 QStyleHints 。

rebound : Transition

该属性用于存储当内容视图弹回可滑动区域的边界时，应应用于该视图的过渡效果。当视图被轻扫或拖动至内容区域边缘之外，或者调用returnToBounds()方法时，将触发该过渡效果。

import QtQuick 2.0

Flickable {
    width: 150; height: 150
    contentWidth: 300; contentHeight: 300

    rebound: Transition {
        NumberAnimation {
            properties: "x,y"
            duration: 1000
            easing.type: Easing.OutBounce
        }
    }

    Rectangle {
        width: 300; height: 300
        gradient: Gradient {
            GradientStop { position: 0.0; color: "lightsteelblue" }
            GradientStop { position: 1.0; color: "blue" }
        }
    }
}

当上述视图被滑动超出其边界时，它将使用指定的过渡效果返回其边界：

如果未设置此属性，则应用默认动画。

synchronousDrag : bool

如果将此属性设置为 true，那么当鼠标或触点移动到足够远的位置以开始拖动内容时，内容会发生跳转，使得按下时位于光标或触点下方的内容像素仍保持在该点下方。

默认值为false ，这会提供更流畅的体验（无跳动），但代价是拖动开始时会“损失”部分拖动距离。

verticalOvershoot : real [read-only]

该属性存储垂直超程值，即内容被拖动或轻扫时超出可轻扫区域边界的垂直距离。当内容被拖动或轻扫至起始位置之外时，该值为负；当超出结束位置时，该值为正；其他情况下，该值为0.0 。

是否报告拖动和/或轻扫操作的超距值由boundsBehavior 决定。即使boundsMovement 的值为Flickable.StopAtBounds ，超距距离仍会被报告。

另请参阅 horizontalOvershoot 、boundsBehavior 和boundsMovement 。

visibleArea group

这些属性描述了当前可见区域的位置和大小。大小定义为当前可见区域占整个视图的百分比，并按 0.0 到 1.0 的范围进行缩放。 页面位置通常在 0.0（起始位置）到 1.0 减去大小比例（结束位置）的范围内，即 `yPosition ` 的取值范围为 0.0 到 1.0 - `heightRatio`。 但是，内容有可能被拖动到正常范围之外，导致页面位置也超出正常范围。

这些属性通常用于绘制滚动条。例如：

Rectangle {
    width: 200; height: 200

    Flickable {
        id: flickable
        ...
    }

    Rectangle {
        id: scrollbar
        anchors.right: flickable.right
        y: flickable.visibleArea.yPosition * flickable.height
        width: 10
        height: flickable.visibleArea.heightRatio * flickable.height
        color: "black"
    }
}

Signal 文档

dragEnded()

当用户停止拖动视图时，会触发此信号。

如果在释放触摸或鼠标按钮时拖动速度足够快，则会触发轻扫操作。

dragStarted()

当视图因用户交互而开始被拖动时，会触发此信号。

flickEnded()

当视图在一次或多次轻扫后停止移动时，会发出此信号。

flickStarted()

当视图被轻扫时，会触发此信号。轻扫操作始于鼠标或触摸释放的瞬间，此时鼠标或触摸仍处于移动状态。

movementEnded()

当视图因用户交互或调用了flick()方法而停止移动时，会发出此信号。如果当时有“轻扫”操作正在进行，则该信号会在“轻扫”停止时发出；如果当时没有“轻扫”操作，则该信号会在用户停止拖动时发出——即鼠标或触摸操作释放时。

movementStarted()

当视图因用户交互或生成的flick() 而开始移动时，会触发此信号。

方法文档

void cancelFlick()

取消当前的轻扫动画。

void flick(qreal xVelocity, qreal yVelocity)

以xVelocity 的速率水平滑动内容，以yVelocity 的速率垂直滑动内容，单位为像素/秒。

调用此方法将更新相应的移动和轻扫属性及信号，就像真正的触摸屏轻扫操作一样。

[since 6.11] void flickTo(point position)

将可滑动内容滑动至position 。

如果滑动该可滑动控件会导致其在开头或结尾处显示空白区域，则该控件将在边界处停止滑动。

该方法在 Qt 6.11 中引入。

[since 6.11] void flickToChild(QQuickItem *child, PositionMode mode, point offset)

轻点可轻点区域，使child 项（如果它是子项）位于mode 指定的位置。mode 可以是以下选项的“或”运算组合：

如果未指定垂直对齐方式，则将忽略垂直轻扫操作。水平对齐的情况也是如此。

可选地，您可以指定 `offset `，以在目标对齐位置之外额外滑动若干像素。

如果对子项进行“flickable”操作会导致“flickable”区域的开头或结尾显示空白区域，则“flickable”将在边界处停止操作。

import QtQuick
import QtQuick.Controls
import QtQuick.Window

Flickable {
    id: flickable

    width: 200
    height: 200
    contentWidth: width
    contentHeight: column.height

    // Will flick to the beginning of the activeFocusItem every time it changes
    property Item activeFocusItem: Window.activeFocusItem
    onActiveFocusItemChanged: flickable.flickToChild(activeFocusItem, Flickable.AlignTop)

    Column {
        id: column

        spacing: 10

        Repeater {
            model: 10
            TextArea {}
        }
    }
}

此方法于 Qt 6.11 中引入。

[since 6.11] void positionViewAtChild(QQuickItem *child, PositionMode mode, point offset)

将contentX 和contentY 设置为使child 项（如果是子节点）位于mode 指定的位置。mode 可以是以下选项的“或”运算组合：

如果未指定垂直对齐方式，则将忽略垂直定位。水平对齐也是如此。

可选地，您可以指定 `offset `，将`contentX` 和 `contentY` 向目标对齐位置之外额外移动指定像素数。

如果将可滑动控件定位在子项上会导致其开头或结尾显示空白区域，则该控件将定位在边界处。

import QtQuick
import QtQuick.Controls
import QtQuick.Window

Flickable {
    id: flickable

    width: 200
    height: 200
    contentWidth: width
    contentHeight: column.height

    // Will center activeFocusItem in the Flickable every time it changes
    property Item activeFocusItem: Window.activeFocusItem
    onActiveFocusItemChanged: flickable.positionViewAtChild(activeFocusItem, Flickable.AlignCenter)

    Column {
        id: column

        spacing: 10

        Repeater {
            model: 10
            TextArea {}
        }
    }
}

此方法自 Qt 6.11 起引入。

void resizeContent(real width, real height, point center)

将内容调整为width xheight ，比例约为center 。

这不会缩放 Flickable 中的内容——它仅调整contentWidth 和contentHeight 的大小。

调整内容大小可能会导致内容超出 Flickable 的边界。调用returnToBounds() 将使内容重新移回有效范围内。

void returnToBounds()

确保内容符合法律规定。

在手动调整内容位置后，可调用此方法以确保内容符合法律规定。