Модели и представления в Qt Quick

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

• Модель - содержит данные и их структуру. Существует несколько типов QML для создания моделей.
• Представление - контейнер, отображающий данные. Представление может отображать данные в списке или сетке.
• Делегат - диктует, как данные должны отображаться в представлении. Делегат берет каждый элемент данных из модели и инкапсулирует его. Данные доступны через делегат. Делегат также может записывать данные обратно в изменяемые модели (например, в обработчике onAccepted в TextField).

Для визуализации данных свяжите свойство представления model с моделью, а свойство delegate - с компонентом или другим совместимым типом.

Отображение данных с помощью представлений

Представления являются контейнерами для наборов элементов. Они обладают богатым функционалом и могут быть настраиваемы для соответствия требованиям стиля или поведения.

Набор стандартных представлений предоставляется в базовом наборе графических типов Qt Quick:

• ListView - организует элементы в горизонтальный или вертикальный список
• GridView - организует элементы в сетку в доступном пространстве
• PathView - организует элементы на траектории

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

Декорирование представлений

Представления позволяют визуально настраивать свойства декорации, такие как header, footer, и section свойства. Связывая объект, обычно другой визуальный объект, с этими свойствами, представления становятся декорируемыми. Подвал может содержать тип Rectangle, отображающий границы, или заголовок, отображающий логотип сверху списка.

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

ListModel {
    id: nameModel
    ListElement { name: "Alice" }
    ListElement { name: "Bob" }
    ListElement { name: "Jane" }
    ListElement { name: "Harry" }
    ListElement { name: "Wendy" }
}
Component {
    id: nameDelegate
    Text {
        text: name;
        font.pixelSize: 24
    }
}

Клуб может декорировать список членов, связав визуальные объекты со свойствами header и footer. Визуальный объект может быть определен в строке, в другом файле или в типе Component.

ListView {
    anchors.fill: parent
    clip: true
    model: nameModel
    delegate: nameDelegate
    header: bannercomponent
    footer: Rectangle {
        width: parent.width; height: 30;
        gradient: clubcolors
    }
    highlight: Rectangle {
        width: parent.width
        color: "lightgray"
    }
}

Component {     //instantiated when header is processed
    id: bannercomponent
    Rectangle {
        id: banner
        width: parent.width; height: 50
        gradient: clubcolors
        border {color: "#9EDDF2"; width: 2}
        Text {
            anchors.centerIn: parent
            text: "Club Members"
            font.pixelSize: 32
        }
    }
}
Gradient {
    id: clubcolors
    GradientStop { position: 0.0; color: "#8EE2FE"}
    GradientStop { position: 0.66; color: "#7ED2EE"}
}

Обработка мыши и касаний

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

Обратите внимание, что если highlightRangeMode установлено в StrictlyEnforceRange, currentIndex будет изменяться при перетаскивании/прокрутке представления, так как представление всегда гарантирует, что currentIndex находится в пределах диапазона выделения, заданного для него.

Разделы ListView

ListView может содержать элементы, сгруппированные в разделы, где связанные элементы списка маркируются в соответствии с их разделами. Кроме того, разделы можно декорировать делегатами.

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

ListModel {
    id: nameModel
    ListElement { name: "Alice"; team: "Crypto" }
    ListElement { name: "Bob"; team: "Crypto" }
    ListElement { name: "Jane"; team: "QA" }
    ListElement { name: "Victor"; team: "QA" }
    ListElement { name: "Wendy"; team: "Graphics" }
}
Component {
    id: nameDelegate
    Text {
        text: name;
        font.pixelSize: 24
        anchors.left: parent.left
        anchors.leftMargin: 2
    }
}

Тип ListView имеет section прикрепленное свойство, которое может объединять смежные и связанные типы в раздел. section.property определяет, какое свойство типа списка использовать в качестве разделов. section.criteria может диктовать, как отображать имена разделов, а section.delegate аналогично свойству представления delegate.

ListView {
    anchors.fill: parent
    model: nameModel
    delegate: nameDelegate
    focus: true
    highlight: Rectangle {
        color: "lightblue"
        width: parent.width
    }
    section {
        property: "team"
        criteria: ViewSection.FullString
        delegate: Rectangle {
            color: "#b0dfb0"
            width: parent.width
            height: childrenRect.height + 4
            Text { anchors.horizontalCenter: parent.horizontalCenter
                font.pixelSize: 16
                font.bold: true
                text: section
            }
        }
    }
}

Делегаты представлений

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

Component {
    id: petdelegate
    Text {
        id: label
        font.pixelSize: 24
        text: index === 0 ? type + " (default)" : type

        required property int index
        required property string type
    }
}

Доступ к представлениям и моделям из делегатов

Представление списка, к которому привязан делегат, доступно из делегата через свойство ListView.view. Аналогично, GridView.view GridView доступен делегатам. Соответствующая модель и ее свойства доступны через ListView.view.model. Кроме того, все определенные сигналы или методы в модели также доступны.

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

