components-card.md 8.27 KB
Newer Older
1
2
---
title: Cards
3
weight: 104
4
group: "components"
5
6
description: >
  A card serves as overview and an entry point for more detailed information and can offer direct access to the most important actions on an item.
7
8
aliases:
  - /docs/kirigami/components-card/
9
10
---

11
The Kirigami types [`Kirigami.AbstractCard`](docs:kirigami2;org::kde::kirigami::AbstractCard) and [`Kirigami.Card`](docs:kirigami2;org::kde::kirigami::Card) are used to implement the popular card component used on many mobile and web platforms. Cards can be used to display a collection of information or actions in an attractive and distinctive way.
12

13
Kirigami also offers 3 kinds of views and positioners to aid you in presenting your cards with beautiful and responsive layouts.
14
15
16

## AbstractCard

17
A [`Kirigami.AbstractCard`](docs:kirigami2;Card) is the simplest type of card. It's just a rectangle with a shadow, which can contain any `Item` in it. It can also have items assigned to its `header` or `footer` properties. In this case a [`Kirigami.Heading`](docs:kirigami2;Heading) is its header and a [`Controls.Label`](docs:qtquickcontrols;QtQuick.Controls.Label) with `wrapMode` set to `Text.WordWrap` is the card's `contentItem`.
18
19

{{< sections >}}
Carl Schwan's avatar
Carl Schwan committed
20

21
{{< section-left >}}
Carl Schwan's avatar
Carl Schwan committed
22

23
24
25
26
27
28
29
30
31
32
33
34
35
```qml
Kirigami.AbstractCard {
    Layout.fillHeight: true
    header: Kirigami.Heading {
        text: qsTr("AbstractCard")
        level: 2
    }
    contentItem: Controls.Label {
        wrapMode: Text.WordWrap
        text: "..."
    }
}
```
Carl Schwan's avatar
Carl Schwan committed
36

37
38
39
{{< /section-left >}}

{{< section-right >}}
Carl Schwan's avatar
Carl Schwan committed
40

Carl Schwan's avatar
Carl Schwan committed
41
![Screenshot of an Abstract Card](/docs/use/kirigami/components-card/abstract-card.png)
Carl Schwan's avatar
Carl Schwan committed
42

43
{{< /section-right >}}
Carl Schwan's avatar
Carl Schwan committed
44

45
46
47
48
49
{{< /sections >}}


## Card

50
A [`Kirigami.Card`](docs:kirigami2;Card) inherits from [`Kirigami.AbstractCard`](docs:kirigami2;AbstractCard) and provides more features out of the box. A card has a header composed of a `banner` and a footer composed of [`Kirigami.Action`](docs:kirigami2;Action) objects alongside its main content.
51
52

{{< sections >}}
Carl Schwan's avatar
Carl Schwan committed
53

54
{{< section-left >}}
Carl Schwan's avatar
Carl Schwan committed
55

56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
```qml
Kirigami.Card {
    actions: [
        Kirigami.Action {
            text: qsTr("Action1")
            icon.name: "add-placemark"
        },
        Kirigami.Action {
            text: qsTr("Action2")
            icon.name: "address-book-new-symbolic"
        },
        // ...
    ]
    banner {
        source: "../banner.jpg"
        title: "Title Alignment"
        // The title can be positioned in the banner
        titleAlignment: Qt.AlignLeft | Qt.AlignBottom
    }
    contentItem: Controls.Label {
        wrapMode: Text.WordWrap
        text: "My Text"
    }
}

```
Carl Schwan's avatar
Carl Schwan committed
82

83
84
85
{{< /section-left >}}

{{< section-right >}}
Carl Schwan's avatar
Carl Schwan committed
86

Carl Schwan's avatar
Carl Schwan committed
87
![](/docs/use/kirigami/components-card/card1.png)
Carl Schwan's avatar
Carl Schwan committed
88

89
{{< /section-right >}}
Carl Schwan's avatar
Carl Schwan committed
90

91
92
93
94
{{< /sections >}}

## CardsLayout

95
96
97
98
99
A [`Kirigami.CardsLayout`](docs:kirigami2;CardsLayout) is most useful when the cards being presented are not instantiated by a model or by a model which always has very few items. They are presented as a grid of two columns which will remain centered if the application is really wide, or become a single column if there is not enough space for two columns, such as a mobile phone screen.

{{< alert title="Note" color="info" >}}
[`Kirigami.CardsListView`](docs:kirigami2;CardsListView) or [`Kirigami.CardsGridView`](docs:kirigami2;CardsGridView) are better suited for larger models.
{{< /alert >}}
100

101
**A CardsLayout should always be contained within a ColumnLayout.**
102

103
A card can optionally be oriented horizontally. In this case it will be wider than tall, and is better suited to being placed in a ColumnLayout. If you must put it in a CardsLayout, it will have a columnSpan of 2 by default.
104
105

{{< sections >}}
Carl Schwan's avatar
Carl Schwan committed
106

107
{{< section-left >}}
Carl Schwan's avatar
Carl Schwan committed
108

109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
```qml
ColumnLayout {
    Kirigami.CardsLayout {
        Kirigami.Card {
            contentItem: Controls.Label {
                wrapMode: Text.WordWrap
                text: "My Text2"
            }
        }
        Kirigami.AbstractCard { 
            contentItem: Controls.Label {
                wrapMode: Text.WordWrap
                text: "My Text"
            }
        }
        Kirigami.Card {
            headerOrientation: Qt.Horizontal
            contentItem: Controls.Label {
                wrapMode: Text.WordWrap
                text: "My Text2"
            }
        }
    }
}
```
{{< /section-left >}}

