QML-тип DatePicker

Календарь для выбора даты. Подробнее…

Строка импорта:	`import Sailfish.Silica 1.0`
Наследуется от:	Item

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

Свойства

cellHeight : real
cellWidth : real
date : date
dateText : string
day : int
daysVisible : bool
delegate : Component
leftMargin : real
modelComponent : Component
month : int
monthYearVisible : bool
rightMargin : real
viewMoving : bool
weeksVisible : bool
year : int

Сигналы

updateModel(variant modelObject, variant fromDate, variant toDate, int primaryMonth)

Методы

showMonth(int month, int year)

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

Тип DatePicker представляет собой элемент управления (календарь) для выбора даты.

Дату, отображаемую на календаре, можно установить с помощью свойства date. Кроме того, значения отдельных составляющих дату компонентов (год, месяц и день) можно получить с помощью допускающих только чтение свойств year, month и day, соответственно.

Ниже приведён простой пример диалога для выбора даты с текущей датой, установленной на 23 ноября 2012 года:

import QtQuick 2.2
import Sailfish.Silica 1.0

DatePicker {
    date: new Date(2012, 10, 23, 12, 0, 0) // 10 = Ноябрь, в JavaScript-объектах даты индексация месяцев начинается с 0
}

Если для свойства date не задано значение, по умолчанию используется текущая дата (в зависимости от даты и времени, заданных в настройках устройства).

При выборе даты в календаре значения свойств date, year, month и day соответственным образом обновляются.

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

Использование пользовательского делегата для выбора даты

Стандартный вид календаря показывает все дни на календарной сетке, выделяя цветом текущий день, дни текущего месяца, дни смежных месяцев. Внешний вид календаря можно настроить путем изменения свойства delegate (делегата), которое отвечает за отображение каждого дня в календаре.

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

import QtQuick 2.2
import Sailfish.Silica 1.0

DatePicker {
    id: datePicker

    delegate: MouseArea {
        width: datePicker.cellWidth
        height: datePicker.cellHeight

        onClicked: datePicker.date = new Date(year, month-1, day, 12, 0, 0)   // set the selected date

        Label {
            anchors.centerIn: parent
            text: day
            color: "orange"
            font.pixelSize: month === primaryMonth ? Theme.fontSizeMedium : Theme.fontSizeExtraSmall
        }
    }
}

Следует обратить внимание, как используются роли модели "day", "year", "month" и "primaryMonth". Если пользовательский компонент модели modelComponent не задан, календарь использует модель данных по умолчанию, в которой описано несколько ролей для даты, представляемых индексом модели. Подробности в описании свойства delegate.

Использование пользовательской модели для выбора даты

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

В следующем примере в календаре задана пользовательская модель, в которой в дополнение к стандартным ролям модели описана роль праздничного дня (ключ "holiday"). Эта новая роль используется в описании делегата с тем, чтобы Католическое Рождество (25 декабря), День подарков (26 декабря) и Новый год (1 января) на календаре были показаны белым жирным шрифтом:

import QtQuick 2.2
import Sailfish.Silica 1.0

DatePicker {
    id: datePicker

    function getModelData(dateObject, primaryMonth) {
        var y = dateObject.getFullYear()
        var m = dateObject.getMonth() + 1
        var d = dateObject.getDate()
        var data = {'year': y, 'month': m, 'day': d,
                    'primaryMonth': primaryMonth,
                    'holiday': (m === 1 && d === 1) || (m === 12 && (d === 25 || d === 26))}
        return data
    }

    modelComponent: Component {
        ListModel { }
    }

    onUpdateModel: {
        var i = 0
        var dateObject = new Date(fromDate)
        while (dateObject < toDate) {
            if (i < modelObject.count) {
                modelObject.set(i, getModelData(dateObject, primaryMonth))
            } else {
                modelObject.append(getModelData(dateObject, primaryMonth))
            }
            dateObject.setDate(dateObject.getDate() + 1)
            i++
        }
    }

    delegate: MouseArea {
        width: datePicker.cellWidth
        height: datePicker.cellHeight

        onClicked: datePicker.date = new Date(year, month-1, day, 12, 0, 0)

        Label {
            anchors.centerIn: parent
            text: day
            color: holiday? "white" : "orange"
            font.bold: holiday
            font.pixelSize: month === primaryMonth ? Theme.fontSizeMedium : Theme.fontSizeExtraSmall
        }
    }
}

См. также DatePickerDialog и TimePicker.

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

cellHeight : real

Предоставляет высоту ячейки таблицы с датами (календаря). По умолчанию равно значению свойства cellWidth, в результате чего ячейки таблицы будут квадратными. В отличие от свойства cellWidth может быть изменено.

Ширина и высота пользовательских делегатов должны быть установлены равными cellWidth и cellHeight, соответственно.

См. также cellWidth.

[read-only] cellWidth : real

