QML-тип PullToRefresh

Предоставляет жест Pull-to-refresh для элементов графического интерфейса. Подробнее…

Строка импорта:

import Aurora.Controls 1.0

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

Прикрепляемые свойства

• description : string
• enabled : bool
• refreshHandler : var
• view.refreshIndicator : Component

Прикрепляемые методы

• void fireRefresh()
• void refreshCompleted(bool success)
• void refreshCompletedCustom(string iconSource, string message)

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

Pull-to-refresh — это жест, позволяющий обновить содержимое графического элемента путём нажатия на него и смещения точки касания вниз в область срабатывания жеста. При достижении зоны срабатывания и отпуске пальца запускается обновление.

Элемент, для которого включен жест, называется RefreshContainer.

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

Пользовательский интерфейс жеста

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

Состояние жестов

У жеста есть 6 состояний, между которыми он переключается в зависимости от входных данных:

• Бездействие — состояние жеста по умолчанию. Пользователь не взаимодействует с RefreshContainer через прикосновение, и жест не находится в состоянии Обновление или Отображение состояния обновления. Визуально пользовательский интерфейс жеста не отображается.

• Взаимодействие — когда пользователь активировал жест, потянув точку касания вниз, и до достижения границы срабатывания.

  • Если пользователь отпустит точку касания, находясь в этом состоянии, жест вернётся в состояние Бездействие.
  • После достижения границы срабатывания пользователь получает уведомление в виде виброотклика, и жест переходит в состояние Ожидание.
  • Если RefreshContainer является Flickable или наследуется от него, а жест перетаскивания Flickable активен, и пользователь перетащил Flickable содержимое в его границы, жест переходит в состояние Отслеживание.

  

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

• Ожидание — когда пользователь переместил точку касания вниз до границы срабатывания или дальше.

  • Если пользователь перемещает точку касания обратно за границу триггера, не отпуская ее, жест возвращается в состояние Взаимодействие.
  • Если пользователь отпускает точку касания, запускается процесс обновления, и жест переходит в состояние Обновление.

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

• Обновление — когда пользователь отпускает точку касания на границе срабатывания или ниже. При переходе в это состояние вызывается функция обратного вызова refreshHandler. Функция refreshHandler должна запустить процесс обновления содержимого. После завершения процесса обновления следует вызвать refreshCompleted или refreshCompletedCustom, чтобы завершить визуализацию процесса обновления и, по желанию, отобразить пользователю результирующий статус обновления.

  • После завершения процесса обновления следует вызвать refreshCompleted или refreshCompletedCustom, чтобы завершить визуализацию процесса обновления и, по желанию, отобразить пользователю результирующий статус обновления.
  • Если вызывается refreshCompletedCustom с пустым источником иконок и сообщением о состоянии, жест переходит в состояние Бездействие.

  

  Визуально отображается только информационный блок. В этом блоке отображается индикатор обновления.

• Отображение состояния обновления — когда обновление завершено, отображается результирующий статус обновления. Жест автоматически переходит из этого состояния в состояние Бездействие через 2 секунды.

  

  Визуально отображается только информационный блок. Этот блок может отображать иконку, текст или иконку и текст, информируя пользователя о состоянии обновления.

• Отслеживание — когда RefreshContainer является Flickable или наследуется от него, а жест перетаскивания Flickable активен, и содержимое не перетаскивается вниз за границу Flickable.

  • Если пользователь отпустит точку касания, находясь в этом состоянии, жест перейдет в состояние Бездействие.
  • Если пользователь перетаскивает Flickable содержимое вниз за границу, жест переходит в состояние Взаимодействие.

Примечание. Для Flickable и элементов, наследующих от него, если для Flickable::boundsBehavior установлено значение Flickable.DragOverBounds или Flickable. DragAndOvershootBounds, жест Pull-to-refresh активируется при перемещении содержимого вниз за границу данного элемента и деактивируется при перемещении содержимого вверх за границу данного элемента.

Настройка пользовательского интерфейса

Можно изменить следующие элементы пользовательского интерфейса:

• Текст описания — текст, отображаемый в информационном блоке во время состояний Взаимодействие и Ожидание. Текст описания по умолчанию — «Потяните для обновления». Его можно изменить с помощью прикреплённого свойства description.

• Индикатор обновления — индикатор, отображаемый в состоянии Обновление. Его можно изменить, указав компонент пользовательского индикатора обновления в свойстве view.refreshIndicator. Высота и ширина пользовательского индикатора обновления ограничены величиной Theme.iconSizeSmall.

