Дії з додавання

Ширші знання щодо дій Kirigami допоможуть нам зробити нашу програму кориснішою.

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.

Коротке повторення

Досі, нами побудовано просту програму, яка показує картки. Втім, у ній ще не передбачено способу додавання нових карток до панелі перегляду карток.

У цій частині підручника ми розглянемо дії Kirigami. Ці дії допоможуть нам додати інтерактивності нашій програмі у сумісний, швидкий і доступний спосіб.

Дії

Дія Kirigami.Action є контейнером для дії з інтерфейсом користувача. Діями можна скористатися для надання нашій програмі легкодоступних дій, які є критичними для виконання нею функціональних можливостей.

Якщо ви раніше користувалися програмами Kirigami, ви напевне взаємодіяли із діями Kirigami. На цьому зображенні ми можемо бачити кнопки дій праворуч від заголовка сторінки із різноманітними піктограмами. Дії Kirigami може бути показано у декілька способів. Вони можуть виконувати широкий діапазон завдань.

Додавання відліків

Програма із зворотним відліком буде непотрібною без можливості додавання зворотних відліків. Давайте створимо дію, яка надасть нам змогу додавати зворотні відліки.

pageStack.initialPage: Kirigami.ScrollablePage {
    // Інші властивості сторінки…
    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
            })
        }
    ]
    // ...
}

Ми розташовуємо нашу Kirigami.Action на нашій основній сторінці з попередніх підручників. Якщо нам потрібно, ми можемо додати інші кнопки дій на нашій сторінці (і навіть вкласти дії у інші дії!).

Дужки [], які використано вище, є подібними до дужок масивів JavaScript, що означає, що ви можете передати їм одну або декілька речей, відокремлених комами:

// Загальний масив компонентів JavaScript:
variable: [ component1, component2 ]
// Передавання масиву дій Kirigami до QML:
actions: [ Kirigami.Action {}, Kirigami.Action {} ]

Із властивостями id і text ми вже познайомилися у попередніх розділах підручника. Втім, нас має зацікавити нова властивість Action.icon: це об'єкт із декількома властивостями, за допомогою якого можна показувати певні піктограми для наших дій. На щастя, щоб скористатися піктограмами KDE достатньо надати назву для властивості піктограми, icon.name.

Перегляд доступних піктограм

Натисніть тут, щоб ознайомитися із тим, як переглянути доступні піктограми у вашій системі

Cuttlefish — програма KDE, за допомогою якої ви можете переглянути усі піктограми, якими можна скористатися у вашій програмі. У програмі передбачено декілька корисних можливостей, зокрема попередній перегляд вигляду піктограм у різних встановлених темах, попередній перегляд із різними розмірами тощо. Можливо, програма буде корисною для вас із метою визначення, які піктограми варто використати у вашій програмі.

У багатьох піктограмах KDE використано специфікацію назв піктограм FreeDesktop. Через це, вам також буде корисним звернутися до сайта проєкту FreeDesktop, де наведено список усіх сумісних із різними стільничними середовищами назв піктограм.

Найважливішою є обробник сигналів onTriggered. Вона визначає те, що буде виконано, коли використовуватиметься наша дія. Ви можете зауважити, що у нашому прикладі ми використовуємо метод kountdownModel.append kountdownModel.append, який було створено у попередньому розділі нашого підручника. За допомогою цього методу можна додати новий елемент до нашої моделі списку. Ми надаємо методу об'єкт (позначений фігурними дужками {}), який має відповідні властивості для наших відліків (name, description та замінник date).

Кожного разу, коли ми натискатимемо кнопку «Add kountdown» у верхній правій частині вікна, додаватиметься наш нетиповий відлік.

Загальна панель

Наступним компонентом є Kirigami.GlobalDrawer. Він показує меню-гамбургер. Типово, він відкриває бічну панель, яка є особливо корисною на мобільних пристроях, оскільки користувач може просто провести пальцем збоку екрана, щоб відкрити його. Загальні висувні панелі корисні для загальної навігації та кнопок дій. Ми збираємося створити просту загальну висувну панель, на якій буде показано кнопку «Вийти».

Kirigami.ApplicationWindow {
    id: root
    // Інші властивості вікна…
    globalDrawer: Kirigami.GlobalDrawer {
        isMenu: true
        actions: [
            Kirigami.Action {
                text: i18n("Quit")
                icon.name: "application-exit-symbolic"
                shortcut: StandardKey.Quit
                onTriggered: Qt.quit()
            }
        ]
    }
    // ...
}

Тут ми розмістили нашу загальну висувну панель у нашому вікні програми. Головною властивістю, якій ми маємо приділити увагу, є GlobalDrawer.actions. Ця властивість приймає значення масиву компонентів Kirigami.Action. Ця дія має відповідну піктограму і запускає функцію Qt.quit(), яка завершує роботу програми.

Оскільки ми поки зберігаємо простоту нашої загальної висувної панелі, ми встановлюємо для GlobalDrawer.isMenu значення true. У результаті нашу загальну висувну панель буде показано як звичайне меню програми, яке займатиме менше місця за типову загальну висувну панель.

Підказка

Сторінка заснованих на Actions компонентів у розділі «Компоненти» цієї документації містить докладніші відомості щодо дій Kirigami та їхнього використання.

Дії є контекстними

Компоненти Kirigami розроблено так, щоб місце, де ви розташуєте кнопки дій Kirigami, було відповідним. Як можна бачити вище, якщо ви додаєте кнопки дій до Kirigami.Page, Kirigami.ScrollablePage або будь-якому іншому похідному від Page компоненті, їх буде показано у правій частині заголовка у режимі робочої станції і у нижній частині сторінки у режимі мобільного пристрою.

Так само, якщо дії Kirigami буде додано до Kirigami.GlobalDrawer, їх буде показано на висувній панелі або у меню.

Інші приклади дій Kirigami, які показано по-різному, залежжжно від їхнього батьківського компонента:

Kirigami.ContextDrawer — підручник з ContextDrawer тут
Kirigami.AbstractCard і похідні — підручник з карток тут
Kirigami.Dialog і похідні — підручник з Dialog тут
Kirigami.ActionToolBar - підручник з ActionToolBar

Серед інших компонентів Kirigami.

Наша програма на поточний момент

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

Компонування, панелі списків і картки

Додавання діалогового вікна