Предоставляет ширину ячейки таблицы с датами (календаря). Размер рассчитывается таким образом, чтобы все дни недели вписывались в ширину элемента DatePicker.

Ширина и высота пользовательских делегатов должны быть установлены равными cellWidth и cellHeight соответственно.

См. также cellHeight.

date : date

Выбранная дата в формате JavaScript-объекта даты. По умолчанию используется текущая локальная дата.

При задании значения следует обратить внимание, что в JavaScript-объектах даты нумерация месяцев начинается с нуля (т.е. допустимые значения лежат в диапазоне от 0 до 11), тогда как допустимые значения свойства month лежат в диапазоне от 1 до 12. Кроме того, ввиду использования расчётов перехода на летнее время в классе QDateTime даты до 01.01.1970 и после 31.12.2037 могут быть смещены на 1 день, если объект даты был создан без уточнения времени.

В следующем примере создаётся объект даты:

DatePicker {
    date: new Date(2000, 9, 26, 12, 0, 0)      // 9 = Октябрь, т.е. дата относится к полудню 26 октября 2000 года

    Component.onCompleted: console.log(month)  // выводит "10", так как свойство DatePicker::month находится в диапазоне 1–12
}

[read-only] dateText : string

Выбранная дата date в виде строки в формате краткой даты системы.

[read-only] day : int

Содержит значение, соответствующее дню выбранной даты в date. Данное значение находится в диапазоне от 1 до 31.

daysVisible : bool

Определяет, показываются ли дни недели над датами в календаре. Значение по умолчанию: false.

delegate : Component

Задаёт пользовательский делегат для отображения в календаре. Делегат создаётся для каждой даты в пределах видимой области календаря. В качестве примера см. раздел Использование пользовательского делегата для выбора даты.

Если свойство modelComponent не задано, этот делегат использует модель данных по умолчанию, в которой описаны следующие роли:

day — день (значения в диапазоне 1–31), представляемый индексом модели.
month — месяц (значения в диапазоне 1–12), представляемый индексом модели.
year — год (четырехзначное число), представляемое индексом модели.
primaryMonth — основной месяц, представляемый на экране в таблице какого-либо конкретного календаря (подробнее см. описание updateModel()).

Делегат должен использовать значения cellWidth и cellHeight в качестве своей ширины и высоты, соответственно.

См. также modelComponent.

leftMargin : real

Отступ между левым и правым краями календаря и его содержимым. Значение по умолчанию: Theme.horizontalPageMargin.

modelComponent : Component

Задаёт пользовательскую модель данных для отображения в календаре. Может использоваться совместно с пользовательским делегатом для описания дополнительных ролей в модели, которые могут использоваться делегатом. В качестве пример см. раздел Использование пользовательской модели для выбора даты.

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

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

[read-only] month : int

Содержит значение, соответствующее месяцу выбранной даты в date. Данное значение находится в диапазоне от 1 до 12.

monthYearVisible : bool

Определяет, показываются ли месяц и год слева от календаря. Значение по умолчанию: true.

rightMargin : real

Отступ между левым и правым краями календаря и его содержимым. Значение по умолчанию: Theme.horizontalPageMargin.

viewMoving : bool

Определяет, перемещается ли вид календаря в данный момент.

weeksVisible : bool

Определяет, показываются ли всегда номера недель. При значении true слева от календаря будет показываться столбец с номерами недель. При значении false этот столбец будет скрыт, но его можно раскрыть путём перетаскивания календаря слева направо.

По умолчанию значение свойства weeksVisible равно true для больших экранов (планшеты) и равно false для маленьких экранов (телефоны).

[read-only] year : int

Содержит значение, соответствующее году принятой даты в date. Данное значение является четырёхзначным числом.

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

updateModel(variant modelObject, variant fromDate, variant toDate, int primaryMonth)

Испускается, если компонент модели задан, и экземпляр этой пользовательской модели необходимо наполнить или обновить новым диапазоном дат. Такое происходит всякий раз при смене отображаемого на календаре месяца.

Используются следующие аргументы:

modelObject — экземпляр модели для обновления. Это экземпляр модели, заданной в свойстве modelComponent.
fromDate — начальная дата, которая будет добавлена в модель.
toDate — конечная дата, которая будет добавлена в модель.
primaryMonth — основной месяц, отображаемый на экране в таблице какого-либо конкретного календаря. На календаре отображается 6 недель с датами текущего и смежного месяцев. Поэтому значения fromDate и toDate обычно выходят за пределы первого и последнего дня месяца. Например, с помощью аргумента primaryMonth можно в описании делегата задать стиль отображения для дат, которые выходят за пределы основного месяца.

В качестве пример см. раздел Использование пользовательской модели для выбора даты.

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

showMonth(int month, int year)

Показывает на экране календарь, соответствующий указанному месяцу (параметр month) и году (параметр year).

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