• Статус обновления — статус обновления, отображаемый в состоянии Отображение статуса обновления. Могут быть показаны:

  • Состояние по умолчанию «Обновлено», если вызвать refreshCompleted без указания параметра success или передать значение true для параметра success.
  • Вызов refreshCompleted со значением false для параметра success по умолчанию означает статус "Обновление не удалось".
  • Значок состояния, если вызвать refreshCompletedCustom и указать путь к значку и пустой текст сообщения.
  • Текст состояния, если вызвать refreshCompletedCustom и указать пустой путь к иконке и тексту сообщения.
  • Значок состояния и текст, если вызвать refreshCompletedCustom с указанием пути к значку и тексту сообщения.
  • Отображение статуса обновления можно пропустить, если вызвать refreshCompletedCustom и указать пустой путь к иконке и пустое сообщение.

  Высота и ширина пользовательской иконки ограничиваются параметром Theme.iconSizeSmall.

Интеграция жестов

Базовые позиционирующие элементы (Column, Row, Flow и Grid) и все остальные визуальные элементы поддерживают жест pull-to-refresh с помощью прикреплённого свойства PullToRefresh. Чтобы добавить поддержку жестов к элементу, необходимо указать функцию обратного вызова refreshHandler. Чтобы скрыть индикатор обновления после завершения обновления и, по желанию, отобразить результирующий статус обновления, необходимо вызвать refreshCompleted или refreshCompletedCustom.

Следующий пример кода демонстрирует интеграцию Pull-to-refresh в ListView:

import QtQuick 2.0
import Sailfish.Silica 1.0
import Aurora.Controls 1.0

ApplicationWindow {
    initialPage: Component {
        Page {
            allowedOrientations: Orientation.All

            Timer {
                id: refreshDelayTimer

                onTriggered: listView.PullToRefresh.refreshCompleted()
                interval: 2000
            }

            ListView {
                id: listView

                anchors.fill: parent
                model: 100
                delegate: Text { width: parent.width; text: index; horizontalAlignment: Text.AlignHCenter}
                PullToRefresh.refreshHandler: refreshDelayTimer.start
            }
        }
    }
}

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

Примечание. Если вызывается refreshHandler, важно вызвать refreshCompleted или refreshCompletedCustom, когда обновление будет завершено. В противном случае жест останется в состоянии Обновление.

Описание прикрепляемых свойств

PullToRefresh.description : string

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

Если значение description пустое (значение по умолчанию), то при выполнении жеста отображается текст описания жеста по умолчанию.

PullToRefresh.enabled : bool

Это прикрепляемое свойство определяет, включен ли жест Pull-to-refresh. Значение по умолчанию: true.

PullToRefresh.refreshHandler : var

Это прикрепляемое свойство содержит функцию, которая вызывается для запуска обновления. Установка refreshHandler в null имеет тот же эффект, что и отключение жеста путем установки enabled в false.

Примечание. refreshCompleted или refreshCompletedCustom должны быть вызваны после завершения обновления. Дополнительные сведения см. в разделе Состояния жестов.

PullToRefresh.view.refreshIndicator : Component

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

Если view::refreshIndicator имеет значение null (значение по умолчанию), то для информирования пользователя о выполнении обновления отображается индикатор обновления по умолчанию.

Описание прикрепляемых методов

void fireRefresh()

Вызывает функцию refreshHandler и переводит PullToRefresh в состояние Обновление. Дополнительные сведения см. в разделе Состояния жестов.

Если обновление уже выполняется, или жест отключён через свойство enabled, или refreshHandler имеет значение null, ничего не происходит.

void refreshCompleted(bool success)

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

Если success равен true или не указан, пользователю отображается статус обновления жеста по умолчанию "Обновлено". В противном случае, если success равен false, пользователю будет показан стандартный статус обновления жеста "Произошла ошибка".

void refreshCompletedCustom(string iconSource, string message)

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

Параметры iconSource и message являются необязательными. Возможны следующие комбинации:

• iconSource и message указаны и не являются пустыми — будет показано соответствующее сообщение с иконкой.
• Если указан iconSource, а message не указан или пуст — будет показана соответствующая иконка без текста.
• iconSource и message указаны, а iconSource пуст — будет отображено соответствующее сообщение без иконки.
• Оба, iconSource и message не указаны или пусты — индикатор обновления будет скрыт без отображения результирующего статуса обновления.