Componentes baseados em acções

As Acções do Kirigami são usadas para adicionar funcionalidades aos componentes.

Acções

A Kirigami.Action consists of a clickable action whose appearance depends on where it is added. Typically it is a button with an icon and text.

We can use these to provide our applications with easy-to-reach actions that are essential to their functionality.

Nota

Kirigami Actions inherit from QtQuick.Controls.Action and can be assigned shortcuts.

Como as Action's do QtQuick Controls, as mesmas poderão ser associadas não só aos itens do menu e aos botões das barras de ferramentas, mas também a vários outros componentes do Kirigami.

import org.kde.kirigami as Kirigami

Kirigami.Action {
    id: copyAction
    text: i18n("Copy")
    icon.name: "edit-copy"
    shortcut: StandardKey.Copy
    onTriggered: {
        // ...
    }
}

Nota

A propriedade icon.name recebe os nomes dos ícones de sistema de acordo com a especificação do FreeDesktop. Estes ícones e nomes de ícones podem ser vistos com a aplicação Cuttlefish, que vem com o pacote plasma-sdk, ou indo à especificação de nomes de ícones do FreeDesktop.

One feature offered by Kirigami Actions on top of QtQuick Actions is the possibility to nest actions.

import org.kde.kirigami as Kirigami

Kirigami.Action {
    text: "View"
    icon.name: "view-list-icons"
    Kirigami.Action {
        text: "action 1"
    }
    Kirigami.Action {
        text: "action 2"
    }
    Kirigami.Action {
        text: "action 3"
    }
}

Outra funcionalidade das acções do Kirigami é fornecer várias dicas aos itens que usam acções, sobre a forma como devem mostra a acção. Estas são tratadas principalmente pelas propriedades displayHint and displayComponent.

Estas propriedades serão respeitadas pelo item, se possível. Por exemplo, as seguintes acções serão apresentadas como um TextField com o item a tentar o seu melhor em manter o item visível o máximo de tempo possível.

import org.kde.kirigami as Kirigami

Kirigami.Action {
    text: "Search"
    icon.name: "search"

    displayComponent: TextField { }

    displayHint: Kirigami.DisplayHints.KeepVisible
}

Usar as acções noutros componentes

As mentioned in the introduction tutorial for actions, Kirigami Actions are contextual, which means they show up in different places depending on where you put them. In addition to that, they also have different representations for desktop and mobile.

Página

A Kirigami.Page shows Actions on the right of the top header in desktop mode, and on a footer in mobile mode.

 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
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Actions Demo"
    width: 600
    height: 600

    globalDrawer: Kirigami.GlobalDrawer {}
    contextDrawer: Kirigami.ContextDrawer {}

    pageStack.initialPage: Kirigami.Page {
        title: "Demo"

        actions: [
            Kirigami.Action {
                icon.name: "go-home"
                onTriggered: showPassiveNotification("Main action triggered")
            },
            Kirigami.Action {
                icon.name: "go-previous"
                onTriggered: showPassiveNotification("Left action triggered")
            },
            Kirigami.Action {
                icon.name: "go-next"
                onTriggered: showPassiveNotification("Right action triggered")
            },
            Kirigami.Action {
                text: "Contextual Action 1"
                icon.name: "bookmarks"
                onTriggered: showPassiveNotification("Contextual action 1 clicked")
            },
            Kirigami.Action {
                text: "Contextual Action 2"
                icon.name: "folder"
                enabled: false
            }
        ]
    }
}

Área global

The Kirigami.GlobalDrawer is a menu-like sidebar that provides an action based navigation to your application. This is where nested actions are useful because it is possible to create nested navigation:

import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Actions Demo"
    globalDrawer: Kirigami.GlobalDrawer {
        title: "Demo"
        titleIcon: "applications-graphics"
        actions: [
            Kirigami.Action {
                text: "View"
                icon.name: "view-list-icons"
                Kirigami.Action {
                    text: "View Action 1"
                    onTriggered: showPassiveNotification("View Action 1 clicked")
                }
                Kirigami.Action {
                    text: "View Action 2"
                    onTriggered: showPassiveNotification("View Action 2 clicked")
                }
            },
            Kirigami.Action {
                text: "Action 1"
                onTriggered: showPassiveNotification("Action 1 clicked")
            },
            Kirigami.Action {
                text: "Action 2"
                onTriggered: showPassiveNotification("Action 2 clicked")
            }
        ]
    }
    //...
}

