Тип Flickable QML

Обеспечивает поверхность, по которой можно "пролистывать". Подробнее...

Оператор импорта:	import QtQuick 2.12
Наследует:	Item
Наследуется:	GridView, ListView, и TableView

Список всех членов, включая унаследованные

Свойства

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.xPosition : real
- visibleArea.widthRatio : real
- visibleArea.yPosition : real
- visibleArea.heightRatio : real

Сигналы

Методы

cancelFlick()
flick(qreal xVelocity, qreal yVelocity)
resizeContent(real width, real height, QPointF center)
returnToBounds()

Подробное описание

Элемент Flickable размещает своих потомков на поверхности, которую можно перетаскивать и пролистывать, вызывая прокрутку представления дочерних элементов. Это поведение составляет основу элементов, предназначенных для отображения большого количества дочерних элементов, таких как ListView и GridView.

В традиционных пользовательских интерфейсах прокрутка представлений может осуществляться с помощью стандартных элементов управления, таких как полосы прокрутки и кнопки со стрелками. В некоторых ситуациях также можно напрямую перетаскивать представление, нажимая и удерживая кнопку мыши, перемещая курсор. В сенсорных пользовательских интерфейсах это действие перетаскивания часто дополняется действием пролистывания, когда прокрутка продолжается после того, как пользователь прекратил касание представления.

Flickable не автоматически обрезает свое содержимое. Если он не используется как полноэкранный элемент, следует рассмотреть возможность установки свойства clip в значение true.

Пример использования

В следующем примере показано небольшое представление большого изображения, в котором пользователь может перетаскивать или пролистывать изображение, чтобы просматривать его различные части.

import QtQuick 2.0

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

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

Элементы, объявленные как дочерние элементы Flickable, автоматически становятся дочерними элементами contentItem Flickable. Это следует учитывать при работе с дочерними элементами Flickable; обычно это дочерние элементы contentItem, которые имеют значение. Например, граница элементов, добавленных в Flickable, будет доступна с помощью contentItem.childrenRect

Примеры contentX и contentY

На следующих изображениях показан пролистываемый элемент, пролистываемый в разных направлениях, и результирующие значения contentX и contentY. Синий квадрат представляет содержимое пролистываемого элемента, а черная граница представляет границы пролистываемого элемента.

	Значения `contentX` и `contentY` равны `0`.
	Значение `contentX` и `contentY` равны `50`.
	Значение `contentX` равно `-50`, а `contentY` равно `50`.
	Значение `contentX` и `contentY` равны `-50`.
	Значение `contentX` равно `50`, а `contentY` равно `-50`.

Ограничения

Примечание: Из-за особенности реализации элементы, размещенные внутри Flickable, не могут быть привязаны к Flickable. Вместо этого используйте parent, который ссылается на contentItem Flickable. Размер элемента содержимого определяется параметрами contentWidth и contentHeight.

Описание свойств

atXBeginning : bool

Эти свойства истинны, если представление flickable находится в начале или конце соответственно.

atXEnd : bool

Эти свойства истинны, если представление flickable находится в начале или конце соответственно.

atYBeginning : bool

Эти свойства истинны, если представление flickable находится в начале или конце соответственно.

atYEnd : bool

Эти свойства истинны, если представление flickable находится в начале или конце соответственно.

bottomMargin : real

Эти свойства содержат поля вокруг контента. Это пространство резервируется в дополнение к 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

Это свойство определяет, будет ли flickable создавать ощущение, что края представления мягкие, а не жесткая физическая граница.

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

Это свойство было добавлено в Qt 5.10.

См. также boundsBehavior, verticalOvershoot и horizontalOvershoot.

contentHeight : real

Размеры контента (поверхность, управляемая Flickable). Обычно это должно быть установлено в объединенный размер элементов, размещенных в Flickable.

В следующем фрагменте кода показано, как эти свойства используются для отображения изображения, которое больше, чем сам элемент Flickable:

import QtQuick 2.0

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

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

В некоторых случаях размеры контента могут быть установлены автоматически на основе свойств childrenRect.width и childrenRect.height элемента contentItem. Например, предыдущий фрагмент кода можно переписать так:

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

Хотя это предполагает, что начало childrenRect равно 0,0.

contentItem : Item

Внутренний элемент, содержащий элементы, которые будут перемещаться в Flickable.

Элементы, объявленные как дочерние элементы Flickable, автоматически становятся дочерними элементами contentItem.

Динамически созданные элементы должны быть явно связаны с contentItem:

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

contentWidth : real

import QtQuick 2.0

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

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

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

Хотя это предполагает, что начало childrenRect равно 0,0.

contentX : real

Эти свойства содержат координату поверхности, которая в данный момент находится в левом верхнем углу Flickable. Например, если вы смахнете изображение вверх на 100 пикселей, contentY увеличится на 100.

