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 子项的项目会自动成为 FlickablecontentItem 的父项。在对 Flickable 的子项进行操作时应考虑到这一点；通常情况下，contentItem 的子项才是相关的。例如，添加到 Flickable 中的项目的绑定可以通过以下方式获得contentItem.childrenRect

contentX 和 contentY 示例

下面的图片演示了向不同方向弹动 flickable 以及由此产生的contentX 和contentY 值。蓝色方块代表 flickable 的内容，黑色边框代表 flickable 的边界。

限制

属性文档

acceptedButtons : flags [since 6.9]

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

默认情况下，此属性设置为Qt.LeftButton ，它提供了与 Qt XML 以前版本相同的行为；但在大多数用户界面中，这种行为是出乎意料的。用户希望只在触摸屏上滑动，而使用鼠标滚轮、触摸板手势或带有鼠标或触摸板的滚动条。将其设置为Qt.NoButton 可禁用拖动。

它可以设置为鼠标按钮的 OR 组合，并将忽略来自其他按钮的事件。

此属性在 Qt 6.9 中引入。

如果可闪烁视图分别位于开始或结束位置，则这些属性为 true。

这些属性保留了内容周围的边距。除了contentWidth 和contentHeight 之外，还预留了这些空间。

boundsBehavior : enumeration

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

当boundsMovement 是Flickable.FollowBoundsBehavior 时，如果值不是Flickable.StopAtBounds ，就会让人感觉视图的边缘是软的，而不是硬的物理边界。

boundsBehavior 可以是

• Flickable.StopAtBounds--内容不能拖动到可闪烁的边界之外，闪烁也不会越界。
• Flickable.DragOverBounds - 可将内容拖动到 Flickable 边界之外，但闪烁不会超调。
• Flickable.OvershootBounds - 在轻弹时，内容可以越过边界，但内容不能被拖动到可轻弹的边界之外。(自QtQuick 2.5 起）
• Flickable.DragAndOvershootBounds（默认）- 内容可以拖动到 Flickable 边界之外，并且在轻弹时可以越过边界。

另请参阅 horizontalOvershoot,verticalOvershoot, 和boundsMovement 。

boundsMovement : enumeration

该属性表示可闪烁视图是否会让人感觉视图的边缘是柔和的，而不是坚硬的物理边界。

boundsMovement 可以是

• Flickable.StopAtBounds--该属性允许实现自定义边缘效果，在这种效果下，内容不会随着拖动或弹动超出 flickable 的边界。horizontalOvershoot 和verticalOvershoot 的值可用于实现自定义边缘特效。
• Flickable.FollowBoundsBehavior（默认）--内容是否跟随拖动或轻移超出 flickable 的边界由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 内容项目的父项。

动态创建的项目需要明确地作为内容项目的父项目：

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 则感觉相当 "粘"。

默认值取决于平台。不允许使用 0 或更小的值。

flickableDirection : enumeration

该属性决定视图可以向哪个方向滑动。

• Flickable.AutoFlickDirection（默认）-- 如果contentHeight（内容 高度）不等于 Flickable 的高度，则允许垂直弹动。如果contentWidth不等于 Flickable 的宽度，则允许水平滑动。
• Flickable.AutoFlickIfNeeded - 如果内容高度大于 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 可优化具有高对比度边缘的静态内容或移动内容，如一像素宽的线条、文本或矢量图形。在优化动画质量时，禁用 pixelAligned。

默认值为false 。

pressDelay : int

该属性设置了向 Flickable 子代传递按压的延迟时间（毫秒）。如果在滑动操作之前对按压做出反应会产生不良影响，那么该属性就非常有用。

如果在延迟超时前拖动/滑动了可闪烁按钮，则不会发送按压事件。如果在超时内松开按钮，则按下和松开事件都将被触发。

请注意，对于设置了 pressDelay 的嵌套可闪动体，外层可闪动体的 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"
    }
}

信号文档

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 。

如果弹动 flickable 会导致在 flickable 的开始或结束处显示空白空间，那么 flickable 将在边界处停止弹动。

此方法在 Qt 6.11 中引入。

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

弹动可弹动条目，使child 条目（如果是子条目）位于mode 指定的位置。mode 可以是以下内容的任意组合：

如果没有指定垂直对齐方式，垂直移动将被忽略。水平对齐方式也是如此。

作为选项，您可以指定offset ，在目标对齐方式之外多弹出若干像素。

如果在子项目处轻弹可闪烁控件会导致在可闪烁控件的开始或结束处显示空白空间，那么可闪烁控件将在边界处停止轻弹。

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移动到目标对齐方式之外的额外像素数。

如果将 flickable 定位在子项目上会导致在 flickable 的开头或结尾显示空白空间，那么 flickable 将被定位在边界上。

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()

确保内容在合法范围内。

在手动定位内容后，可调用此功能确保内容在合法范围内。