{{< section-right >}}
Carl Schwan's avatar
Carl Schwan committed
137

Carl Schwan's avatar
Carl Schwan committed
138
![Screenshot of a CardsLayout](/docs/use/kirigami/components-card/cardslayout.png)
Carl Schwan's avatar
Carl Schwan committed
139

140
{{< /section-right >}}
Carl Schwan's avatar
Carl Schwan committed
141

142
143
144
145
{{< /sections >}}

## CardsListView

146
A [`Kirigami.CardsListView`](docs:kirigami2;CardsListView) is a list view that can be used with [`Kirigami.AbstractCard`](docs:kirigami2;AbstractCard) components.
147

148
A `Kirigami.CardsListView` will stretch child cards to its own width. This component should therefore only be used with cards which will look good at any horizontal size. Using a `Kirigami.CardsListView` the `Kirigami.Card` component is discouraged, unless it has `Qt.Horizontal` as its `headerOrientation` property.
149

150
The choice between using this view with `Kirigami.AbstractCard` components or a conventional `ListView` with [`AbstractListItem`](docs:kirigami2;AbstractListItem)/[BasicListItem](docs:kirigami2;BasicListItem) components is purely an aesthetic one.
151
152

{{< sections >}}
Carl Schwan's avatar
Carl Schwan committed
153

154
{{< section-left >}}
Carl Schwan's avatar
Carl Schwan committed
155

156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
```qml
Kirigami.CardsListView {
    id: view
    model: 100

    delegate: Kirigami.AbstractCard {
        //NOTE: never put a Layout as contentItem as it will cause binding loops
        contentItem: Item {
            implicitWidth: delegateLayout.implicitWidth
            implicitHeight: delegateLayout.implicitHeight
            GridLayout {
                id: delegateLayout
                anchors {
                    left: parent.left
                    top: parent.top
                    right: parent.right
                    //IMPORTANT: never put the bottom margin
                }
                rowSpacing: Kirigami.Units.largeSpacing
                columnSpacing: Kirigami.Units.largeSpacing
                columns: width > Kirigami.Units.gridUnit * 20 ? 4 : 2
                Kirigami.Icon {
                    source: "applications-graphics"
                    Layout.fillHeight: true
                    Layout.maximumHeight: Kirigami.Units.iconSizes.huge
                    Layout.preferredWidth: height
                }
                Kirigami.Heading {
                    level: 2
                    text: qsTr("Product ")+ modelData
                }
                Controls.Button {
                    Layout.alignment: Qt.AlignRight
                    Layout.columnSpan: 2 
                    text: qsTr("Install")
                }
            }
        }
    }
}
```
Carl Schwan's avatar
Carl Schwan committed
197

198
{{< /section-left >}}
Carl Schwan's avatar
Carl Schwan committed
199

200
{{< section-right >}}
Carl Schwan's avatar
Carl Schwan committed
201

Julius Künzel's avatar
Julius Künzel committed
202
![Screenshot of a CardsListView](/docs/use/kirigami/components-card/cardslistview.png)
Carl Schwan's avatar
Carl Schwan committed
203

204
{{< /section-right >}}
Carl Schwan's avatar
Carl Schwan committed
205

206
207
208
209
{{< /sections >}}

## CardsGridView

210
Use a [`Kirigami.CardsGridView`](docs:kirigami2;org::kde::kirigami::CardsGridView) to display cards in a grid.
211

212
Its behavior is the same as a `Kirigami.CardsLayout`, and it allows cards to be put in one or two columns depending on the available width.
213

214
CardsGridView has the limitation that every card must have the same exact height, so `cellHeight` must be manually set to a value for which the content must fit for every child card.
215

216
If possible use `Kirigami.CardsGridView` only when you need to instantiate many cards. If you are only going to instantiate a few cards, opt for a `Kirigami.CardsLayout` with a `Repeater` instead.
217
218

{{< sections >}}
Carl Schwan's avatar
Carl Schwan committed
219

220
{{< section-left >}}
Carl Schwan's avatar
Carl Schwan committed
221

222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
```qml
Kirigami.CardsGridView {
    id: view
    model: ListModel {
        id: mainModel
        // Model with the following roles: text,
        // actions and image
    }
    delegate:Kirigami.Card {
        id: card
        banner {
            title: model.title
            source: model.image
        }
        contentItem: Controls.Label {
            wrapMode: Text.WordWrap
            text: model.text
        }
        actions: [
            Kirigami.Action {
                text: model.actions.get(0).text
                icon.name: model.actions.get(0).icon
            },
            Kirigami.Action {
                text: model.actions.get(1).text
                icon.name: model.actions.get(1).icon
            }
        ]
    }
}

```
Carl Schwan's avatar
Carl Schwan committed
254

255
256
257
{{< /section-left >}}

{{< section-right >}}
Carl Schwan's avatar
Carl Schwan committed
258

Carl Schwan's avatar
Carl Schwan committed
259
![Screenshot of a CardsGridView](/docs/use/kirigami/components-card/cardsgridview.png)
Carl Schwan's avatar
Carl Schwan committed
260

261
{{< /section-right >}}
Carl Schwan's avatar
Carl Schwan committed
262

263
{{< /sections >}}