Тип QML Flickable

Предоставляет поверхность, которую можно «прокрутить». Подробнее...

Заявление об импорте:	import QtQuick 2.11
Наследует:	Item
Наследуется:	GridView и ListView

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

Свойства

atXBeginning : bool
atXEnd : bool
atYBeginning : bool
atYEnd : bool
bottomMargin : real
boundsBehavior : перечисление
boundsMovement : перечисление
contentHeight : real
contentItem : Item
contentWidth : real
contentX : real
contentY : real
dragging : bool
draggingHorizontally : bool
draggingVertically : bool
flickDeceleration : real
flickableDirection : перечисление
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
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

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

	Значения `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

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

atXEnd : bool

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

atYBeginning : bool

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

atYEnd : bool

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

bottomMargin : real

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

boundsBehavior : перечисление

Это свойство определяет, может ли поверхность быть перетащена за пределы границ 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 : перечисление

Это свойство определяет, будет ли 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 : вещественное

Размеры содержимого (поверхности, контролируемой 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 Flickable.

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

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

contentWidth : вещественное

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 : вещественное

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

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

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

contentY : вещественное

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

dragging : логическое

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

draggingHorizontally : логическое

draggingVertically : логическое

flickDeceleration : вещественное

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

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

flickableDirection : перечисление

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

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 : логическое

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

flickingHorizontally : логическое

flickingVertically : логическое

horizontalOvershoot : вещественное

Это свойство содержит горизонтальный перехват, то есть горизонтальное расстояние, на которое содержимое было перетащено или протащено за пределы области прокручиваемого элемента. Значение отрицательное, когда содержимое перетащено или протащено за начало, и положительное, когда за конец; 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 перетаскивается/протаскивается до истечения срока задержки, событие нажатия не будет доставлено. Если кнопка отпущена в течение времени ожидания, будут доставлены как событие нажатия, так и отпуска.

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

См. также 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" }
        }
    }
}

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

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

rightMargin : real

topMargin : real

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

См. также UI Components: Scrollbar Example.

Документация сигналов

flickEnded()

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

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

flickStarted()

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

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

movementEnded()

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

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

movementStarted()

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

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

Документация по методам

cancelFlick()

Отменяет текущую анимацию flick.

flick(qreal xVelocity, qreal yVelocity)

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

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

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/archives/qt-5.11/qml-qtquick-flickable.html