Lägga till åtgärder

Att lära oss mer om åtgärder i Kirigami hjälper oss att göra vårt program användbarare.

About Kirigami API documentation: use https://api-staging.kde.org/kirigami-index.html for now

Click here to read more

We are aware of issues involving broken links to Kirigami API documentation. We are currently working on a better website to address these issues, porting the API docs where possible.

In its current state, the staging API website under development for Kirigami can be used to access all relevant Kirigami API pages, and it should already work better than the previous API website. You can access the staging API website through https://api-staging.kde.org/kirigami-index.html.

If you'd like to assist us in our efforts to port the API documentation, take a look at our Port API documentation to QDoc metatask.

Sammanfattning

Hittills har vi lyckats bygga ett enkelt program som kan visa kort. Vi har dock inte ännu något sätt att lägga till nya kort i kortvyn.

I den här handledningen tar vi en titt på åtgärder i Kirigami. De hjälper oss att lägga till interaktivitet i vårt program på ett konsekvent, snabbt och tillgängligt sätt.

Åtgärder

En Kirigami.Action inkapslar en åtgärd i ett användargränssnitt. Vi kan använda dem för att tillhandahålla åtgärder i våra program som är enkla att nå och är grundläggande för deras funktion.

Om du har använt Kirigami-program tidigare, har du med säkerhet interagerat med Kirigiami åtgärder. På den här bilden kan vi se åtgärder till höger om sidans titel med olika ikoner. Åtgärder i Kirigami kan visas på flera olika sätt och kan göra ett stort antal saker.

Lägga till nedräknare

Ett nedräkningsprogram är ganska oanvändbart utan möjlighet att lägga till nedräknare. Låt oss skapa en åtgärd som låter oss göra det.

pageStack.initialPage: Kirigami.ScrollablePage {
    // Andra sidegenskaper...
    actions: [
        Kirigami.Action {
            id: addAction
            icon.name: "list-add-symbolic"
            text: i18nc("@action:button", "Add kountdown")
            onTriggered: kountdownModel.append({
                name: "Kirigami Action added card!",
                description: "Congratulations, your Kirigami Action works!",
                date: 1000
            })
        }
    ]
    // ...
}

Vi placerar vår Kirigami.Action på vår huvudsida från de tidigare handledningarna. Om vi ville kunde vi lägga till fler åtgärder på vår sida (och till och med kapsla in åtgärder i åtgärder).

De parenteser "[]" som används ovan liknar Javascript-fält, vilket innebär att man kan skicka en eller flera saker till dem, separerade med kommatecken:

// Allmänt Javascript-fält med komponenter:
variable: [ component1, component2 ]
// Skicka ett fält med Kirigami-åtgärder till QML:
actions: [ Kirigami.Action {}, Kirigami.Action {} ]

Egenskaperna id och text bör vara välkända från tidigare handledningar. Dock kan den ärvda egenskapen Action.icon vara intressant: det är ett objekt med flera egenskaper som låter dig visa vissa ikoner för dina åtgärder. Lyckligtvis är allt vi behöver göra för att använda KDE-ikoner att tillhandahålla namnegenskapen i icon-egenskapen, icon.name.

Visa tillgängliga ikoner

Klicka här för att se hur du kontrollerar tillgängliga ikoner på systemet

Cuttlefish är ett KDE-program som låter dig visa alla ikoner som du kan använda i ditt program. Det erbjuder ett antal användbara funktioner, såsom förhandsgranskningar av deras utseenden över olika installerade teman, förhandsgranskningar vid olika storlekar, med mera. Det kan vara ett användbart verktyg när du ska bestämma dig för vilka ikoner du vill använda i ditt program.

Många av KDE:s ikoner följer FreeDesktop specifikation för namngivning av ikoner. Därför kan det också vara nyttigt att konsultera FreeDesktop-projektets webbplats, som listar alla kompatibla ikonnamn för olika skrivbord.

Egenskapen onTriggered är den viktigaste. Det är vad vår åtgärd gör när den används. Du märker att i vårt exempel använder vi metoden kountdownModel.append från kountdownModel som vi skapade i vår föregående handledning. Metoden låter oss lägga till ett nytt element i vår listmodell. Vi tillhandahåller den med ett objekt (angivet av klammerparenteser {}) som har relevanta egenskaper för våra nedräknare (name, description, och ett platsmarkerande date).

Varje gång vi nu klickar på vår knapp "Add Kountdown" längst upp till höger, läggs vår egna nedräknare till

Global låda

Nästa komponent är en Kirigami.GlobalDrawer. Den visas som en hamburgermeny. Normalt öppnar den ett sidofält, vilket är särskilt användbart på en mobil, eftersom användaren bara kan svepa in på en sida av skärmen för att öppna den. Globala lådor är användbara för global navigering och handlingar. Vi skapar en enkel global låda som innehåller knappen "avsluta".