В следующем примере делегат показывает свойство language модели, а цвет одного из полей зависит от свойства fruit_color представления.

Rectangle {
     width: 200; height: 200

    ListModel {
        id: fruitModel
        property string language: "en"
        ListElement {
            name: "Apple"
            cost: 2.45
        }
        ListElement {
            name: "Orange"
            cost: 3.25
        }
        ListElement {
            name: "Banana"
            cost: 1.95
        }
    }

    Component {
        id: fruitDelegate
        Row {
                id: fruit
                Text { text: " Fruit: " + name; color: fruit.ListView.view.fruit_color }
                Text { text: " Cost: $" + cost }
                Text { text: " Language: " + fruit.ListView.view.model.language }
        }
    }

    ListView {
        property color fruit_color: "green"
        model: fruitModel
        delegate: fruitDelegate
        anchors.fill: parent
    }
}

Модели

Данные предоставляются делегату через именованные роли данных, к которым делегат может привязываться. Вот ListModel с двумя ролями, type и age, и ListView с делегатом, который привязывается к этим ролям для отображения их значений:

import QtQuick 2.0

Item {
    width: 200; height: 250

    ListModel {
        id: myModel
        ListElement { type: "Dog"; age: 8 }
        ListElement { type: "Cat"; age: 5 }
    }

    Component {
        id: myDelegate
        Text { text: type + ", " + age }
    }

    ListView {
        anchors.fill: parent
        model: myModel
        delegate: myDelegate
    }
}

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

import QtQuick 2.0

Item {
    width: 200
    height: 250

    ListModel {
        id: myModel
        ListElement { type: "Dog"; age: 8; noise: "meow" }
        ListElement { type: "Cat"; age: 5; noise: "woof" }
    }

    component MyDelegate : Text {
        required property string type
        required property int age
        text: type + ", " + age
        // WRONG: Component.onCompleted: () => console.log(noise)
        // The above line would cause a ReferenceError
        // as there is no required property noise,
        // and the presence of the required properties prevents
        // noise from being injected into the scope
    }

    ListView {
        anchors.fill: parent
        model: myModel
        delegate: MyDelegate {}
    }
}

Если между свойствами модели и свойствами делегата возникает конфликт имен, к ролям можно получить доступ с использованием квалифицированного имени model. Например, если у типа Text были свойства type или age, текст в приведенном выше примере будет отображать значения этих свойств вместо значений type и age из элемента модели. В этом случае к свойствам можно было бы обратиться как model.type и model.age, чтобы гарантировать, что делегат отображает значения свойств из элемента модели.

Также доступна специальная роль index, содержащая индекс элемента в модели. Обратите внимание, что этот индекс устанавливается в -1, если элемент удаляется из модели. Если вы привязываетесь к роли index, убедитесь, что логика учитывает возможность того, что index равен -1, т. е. что элемент больше не действителен. (Обычно элемент вскоре будет уничтожен, но возможно отложить уничтожение делегата в некоторых представлениях с помощью прикрепленного свойства delayRemove.)

Модели, которые не имеют именованных ролей (например, ListModel, показанный ниже), будут предоставлять данные через роль modelData. Роль modelData также предоставляется для моделей, которые имеют только одну роль. В этом случае роль modelData содержит те же данные, что и именованная роль.

Примечание: роли model, index и modelData недоступны, если делегат содержит обязательные свойства, если только у него также нет обязательных свойств с совпадающими именами.

QML предоставляет несколько типов моделей данных среди встроенного набора типов QML. Кроме того, модели могут быть созданы с помощью Qt C++ и затем предоставлены QQmlEngine для использования компонентами QML. Для получения информации о создании этих моделей посетите статьи Использование моделей C++ с представлениями Qt Quick и создание типов QML.

Расположение элементов из модели может быть достигнуто с помощью Repeater.

Модель списка

ListModel - это простая иерархия типов, определенная в QML. Доступные роли определяются свойствами ListElement.

ListModel {
    id: fruitModel

    ListElement {
        name: "Apple"
        cost: 2.45
    }
    ListElement {
        name: "Orange"
        cost: 3.25
    }
    ListElement {
        name: "Banana"
        cost: 1.95
    }
}

У этой модели есть две роли, name и cost. К ним можно привязаться, например, делегатом ListView:

ListView {
    anchors.fill: parent
    model: fruitModel
    delegate: Row {
        Text { text: "Fruit: " + name }
        Text { text: "Cost: $" + cost }
    }
}

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

ListModel { id: fruitModel }
    ...
MouseArea {
    anchors.fill: parent
    onClicked: fruitModel.append({"cost": 5.95, "name":"Pizza"})
}

При нажатии на MouseArea, fruitModel будет иметь две роли, cost и name. Даже если последующие роли будут добавлены, только первые две будут обрабатываться представлениями, использующими модель. Для сброса доступных ролей в модели вызовите ListModel::clear().