Примечание: Если вы смахнете обратно к началу (в левый верхний угол), после анимации отскока, contentX установится на то же значение, что и originX, а contentY на originY. Обычно это (0,0), однако ListView и GridView могут иметь произвольное начало из-за изменения размера делегата или вставки/удаления элементов за пределами видимой области. Поэтому, если вы хотите реализовать что-то вроде вертикальной полосы прокрутки, один из способов - использовать y: (contentY - originY) * (height / contentHeight) для позиции; другой способ - использовать нормализованные значения в visibleArea.

См. также Примеры contentX и contentY, originX и originY.

contentY : real

См. также Примеры contentX и contentY, originX и originY.

dragging : bool

Эти свойства описывают, перемещается ли представление в данный момент по горизонтали, вертикали или в любом направлении из-за перетаскивания представления пользователем.

draggingHorizontally : bool

draggingVertically : bool

flickDeceleration : real

Это свойство содержит скорость, с которой будет замедляться смахивание.

Значение по умолчанию зависит от платформы.

flickableDirection : enumeration

Это свойство определяет, в каких направлениях можно смахивать представление.

Flickable.AutoFlickDirection (по умолчанию) - разрешает смахивание по вертикали, если contentHeight не равен height Flickable. Разрешает смахивание по горизонтали, если contentWidth не равен width Flickable.
Flickable.AutoFlickIfNeeded - разрешает смахивание по вертикали, если contentHeight больше, чем height Flickable. Разрешает смахивание по горизонтали, если contentWidth больше, чем width Flickable. (начиная с QtQuick 2.7)
Flickable.HorizontalFlick - разрешает смахивание по горизонтали.
Flickable.VerticalFlick - разрешает смахивание по вертикали.
Flickable.HorizontalAndVerticalFlick - разрешает смахивание в обоих направлениях.

flicking : bool

Эти свойства описывают, перемещается ли представление в данный момент по горизонтали, вертикали или в любом направлении из-за смахивания представления пользователем.

flickingHorizontally : bool

flickingVertically : bool

horizontalOvershoot : real

Это свойство содержит горизонтальный перескок, то есть горизонтальное расстояние, на которое содержимое было перетащено или отброшено за пределы области прокрутки. Значение отрицательное, когда контент перетаскивается или отбрасывается за начало, и положительное, когда за конец; 0.0 в противном случае.

Определяется ли вывод значений для перетаскивания и/или отбрасывания, зависит от boundsBehavior. Расстояние перескока сообщается даже тогда, когда boundsMovement равно Flickable.StopAtBounds.

Это свойство было добавлено в Qt 5.9.

См. также verticalOvershoot, boundsBehavior и boundsMovement.

horizontalVelocity : real

Мгновенная скорость движения вдоль осей x и y, в пикселях/сек.

Сообщаемая скорость сглаживается, чтобы избежать нестабильного вывода.

Обратите внимание, что для представлений с большим размером контента (более чем в 10 раз больше размера представления) скорость отбрасывания может превышать скорость касания в случае нескольких быстрых последовательных отбрасываний. Это позволяет пользователю быстрее пролистывать большой контент.

interactive : bool

Это свойство описывает, может ли пользователь взаимодействовать с Flickable. Пользователь не может перетаскивать или отбрасывать Flickable, который не является интерактивным.

По умолчанию это свойство имеет значение true.

Это свойство полезно для временного отключения прокрутки. Это позволяет специальное взаимодействие с дочерними элементами Flickable; например, вы можете захотеть заморозить карту flickable во время прокрутки всплывающего диалогового окна, которое является дочерним элементом Flickable.

leftMargin : real

Эти свойства содержат поля вокруг контента. Это пространство резервируется в дополнение к contentWidth и contentHeight.

maximumFlickVelocity : real

Это свойство содержит максимальную скорость, с которой пользователь может отбросить представление в пикселях/секунду.

Значение по умолчанию зависит от платформы.

moving : bool

Эти свойства описывают, движется ли представление в данный момент по горизонтали, вертикали или в любом направлении из-за того, что пользователь перетаскивает или отбрасывает представление.

movingHorizontally : bool

movingVertically : bool

originX : real

Эти свойства содержат начало контента. Это значение всегда относится к левому верхнему положению контента независимо от направления компоновки.

Обычно это (0,0), однако ListView и GridView могут иметь произвольное начало из-за вариации размера делегата или вставки/удаления элементов за пределами видимой области.

См. также contentX и contentY.

originY : real

См. также contentX и contentY.

pixelAligned : bool

Это свойство устанавливает выравнивание contentX и contentY к пикселям (true) или субпикселям (false).

Включите pixelAligned для оптимизации неподвижного контента или движущегося контента с высококонтрастными краями, такими как линии шириной в один пиксель, текст или векторная графика. Отключите pixelAligned при оптимизации качества анимации.

