Добавление действий

Изучение действий Kirigami поможет сделать приложение более полезным.

Резюме

Пока что создано простое приложение, которое умеет показывать карточки. Однако сейчас нет способа добавить новые карточки в представление карточек.

В этом руководстве рассматриваются действия 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, достаточно указать свойство name для свойства icon — icon.name.

Просмотр доступных значков

Нажмите здесь, чтобы узнать, как проверить доступные значки в системе

Icon Explorer — приложение KDE, позволяющее просматривать все значки, которые можно использовать в приложении. Оно предоставляет ряд полезных возможностей: предварительный просмотр внешнего вида значков в различных установленных оформлениях, предварительный просмотр значков разных размеров и многое другое. Этот инструмент может пригодиться при выборе значков для приложения.

Многие значки KDE соответствуют спецификации именования значков FreeDesktop. Поэтому может оказаться полезным также обратиться к сайту проекта FreeDesktop, где перечислены все имена значков, совместимые с разными рабочими средами.

Обработчик сигнала onTriggered — самый важный. Именно это сделает наше действие при его использовании. Заметьте, что в примере используется метод kountdownModel.append модели kountdownModel, созданной в предыдущем руководстве. Этот метод позволяет добавить новый элемент в модель списка. Ему передаётся объект (обозначен фигурными скобками {}) с нужными свойствами для обратных отсчётов (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. Тогда глобальная выдвижная панель показывается как обычное меню приложения и занимает меньше места, чем стандартная выдвижная панель.

Совет

На странице компонентов на основе действий этой документации приведены более подробные сведения о действиях Kirigami и о том, как их использовать.

Действия зависят от контекста

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

Аналогично, если добавить действия Kirigami в Kirigami.GlobalDrawer, они появятся в получившейся выдвижной панели или меню.

Другие примеры действий Kirigami, которые показываются по-разному в зависимости от родительского компонента:

Kirigami.ContextDrawer — Руководство по ContextDrawer
Kirigami.AbstractCard и производные от него — Руководство по карточкам
Kirigami.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
        }
    }
}

Компоновки, списки и карточки

Добавление диалога