Модель объекта

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

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

import QtQuick 2.0
import QtQml.Models 2.1

Rectangle {
    ObjectModel {
        id: itemModel
        Rectangle { height: 30; width: 80; color: "red" }
        Rectangle { height: 30; width: 80; color: "green" }
        Rectangle { height: 30; width: 80; color: "blue" }
    }

    ListView {
        anchors.fill: parent
        model: itemModel
    }
}

Целые числа как модели

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

В следующем примере создается ListView с пятью элементами:

Item {
    width: 200; height: 250

    Component {
        id: itemDelegate
        Text { text: "I am item number: " + index }
    }

    ListView {
        anchors.fill: parent
        model: 5
        delegate: itemDelegate
    }

}

Примечание: ограничение на количество элементов в модели целого числа составляет 100 000 000.

Экземпляры объектов как модели

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

В приведенном ниже примере создается список с одним элементом, отображающим цвет текста myText. Обратите внимание на использование полностью квалифицированного свойства model.color для предотвращения конфликта со свойством color типа Text в делегате.

Rectangle {
    width: 200; height: 250

    Text {
        id: myText
        text: "Hello"
        color: "#dd44ee"
    }

    Component {
        id: myDelegate
        Text { text: model.color }
    }

    ListView {
        anchors.fill: parent
        anchors.topMargin: 30
        model: myText
        delegate: myDelegate
    }
}

C++ Модели данных

Модели могут быть определены в C++ и затем доступны для QML. Этот механизм полезен для экспонирования существующих моделей данных C++ или других сложных наборов данных в QML.

Для получения дополнительной информации посетите статью Использование C++ моделей с виджетами Qt Quick.

Повторители

Повторители создают элементы из шаблона для использования с позиционерами, используя данные из модели. Объединение повторителей и позиционеров — простой способ выложить множество элементов. Элемент Repeater размещается внутри позиционера и генерирует элементы, которые позиционер организует.

Каждый Repeater создает определенное количество элементов, комбинируя каждый элемент данных из модели, указанной с помощью свойства model, с шаблоном элемента, определенным как дочерний элемент внутри Repeater. Общее количество элементов определяется объемом данных в модели.

Следующий пример демонстрирует повторитель, используемый с элементом Grid для организации набора элементов Rectangle. Элемент Repeater создает серию из 24 прямоугольников для размещения элементом Grid в 5×5 сетке.

import QtQuick 2.0

Rectangle {
    width: 400; height: 400; color: "black"

    Grid {
        x: 5; y: 5
        rows: 5; columns: 5; spacing: 10

        Repeater { model: 24
                   Rectangle { width: 70; height: 70
                               color: "lightgreen"

                               Text { text: index
                                      font.pointSize: 30
                                      anchors.centerIn: parent } }
        }
    }
}

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

Дополнительную информацию см. в документе QML Модели данных.

Если модель представляет собой список строк, делегат также получает доступ к свойству только для чтения modelData , которое содержит строку. Например:

Column {
    Repeater {
        model: ["apples", "oranges", "pears"]
        Text { text: "Data: " + modelData }
    }
}

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

Изменение данных модели

Для изменения данных модели можно назначить обновленные значения свойствам model. QML ListModel по умолчанию редактируется, в то время как модели C++ должны реализовывать setData(), чтобы стать редактируемыми. Целочисленные и массивы JavaScript моделей являются только для чтения.

Предположим, модель C++ на основе QAbstractItemModel, реализующая метод setData, зарегистрирована как тип QML под названием EditableModel. Данные можно записать в модель следующим образом:

ListView {
    anchors.fill: parent
    model: EditableModel {}
    delegate: TextEdit {
        width: ListView.view.width
        height: 30
        text: model.edit
        Keys.onReturnPressed: model.edit = text
    }
}

Примечание: Роль edit равна Qt::EditRole. См. roleNames() для встроенных имен ролей. Однако, в реальных моделях обычно используются пользовательские роли.

Примечание: Если роль модели связана с обязательным свойством, присвоение этому свойству не изменит модель. Вместо этого это разорвет связь с моделью (точно так же, как присвоение любому другому свойству разрывает существующие связи). Если вы хотите использовать обязательные свойства и изменять данные модели, сделайте модель также обязательным свойством и присвойте значение model.propertyName.

Для получения дополнительной информации посетите статью Использование C++ моделей с Qt Quick Views.

Использование переходов

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

Переходы для добавления элементов применяются к элементам, которые создаются как часть позиционера, а также к тем, которые переродились, став дочерними элементами позиционера.

Переходы для удаления элементов применяются к элементам внутри позиционера, которые удаляются, а также к тем, которые удаляются из позиционера и получают новых родителей в документе.

Примечание: Изменение непрозрачности элементов на ноль не приведет к их исчезновению из позиционера. Их можно удалить и добавить заново, изменив свойство visible.