Значение по умолчанию — false.

pressDelay : int

Это свойство содержит время задержки (мс) доставки нажатия дочерним элементам Flickable. Это может быть полезно, когда реакция на нажатие до начала действия прокрутки имеет нежелательные последствия.

Если flickable перетаскивается/отбрасывается до истечения времени задержки, событие нажатия не будет доставлено. Если кнопка отпускается в течение времени ожидания, будут доставлены как нажатие, так и отпускание.

Обратите внимание, что для вложенных Flickables с установленным pressDelay, pressDelay внешних Flickables переопределяется самым внутренним Flickable. Если перетаскивание превышает пороговое значение перетаскивания платформы, событие нажатия будет доставлено независимо от этого свойства.

См. также QStyleHints.

rebound : Transition

Это содержит переход, который будет применен к представлению контента, когда оно возвращается к границам flickable. Переход активируется, когда представление отбрасывается или перетаскивается за край области контента, или когда вызывается 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" }
        }
    }
}

Когда вышеуказанное представление отбрасывается за свои границы, оно вернется к своим границам, используя указанный переход:

Если это свойство не установлено, применяется анимация по умолчанию.

rightMargin : real

Эти свойства содержат поля вокруг контента. Это пространство резервируется в дополнение к contentWidth и contentHeight.

synchronousDrag : bool

Если это свойство установлено в true, то когда мышь или точка касания перемещаются достаточно далеко, чтобы начать перетаскивание контента, контент перескочит так, чтобы пиксель контента, который находился под курсором или точкой касания при нажатии, оставался под этой точкой.

Значение по умолчанию — false, что обеспечивает более плавный опыт (без перескока) за счет того, что часть расстояния перетаскивания «теряется» в начале.

Это свойство было добавлено в Qt 5.12.

topMargin : real

Эти свойства содержат поля вокруг контента. Это пространство резервируется в дополнение к contentWidth и contentHeight.

verticalOvershoot : real

Это свойство содержит вертикальный перескок, то есть вертикальное расстояние, на которое содержимое было перетащено или отброшено за пределы области прокрутки. Значение отрицательное, когда контент перетаскивается или отбрасывается за начало, и положительное, когда за конец; 0.0 в противном случае.

Это свойство было добавлено в Qt 5.9.

См. также horizontalOvershoot, boundsBehavior и boundsMovement.

verticalVelocity : real

Мгновенная скорость движения вдоль осей x и y, в пикселях/сек.

Сообщаемая скорость сглаживается, чтобы избежать нестабильного вывода.

visibleArea.xPosition : real

Эти свойства описывают положение и размер текущей видимой области. Размер определяется как процент от полного представления, видимого в данный момент, масштабированный до 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"
    }
}

См. также Компоненты пользовательского интерфейса: Пример полосы прокрутки.

Описание сигналов

flickEnded()

Этот сигнал испускается, когда представление перестает двигаться из-за отбрасывания.

Соответствующий обработчик — onFlickEnded.

flickStarted()

Этот сигнал испускается, когда представление пролистывается. Пролистывание начинается с точки, в которой отпускается мышь или касание, при этом оставаясь в движении.

Соответствующий обработчик — onFlickStarted.

movementEnded()

Этот сигнал испускается, когда представление перестает двигаться из-за взаимодействия пользователя или сгенерированного flick(). Если пролистывание было активным, этот сигнал будет испущен после остановки пролистывания. Если пролистывание не было активным, этот сигнал будет испущен, когда пользователь прекратит перетаскивание — т. е. отпускание мыши или касания.

Соответствующий обработчик — onMovementEnded.

movementStarted()

Этот сигнал испускается, когда представление начинает двигаться из-за взаимодействия пользователя или сгенерированного flick().

Соответствующий обработчик — onMovementStarted.

Описание методов

cancelFlick()

Отменяет текущую анимацию пролистывания.

flick(qreal xVelocity, qreal yVelocity)

Пролистывает содержимое с xVelocity по горизонтали и yVelocity по вертикали в пикселях/сек.

Вызов этого метода обновит соответствующие свойства и сигналы движения и пролистывания, как и при реальном пролистывании.

resizeContent(real width, real height, QPointF center)

Изменяет размер содержимого на width x height относительно center.

Это не масштабирует содержимое Flickable — это только изменяет размер contentWidth и contentHeight.

Изменение размера содержимого может привести к тому, что содержимое окажется за пределами границ Flickable. Вызов returnToBounds() вернет содержимое в допустимые границы.

returnToBounds()

Убеждается, что содержимое находится в допустимых границах.

Это может быть вызвано для того, чтобы убедиться, что содержимое находится в допустимых границах после ручного позиционирования содержимого.

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-5.12/qml-qtquick-flickable.html