QML类型：Flickable

一、描述

Flickable 项将其子项放置在可以拖动和轻弹的表面上，从而使得子项上的视图滚动。

在传统的用户界面中，可以使用标准控件（例如滚动条和箭头按钮）滚动视图。在某些情况下，也可以在移动光标的同时按住鼠标按钮直接拖动视图。在基于触摸的用户界面中，这种拖动动作通常与轻弹动作相辅相成，在用户停止触摸视图后继续滚动。

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

二、使用示例

以下示例显示了大图像上的小视图，用户可以在其中拖动或轻拂图像以查看图像的不同部分。

import QtQuick 2.12
import QtQuick.Window 2.0Window
{id:root;visible: true;width: 400;height: 400;title: "hello world"Flickable{anchors.fill: parentcontentWidth: image.widthcontentHeight: image.heightImage{id: imagesource: "qrc:/img/a.jpg"}}
}

声明为 Flickable 的子项的项会自动成为 Flickable 的 contentItem 的父项。

三、contentX and contentY示例

下图演示了在各个方向上轻弹的可轻弹以及由此产生的 contentX 和 contentY 值。蓝色方块代表可轻弹的内容，黑色边框代表可轻弹的边界。

四、限制

由于实现细节，放置在 Flickable 内的项目不能锚定到 Flickable。其中的项目锚定时使用的 parent指的是 Flickable 的 contentItem。contentItem 的大小由 contentWidth 和 contentHeight 决定。

五、属性成员

1、moving : bool

movingHorizontally : bool

movingVertically : bool

当用户拖动或轻弹视图时，视图当前是否在水平、垂直或任一方向移动。

2、dragging : bool

draggingHorizontally : bool

draggingVertically : bool

当用户拖动视图时，视图当前是否在水平、垂直或任一方向移动。

3、flicking : bool

flickingHorizontally : bool

flickingVertically : bool

当用户轻弹视图，视图当前是否在水平、垂直或任一方向移动。

4、originX : real

originY : real

这些属性保存content的来源。无论布局方向如何，此值始终是指content的左上角位置。

5、bottomMargin : real

leftMargin : real

rightMargin : real

topMargin : real

这些属性保留content周围的边距。

6、contentHeight : real

contentWidth : real

content的尺寸（由 Flickable 控制的表面）。

7、atXBeginning : bool

atXEnd : bool

atYBeginning : bool

atYEnd : bool

flickable 视图是否分别位于开头或结尾。

8、horizontalVelocity : real

verticalVelocity : real

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

9、contentX : real

contentY : real

这些属性保存当前位于 Flickable 左上角的表面坐标。例如，如果将图像向上滑动 100 像素，则 contentY 将增加 100。

10、boundsBehavior : enumeration

content 是否可以在拖动、轻弹时超出 Flickable 的边界。

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

Flickable.StopAtBounds：拖动、轻弹都不能。
Flickable.DragOverBounds：拖动可以，轻弹不能。
Flickable.OvershootBounds：轻弹可以，拖动不能。
Flickable.DragAndOvershootBounds：默认。拖动、轻弹都可以。

11、boundsMovement : enumeration

Flickable 是否会让人感觉视图的边缘是软的，而不是硬的物理边界。

Flickable.StopAtBounds：允许实现自定义边缘效果，其中 content 不跟随拖动或轻弹超出可轻弹的边界。horizontalOvershoot 和 verticalOvershoot 的值可用于实现自定义边缘效果。
Flickable.FollowBoundsBehavior：默认，content 是否跟随拖动或轻弹超出 flickable 的边界由 boundsBehavior 决定。

以下示例将内容保持在边界内，而是在水平边界上轻弹时应用翻转效果：

import QtQuick 2.12
import QtQuick.Window 2.0Window
{id:root;visible: true;width: 400;height: 400;title: "hello world"Flickable{anchors.fill: parentcontentWidth: image.widthcontentHeight: image.heightImage{id: imagesource: "qrc:/img.jpg"}id: flickableboundsMovement: Flickable.StopAtBoundsboundsBehavior: Flickable.DragAndOvershootBoundstransform: Rotation{axis { x: 0; y: 1; z: 0 }origin.x: flickable.width / 2origin.y: flickable.height / 2angle: Math.min(30, Math.max(-30, flickable.horizontalOvershoot))}}
}

