Añadir acciones

Aprender más sobre las acciones de Kirigami nos ayudará a que nuestra aplicación sea más útil.

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.

Resumen

So far, we built a simple app that can display cards. However, there is currently no way for the user to add new cards to the card view.

En este tutorial, veremos las acciones de Kirigami. Estas nos ayudarán a añadir interactividad a nuestra aplicación de una manera consistente, rápida y accesible.

Acciones

Una Kirigami.Action encapsula una acción de la interfaz de usuario. Podemos usarlas para proporcionar a nuestras aplicaciones acciones de fácil acceso que son esenciales para su funcionalidad.

Si ha usado aplicaciones de Kirigami con anterioridad, ya habrá interactuado con las acciones de Kirigami. En esta imagen podemos ver acciones a la derecha del título de la página con diversos iconos. Las acciones de Kirigami se pueden mostrar de varias formas y pueden hacer una amplia variedad de cosas.

Añadir cuentas regresivas

Una aplicación de cuenta regresiva es bastante inútil sin la capacidad de añadir cuentas regresivas. Vamos a crear una acción que nos permita hacer esto.

pageStack.initialPage: Kirigami.ScrollablePage {
    // Otras propiedades de la página...
    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
            })
        }
    ]
    // ...
}

We are placing our Kirigami.Action within our main page from the previous tutorials. If we wanted to, we could add more actions to our page (and even nest actions within actions!).

The brackets [] used above are similar to JavaScript arrays, which means you can pass one or more things to them, separated by comma:

// General JavaScript array of components:
variable: [ component1, component2 ]
// Passing an array of Kirigami actions to QML:
actions: [ Kirigami.Action {}, Kirigami.Action {} ]

Las propiedades id y text deberían resultarle familiares de los tutoriales anteriores. Sin embargo, la propiedad Action.icon heredada debería ser interesante: es un objeto con varias propiedades que le permiten mostrar ciertos iconos para las acciones. Afortunadamente, para usar los iconos de KDE, todo lo que tenemos que hacer es proporcionar la propiedad del nombre para la propiedad del icono, icon.name.

Viewing the available icons

Pulse aquí para ver cómo comprobar los iconos disponibles en su sistema

Cuttlefish es una aplicación de KDE que le permite ver todos los iconos que puede usar en su aplicación. Ofrece una serie de funciones útiles, como vistas previas de su apariencia con los diferentes temas instalados, vistas previas en distintos tamaños y más. Puede que le resulte una herramienta útil a la hora de decidir los iconos que va a utilizar en su aplicación.

Muchos de los iconos de KDE siguen la especificación de denominación de iconos de FreeDesktop. Por lo tanto, también puede resultarle útil consultar el sitio web del proyecto FreeDesktop, que enumera todos los nombres de iconos compatibles con todos los escritorios.

The onTriggered signal handler is the most important. This is what our action will do when it is used. You'll notice that in our example we're using the method kountdownModel.append of the kountdownModel we created in our previous tutorial. This method lets us append a new element to our list model. We are providing it with an object (indicated by curly braces {}) that has the relevant properties for our countdowns (name, description, and a placeholder date).

Cada vez que hacemos clic en el botón «Añadir kountdown» de la parte superior derecha, se añade una cuenta atrás personalizada.

Cajón global

The next component is a Kirigami.GlobalDrawer. It shows up as a hamburger menu. By default it opens a sidebar, which is especially useful on mobile, as the user can just swipe in a side of the screen to open it. Global drawers are useful for global navigation and actions. We are going to create a simple global drawer that includes a "quit" button.

Kirigami.ApplicationWindow {
    id: root
    // Otras propiedades de la ventana...
    globalDrawer: Kirigami.GlobalDrawer {
        isMenu: true
        actions: [
            Kirigami.Action {
                text: i18n("Quit")
                icon.name: "application-exit-symbolic"
                shortcut: StandardKey.Quit
                onTriggered: Qt.quit()
            }
        ]
    }
    // ...
}

Here, we put our global drawer inside our application window. The main property we need to pay attention to is GlobalDrawer.actions, which takes the form of an array of Kirigami.Action components. This action has an appropriate icon and executes the Qt.quit() function when triggered, closing the application.

Como vamos a mantener nuestro cajón global simple por ahora, definimos la propiedad GlobalDrawer.isMenu como true. Esto muestra nuestro cajón global como un menú de aplicación normal, que ocupa menos espacio que el panel del cajón global predeterminado.

Consejo

The Actions based components page of these docs provides further detail on Kirigami Actions and how they can be used.

Las acciones son contextuales

Kirigami components are designed in such a way that the place where you put Kirigami Actions is relevant. As seen above, if you add actions to a Kirigami.Page, Kirigami.ScrollablePage or any other derivative Page component, they will show up on the right side of the header in desktop mode, and on the bottom in mobile mode.

Similarly, if Kirigami Actions are added to a Kirigami.GlobalDrawer, they will show up in the resulting drawer or menu.

Otros ejemplos de acciones de Kirigami que se muestran de forma distinta dependiendo del componente padre que tengan son:

Kirigami.ContextDrawer - Tutorial de ContextDrawer
Kirigami.AbstractCard and derivatives - Tutorial de Card
Kirigami.Dialog and derivatives - Tutorial de Dialog
Kirigami.ActionToolBar - Tutorial de ActionToolBar

Entre otros complementos de Kirigami

Nuestra aplicación hasta ahora

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
        }
    }
}

Layouts, ListViews y Cards

Añadir un diálogo