Kirigami.ApplicationWindow {
    id: root
    // Andra fönsteregenskaper...
    globalDrawer: Kirigami.GlobalDrawer {
        isMenu: true
        actions: [
            Kirigami.Action {
                text: i18n("Quit")
                icon.name: "application-exit-symbolic"
                shortcut: StandardKey.Quit
                onTriggered: Qt.quit()
            }
        ]
    }
    // ...
}

Här placerar vi vår globala låda inne i programfönstret. Huvudegenskapen som vi måste ta hänsyn till är GlobalDrawer.actions, som har formen av ett fält av Kirigami.Action komponenter. Åtgärden har en lämplig ikon och kör funktionen Qt.quit() när den används, som stänger programmet.

Eftersom vi håller vår globala låda enkel för tillfället, ställer vi in egenskapen GlobalDrawer.isMenu till true. Det visar vår globala låda som en normal programmeny, vilket upptar mindre utrymme än den normala rutan för globala lådor.

Tips

Sidan Actions based components i den här dokumentationen ger ytterligare information om Kirigami åtgärder och hur de kan användas.

Åtgärder är sammanhangsberoende

Kirigami-komponenter är konstruerade på ett sådant sätt att platsen där man placerar Kirigami Actions är relevant. Som framgår ovan, om man lägger till åtgärder på en Kirigami.Page, Kirigami.ScrollablePage eller någon annan härledd sidkomponent, dyker de upp på höger sida om rubriken i skrivbordsläge och längst ner i mobilläge.

På liknande sätt, om Kirigami Actions läggs till i en Kirigami.GlobalDrawer, dyker de upp i den resulterande lådan eller menyn.

Andra exempel på Kirigami Actions som visas olika beroende på överliggande komponent är:

Bland andra komponenterna i Kirigami.

Vårt program så långt

Main.qml:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 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
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    id: root

    width: 400
    height: 300

    title: i18nc("@title:window", "Day Kountdown")

    // Global drawer element with app-wide actions
    globalDrawer: Kirigami.GlobalDrawer {
        // Makes drawer a small menu rather than sliding pane
        isMenu: true
        actions: [
            Kirigami.Action {
                text: i18n("Quit")
                icon.name: "application-exit-symbolic"
                shortcut: StandardKey.Quit
                onTriggered: Qt.quit()
            }
        ]
    }

    ListModel {
        id: kountdownModel
        ListElement {
            name: "Dog birthday!!"
            description: "Big doggo birthday blowout."
            date: 100
        }
    }

    Component {
        id: kountdownDelegate
        Kirigami.AbstractCard {
            contentItem: Item {
                implicitWidth: delegateLayout.implicitWidth
                implicitHeight: delegateLayout.implicitHeight
                GridLayout {
                    id: delegateLayout
                    anchors {
                        left: parent.left
                        top: parent.top
                        right: parent.right
                    }
                    rowSpacing: Kirigami.Units.largeSpacing
                    columnSpacing: Kirigami.Units.largeSpacing
                    columns: root.wideScreen ? 4 : 2

                    Kirigami.Heading {
                        Layout.fillHeight: true
                        level: 1
                        text: date
                    }

                    ColumnLayout {
                        Kirigami.Heading {
                            Layout.fillWidth: true
                            level: 2
                            text: name
                        }
                        Kirigami.Separator {
                            Layout.fillWidth: true
                            visible: description.length > 0
                        }
                        Controls.Label {
                            Layout.fillWidth: true
                            wrapMode: Text.WordWrap
                            text: description
                            visible: description.length > 0
                        }
                    }
                    Controls.Button {
                        Layout.alignment: Qt.AlignRight
                        Layout.columnSpan: 2
                        text: i18n("Edit")
                    }
                }
            }
        }
    }

    pageStack.initialPage: Kirigami.ScrollablePage {
        title: i18nc("@title", "Kountdown")

        // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
        actions: [
            Kirigami.Action {
                id: addAction
                // Name of icon associated with the action
                icon.name: "list-add-symbolic"
                // Action text, i18n function returns translated string
                text: i18nc("@action:button", "Add kountdown")
                // What to do when triggering the action
                onTriggered: kountdownModel.append({
                    name: "Kirigami Action added card!",
                    description: "Congratulations, your Kirigami Action works!",
                    date: 1000
                })
            }
        ]

        Kirigami.CardsListView {
            id: cardsView
            model: kountdownModel
            delegate: kountdownDelegate
        }
    }
}

Layouter, listvyer och kort

Lägga till en dialogruta