下面的示例将内容保持在边界内，而是在垂直边界上拖动时应用不透明效果：

import QtQuick 2.12
import QtQuick.Window 2.0Window
{id:root;visible: true;width: 400;height: 400;title: "hello world"Flickable{anchors.fill: parentcontentWidth: image.widthcontentHeight: image.heightImage{id: imagesource: "qrc:/img.jpg"}id: flickableboundsMovement: Flickable.StopAtBoundsboundsBehavior: Flickable.DragOverBoundsopacity: Math.max(0.5, 1.0 - Math.abs(verticalOvershoot) / height)}
}

12、contentItem : Item

包含要在 Flickable 中移动的项目的内部项目。

声明为 Flickable 的子项的项会自动成为 Flickable 的 contentItem 的父项。

动态创建的项目需要明确作为 contentItem 的父级：

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

13、flickDeceleration : real

此属性保存轻弹的减速速率：数字越大，当用户通过触摸、触摸板或鼠标滚轮停止轻弹时，它减慢的速度就越快。例如 0.0001 几乎是“无摩擦”，而 10000 感觉很“粘”。

默认值取决于平台。不允许为零或更小的值。

14、flickableDirection : enumeration

此属性确定可以轻弹视图的方向。

Flickable.AutoFlickDirection：默认，如果 contentHeight 不等于 Flickable 的高度，则允许垂直滑动。如果 contentWidth 不等于 Flickable 的宽度，则允许水平滑动。
Flickable.AutoFlickIfNeeded：如果 contentHeight 大于 Flickable 的高度，则允许垂直滑动。如果 contentWidth 大于 Flickable 的宽度，则允许水平滑动。
Flickable.HorizontalFlick：允许水平轻弹。
Flickable.VerticalFlick：允许垂直轻弹。
Flickable.HorizontalAndVerticalFlick：允许在两个方向上轻弹。

15、horizontalOvershoot : real

verticalOvershoot : real

水平过冲 / 垂直过冲，即 contents 被拖动或轻弹超过可轻弹边界的水平距离 / 垂直距离。

16、interactive : bool

是否可以与 Flickable 交互。用户不能拖动或轻弹非交互式的 Flickable。默认为 true。

此属性对于暂时禁用轻弹很有用。这允许与 Flickable 的子项进行特殊互动。例如，可能希望在滚动浏览作为 Flickable 子项的弹出对话框时冻结可滑动地图。

17、maximumFlickVelocity : real

可以以像素/秒为单位轻弹视图的最大速度。默认值取决于平台。

18、pixelAligned : bool

此属性将 contentX 和 contentY 的对齐方式设置为像素 (true) 或子像素 (false)。

启用 pixelAligned 以优化具有高对比度边缘的静止内容或移动内容，例如一像素宽的线条、文本或矢量图形。优化动画质量时禁用 pixelAligned。默认值为false。

19、pressDelay : int

此属性保存向 Flickable 的子项发送一个按压（press）信号的延迟时间 (ms)。在轻弹动作之前对按压做出反应会产生不良影响的情况下，这可能很有用。

如果在延迟超时之前拖动/轻弹可轻弹，则不会传递按下事件。如果在超时时间内释放按钮，则按下和释放都将传递。

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

20、rebound : Transition

当内容视图重新回到可轻弹的边界时要应用于内容视图的过渡。当视图被轻弹或拖过内容区域的边缘时，或者当 returnToBounds() 被调用时，就会触发转换。

当视图被轻弹超出其边界时，它将使用指定的过渡返回到其边界：

import QtQuick 2.12
import QtQuick.Window 2.0Window
{id:root;visible: true;width: 400;height: 400;title: "hello world"Flickable{width: 150; height: 150contentWidth: 300; contentHeight: 300rebound: Transition{NumberAnimation{properties: "x,y"duration: 1000easing.type: Easing.OutBounce}}Rectangle{width: 300; height: 300gradient: Gradient{GradientStop { position: 0.0; color: "lightsteelblue" }GradientStop { position: 1.0; color: "blue" }}}}
}