Poderá ler mais sobre as Áreas Globais na página de documentação das mesmas.

Context drawer

A Kirigami.ContextDrawer consists of an additional set of actions that are hidden behind a three-dots menu on the top right in desktop mode or on the bottom right in mobile mode if there is no space. It is used to display actions that are only relevant to a specific page. You can read more about them in our Kirigami Drawers tutorial.

ActionTextFields

Um Kirigami.ActionTextField é usado para adicionar algumas acções de contexto a um campo de texto, como por exemplo limpar o texto ou procurar pelo mesmo.

Kirigami.ActionTextField {
    id: searchField
    rightActions: [
        Kirigami.Action {
            icon.name: "edit-clear"
            visible: searchField.text !== ""
            onTriggered: {
                searchField.text = ""
                searchField.accepted()
            }
        }
    ]
}

Neste exemplo, estamos a criar um botão "limpar" para um campo de pesquisa que só aparece quando tiver introduzido algum texto.

Nota

Raramente deverá usar um ActionTextField directamente. O SearchField e o PasswordField herdam ambos de ActionTextField e provavelmente irão cobrir o seu caso de uso desejado.

SwipeListItem

Um Kirigami.SwipeListItem é um objecto-delegado que pretende dar suporte a acções extras. Ao usar um rato, as mesmas irão aparecer à passagem. Num dispositivo táctil, as mesmas poderão aparecer se arrastar o item com a pega. Nas seguintes imagens, estes são os ícones à direita.

ListView {
    model: myModel
    delegate: SwipeListItem {
        Controls.Label {
            text: model.text
        }
        actions: [
             Action {
                 icon.name: "document-decrypt"
                 onTriggered: print("Action 1 clicked")
             },
             Action {
                 icon.name: model.action2Icon
                 onTriggered: //fazer algo
             }
        ]
    }
}

ActionToolBar

Uma Kirigami.ActionToolBar é uma barra de ferramentas construída com base numa lista de acções. Por omissão, cada acção que caiba na barra de ferramentas será representada como um ToolButton, sendo que as que não caibam irão para um menu no fim da barra de ferramentas.

Como o ActionTextField, poderá não necessitar de usar o ActionToolBar directamente, dado que é usado pelos cabeçalhos das páginas e cartões para fornecer a sua apresentação das acções.

import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    title: "Actions Demo"
    width: 350
    height: 350
    header: Kirigami.ActionToolBar {
        actions: [
            Kirigami.Action {
                text: i18n("View Action 1")
                onTriggered: showPassiveNotification(i18n("View Action 1 clicked"))
            },
            Kirigami.Action {
                text: i18n("View Action 2")
                onTriggered: showPassiveNotification(i18n("View Action 2 clicked"))
            },
            Kirigami.Action {
                text: i18n("Action 1")
                onTriggered: showPassiveNotification(i18n("Action 1 clicked"))
            },
            Kirigami.Action {
                text: i18n("Action 2")
                onTriggered: showPassiveNotification(i18n("Action 2 clicked"))
            }
        ]
    }
}

Uma barra de ferramentas horizontal a ser apresentada no topo da aplicação

Poderá ler mais sobre os componentes ActionToolBar na sua página de documentação dedicada.

Cartões

Um Kirigami.Card é usado para apresentar uma colecção de informações ou acções em conjunto. Estas acções poderão ser adicionadas ao grupo actions, de forma semelhante aos componentes anteriores.

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"
        titleAlignment: Qt.AlignLeft | Qt.AlignBottom
    }
    contentItem: Controls.Label {
        wrapMode: Text.WordWrap
        text: "My Text"
    }
}

Imagem de um Card completo com um fundo separador debaixo do seu título, um fundo branco atrás do seu texto e duas acções com ícones e um menu em hambúrguer no fundo

Para mais informações, consulte a página dos componentes Card.

Tipografia

Linhas da página e pilhas de páginas