21、synchronousDrag : bool

如果此属性设置为 true，则当鼠标或触摸点移动到足够远以开始拖动 content 时，content 将跳跃，这样按下时位于光标或触摸点下方的内容像素仍保留在该点下方。

默认值为 false，它提供更流畅的体验（无跳跃），代价是在开始时“丢失”了一些拖动距离。

22、可见区域组

visibleArea.heightRatio : real

visibleArea.widthRatio : real

visibleArea.xPosition : real

visibleArea.yPosition : real

当前可见区域的位置和大小。visibleArea.widthRatio、visibleArea.heightRatio为当前可见的完整视图的宽高百分比，值的范围：0.0 - 1.0。

visibleArea.xPosition、visibleArea.yPosition 范围： 0.0 - 1.0 减去尺寸比。即 yPosition 在 0.0 - （1.0 - heightRatio）的范围内。

content 可能会被拖到正常范围之外，从而导致页面位置也在正常范围之外。

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

ScrollBar.qml

import QtQuick 2.0Rectangle
{width: 640height: 480Flickable{id: viewanchors.fill: parentcontentWidth: picture.widthcontentHeight: picture.heightImage{id: picturesource: "pics/niagara_falls.jpg"asynchronous: true}states: State{name: "ShowBars"when: view.movingVertically || view.movingHorizontallyPropertyChanges { target: verticalScrollBar; opacity: 1 }PropertyChanges { target: horizontalScrollBar; opacity: 1 }}transitions: Transition{NumberAnimation { properties: "opacity"; duration: 400 }}}ScrollBar{id: verticalScrollBarwidth: 12; height: view.height-12anchors.right: view.rightopacity: 0orientation: Qt.Verticalposition: view.visibleArea.yPositionpageSize: view.visibleArea.heightRatio}ScrollBar{id: horizontalScrollBarwidth: view.width-12; height: 12anchors.bottom: view.bottomopacity: 0orientation: Qt.Horizontalposition: view.visibleArea.xPositionpageSize: view.visibleArea.widthRatio}
}

main.qml

import QtQuick 2.0Rectangle
{width: 640height: 480Flickable{id: viewanchors.fill: parentcontentWidth: picture.widthcontentHeight: picture.heightImage{id: picturesource: "pics/niagara_falls.jpg"asynchronous: true}states: State{name: "ShowBars"when: view.movingVertically || view.movingHorizontallyPropertyChanges { target: verticalScrollBar; opacity: 1 }PropertyChanges { target: horizontalScrollBar; opacity: 1 }}transitions: Transition{NumberAnimation { properties: "opacity"; duration: 400 }}}ScrollBar{id: verticalScrollBarwidth: 12; height: view.height-12anchors.right: view.rightopacity: 0orientation: Qt.Verticalposition: view.visibleArea.yPositionpageSize: view.visibleArea.heightRatio}ScrollBar{id: horizontalScrollBarwidth: view.width-12; height: 12anchors.bottom: view.bottomopacity: 0orientation: Qt.Horizontalposition: view.visibleArea.xPositionpageSize: view.visibleArea.widthRatio}
}

六、信号成员

1、flickEnded()

当视图因轻弹而停止移动时发出此信号。

2、flickStarted()

当视图被轻弹时发出这个信号。轻弹从鼠标或触摸被释放时开始。

3、movementEnded()

当视图由于用户交互或生成的 flick() 而停止移动时会发出此信号。

4、movementStarted()

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

七、成员函数

1、cancelFlick()

取消当前的轻弹动画。

2、flick(qreal xVelocity, qreal yVelocity)

使用 xVelocity 水平滑动内容，yVelocity 垂直滑动（以像素/秒为单位）。

调用此方法会更新相应的移动和轻弹属性和信号，就像真正的轻弹一样。

3、resizeContent(real width, real height, QPointF center)

将 content 的大小调整为围绕中心的 width * height。

这不会缩放 Flickable 的内容 - 它只会调整 contentWidth 和 contentHeight。

调整 content 大小可能会导致内容位于 Flickable 的边界之外。调用 returnToBounds() 会将 content 移回合适范围内。

4、returnToBounds()

确保 content 在合适范围内。