Delegáty formulárov na vašich stránkach nastavení

Vytvorte elegantné vlastné stránky nastavení.

Kirigami Addons je dodatočná sada vizuálnych komponentov, ktoré dobre fungujú na mobiloch aj desktopoch a je zaručená ich multiplatformovosť. Na vytváranie svojich komponentov používa Kirigami pod kapotou.

Naučili ste sa pridať stránky O aplikácii a O KDE do vašej aplikácie. Teraz budete môcť použiť rovnaké vnútorné komponenty na vytvorenie vašich stránok nastavení.

Štruktúra projektu by mala vyzerať takto:

addonsexample
├── CMakeLists.txt
├── main.cpp 
├── Main.qml
├── MyAboutPage.qml
└── SettingsPage.qml

Potrebné zmeny

Zmeňte Main.qml tak, aby zahŕňal našu novú stránku Nastavení:

import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
    id: root
    width: 600
    height: 700

    Component {
        id: aboutkde
        FormCard.AboutKDE {}
    }

    Component {
        id: aboutpage
        MyAboutPage {}
    }

    Component {
        id: settingspage
        SettingsPage {}
    }

    pageStack.initialPage: Kirigami.ScrollablePage {
        ColumnLayout {
            FormCard.FormCard {
                FormCard.FormButtonDelegate {
                    id: aboutKDEButton
                    icon.name: "kde"
                    text: i18n("About KDE Page")
                    onClicked: root.pageStack.layers.push(aboutkde)
                }

                FormCard.FormButtonDelegate {
                    id: aboutPageButton
                    icon.name: "applications-utilities"
                    text: i18n("About Addons Example")
                    onClicked: root.pageStack.layers.push(aboutpage)
                }

                FormCard.FormButtonDelegate {
                    id: settingsButton
                    icon.name: "settings-configure"
                    text: i18n("Single Settings Page")
                    onClicked: root.pageStack.layers.push(settingspage)
                }
            }
        }
    }
}

Teraz môžeme začať skúmať komponenty používané na vytvorenie našej stránky Nastavení: Form Card a jeho delegáty.

Delegát

FormCard a FormCardPage

FormCard.FormCard je hlavný komponent, ktorý budeme používať na zoskupenie všetkých jeho podriadených komponentov, delegátov.

Formulárovú kartu sme už použili v úvode do Kirigami Addons. Jej hlavným účelom je slúžiť ako kontajner pre ďalšie komponenty s farbou odlišnou od pozadia, podobne ako Kirigami.Card.

Vytvorte nový súbor SettingsPage.qml:

import QtQuick
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
    FormCard.FormCard {
        // Tu budú všetky naše delegáty!
    }

    FormCard.FormCard {
        // Tu budú všetky naše delegáty!
    }
}

Keďže vytvárame samostatný súbor QML pre našu stránku Nastavení a keďže sa musíme pripraviť na prípadné posúvanie na našej stránke, používame FormCard.FormCardPage, ktorý dedí z Kirigami.ScrollablePage.

Pekná vec na stránke formulárovej karty je, že prichádza s vnútorným rozložením, takže nie je potrebný žiadny ďalší ColumnLayout a naše delegáty je možné pridať priamo do nej.

Poznámka

Je možné použiť delegáty FormCard priamo s Kirigami.ScrollablePage, ale v tom prípade budete musieť pridať vlastné rozloženia.

Hlavička

Pre každý FormCard, ktorý chcete vytvoriť, môžete vytvoriť FormHeader tesne pred ním. Hlavička používa tučný text a zobrazuje sa priamo nad formulárovou kartou.

import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
    FormCard.FormHeader {
        title: i18n("General")
    }

    FormCard.FormCard {
        // Tu budú naše delegáty...
    }

    FormCard.FormHeader {
        title: i18n("Accounts")
    }

    FormCard.FormCard {
        // Tu budú naše delegáty...
    }
}

FormTextDelegate a FormSectionText

Začnime jednoducho, s obyčajným textom.

FormSectionText jednoducho pridá tenký delegát obsahujúci štítok. FormTextDelegate má text a zošednutý popis.

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
    FormCard.FormHeader {
        title: i18n("General")
    }

    FormCard.FormCard {
        FormCard.FormTextDelegate {
            text: i18n("Current Color Scheme")
            description: "Breeze"
        }
    }

    FormCard.FormHeader {
        title: i18n("Accounts")
    }

    FormCard.FormCard {
        FormCard.FormSectionText {
            text: i18n("Online Account Settings")
        }
        FormCard.FormTextDelegate {
            leading: Kirigami.Icon {source: "user"}
            text: "John Doe"
            description: i18n("The Maintainer ™️")
        }
    }
}

Pridáme zástupný text pre hypotetickú detekciu témy. Keby sme chceli skutočnú detekciu farebnej schémy, v budúcnosti by to bolo možné urobiť podobne ako v Neochat (kód tu), využitím C++ modelu s KColorSchemeManager.

V sekcii Online účty vidíme dodatočnú vlastnosť leading. Môžeme do nej pridať Item, aby sa zobrazil pred textom. Opačná vlastnosť trailing by mohla zobraziť Item za textom, ale v našom programe ju nepoužijeme.

Pre jednoduchosť tu používame Kirigami.Icon, ale toto by sa dalo implementovať aj pomocou Avatara Kirigami Addons, ktorý získava informácie z modelu, ako sa to robí v Neochat.

Výsledok by mal vyzerať takto:

Delegát

FormButtonDelegate je vizuálne podobný FormTextDelegate, ale je klikateľný a zobrazuje šípku smerujúcu doprava. Použili sme ho predtým v úvode do Kirigami Addons.

Zatiaľ čo FormTextDelegate mal vlastnosti leading a trailing na zobrazenie položky pred a za hlavným obsahom, FormButtonDelegate má iba vlastnosť leading, pretože pravá strana je obsadená šípkou.

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
    FormCard.FormHeader {
        title: i18n("General")
    }

    FormCard.FormCard {
        FormCard.FormTextDelegate {
            text: i18n("Current Color Scheme")
            description: "Breeze"
        }
    }

    FormCard.FormHeader {
        title: i18n("Accounts")
    }

    FormCard.FormCard {
        FormCard.FormSectionText {
            text: i18n("Online Account Settings")
        }
        FormCard.FormTextDelegate {
            leading: Kirigami.Icon {source: "user"}
            text: "John Doe"
            description: i18n("The Maintainer ™️")
        }
        FormCard.FormButtonDelegate {
            icon.name: "list-add"
            text: i18n("Add a new account")
            onClicked: console.info("Clicked!")
        }
    }
}

Používame jeho vlastnosť icon.name na nastavenie ikony plus (+), aby sa zobrazila za miestom, kde by sa objavil leading, a pred hlavným obsahom. Toto je bežný vzor na označenie, že vaše tlačidlo pridá niečo do zoznamu.

Keďže tento príklad je na jednoduché ilustračné účely, neponárame sa hlboko do toho, čo by sa stalo po kliknutí na tlačidlo: jednoducho vypíše "Clicked!" do terminálu. Mohli by sme vytvoriť novú stránku na vytvorenie účtu, ktorá pridá ďalšieho používateľa do modelu, a potom stránku zobraziť, podobne ako sme to urobili v Main.qml.

FormRadioDelegate, FormCheckDelegate a FormSwitchDelegate

RadioButton, CheckBox a Switch sú veľmi bežne používané komponenty v každom používateľskom rozhraní. Kirigami Addons ich poskytuje ako FormRadioDelegate, FormCheckDelegate a FormSwitchDelegate.

Ich jediné hlavné vlastnosti sú text a description. Líšia sa v používaní, pretože všetky dedia z AbstractButton, a preto sa očakáva, že budete používať jeho signály a obsluhy: checked a onChecked, toggled a onToggled, clicked a onClicked.

Chceme vytvoriť funkciu automatického ukladania v našej aplikácii a chceme zobraziť jej nastavenia iba v prípade, že používateľ túto funkciu povolil. Vytvorte novú sekciu pomocou FormCard a FormHeader, potom pridajte FormSwitchDelegate a FormRadioDelegate.

FormCard.FormHeader {
    title: i18n("Autosave")
}

FormCard.FormCard {
    FormCard.FormSwitchDelegate {
        id: autosave
        text: i18n("Enabled")
    }
    FormCard.FormRadioDelegate {
        text: i18n("After every change")
        visible: autosave.checked
    }
    FormCard.FormRadioDelegate {
        text: i18n("Every 10 minutes")
        visible: autosave.checked
    }
    FormCard.FormRadioDelegate {
        text: i18n("Every 30 minutes")
        visible: autosave.checked
    }
}

Viažeme viditeľnosť každého prepínacieho tlačidla na prepínač, takže sa objavia iba keď je prepínač zapnutý.

Osvedčené postupy

Click here to read more

Ak máte nejaké programátorské skúsenosti s imperatívnymi jazykmi ako C++, mohli by ste byť v pokušení nastaviť vlastnosť checked prepínača na zapnutie viditeľnosti prepínacích tlačidiel na true pomocou priradenia v JavaScripte ako napríklad:

checked: {
    radio1.visible = true;
    radio2.visible = true;
    radio3.visible = true;
}

Toto nie je veľmi efektívne pre deklaratívny jazyk QML a jeho signály a sloty. Pokúste sa používať väzby QML ako v prípade visible: autosave.checked čo najviac namiesto výrazov JavaScripte.

Podrobnosti nájdete na tejto stránke.

Na otestovanie nášho zaškrtávacieho políčka môžeme pridať nový FormCheckDelegate do našej sekcie Všeobecné.

FormCard.FormHeader {
    title: i18n("General")
}

FormCard.FormCard {
    FormCard.FormTextDelegate {
        text: i18n("Current Color Scheme")
        description: "Breeze"
    }
    FormCard.FormCheckDelegate {
        text: i18n("Show Tray Icon")
        onToggled: {
            if (checkState) {
                console.info("A tray icon appears on your system!")
            } else {
                console.info("The tray icon disappears!")
            }
        }
    }
}

Tu používame obsluhu signálu s názvom onToggled na zobrazenie ukážkového textu simulujúceho zobrazenie ikony v systémovej lište. Ak by ste naozaj chceli, mohli by ste jednoducho implementovať ikonu v systémovej lište pomocou KStatusNotifierItem od KDE alebo SystemTrayIcon od Qt.

Naša aplikácia by zatiaľ mala vyzerať takto:

FormComboBoxDelegate

Bežný komponent ComboBox možno vytvoriť pomocou FormComboBoxDelegate.

Tento combobox má niekoľko užitočných vlastností, ktoré môžeme využiť: editable, displayText a displayMode.

Nastavenie editable: true umožňuje používateľovi upravovať text comboboxu, čo je užitočné v prípade, keď je potrebné pridať nové možnosti do comboboxu:

Kedykoľvek potrebujete zobraziť dodatočný text pred každou možnosťou, môžete použiť niečo ako displayText: "Profile: " + currentText:

A najzaujímavejšia, ktorú budeme používať v našom príklade, je displayMode. Má tri možnosti:

FormComboBoxDelegate.ComboBox: štandardné malé pole zobrazujúce zoznam možností.

FormComboBoxDelegate.Dialog: dialóg zobrazujúci zoznam možností v strede okna, podobne ako Kirigami.OverlaySheet.

FormComboBoxDelegate.Page: nová stránka obsahujúca zoznam možností zobrazená v samostatnom okne.

Pridajte nasledovné medzi delegáty "Current Color Scheme" a "Show Tray Icon" vo vašej formulárovej karte "General".

FormCard.FormComboBoxDelegate {
    text: i18n("Default Profile")
    description: i18n("The profile to be loaded by default.")
    displayMode: FormCard.FormComboBoxDelegate.ComboBox
    currentIndex: 0
    editable: false
    model: ["Work", "Personal"]
}

S checkboxom by naša stránka Nastavení mala vyzerať takto:

FormDelegateSeparator

Naša stránka Nastavení nadobúda tvar, ale každá sekcia začína byť dlhá. Môžeme pridať niekoľko inštancií FormDelegateSeparator, aby bola naša stránka prehľadnejšia:

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
    id: root

    title: i18nc("@title", "Settings")

    FormCard.FormHeader {
        title: i18nc("@title:group", "General")
    }

    FormCard.FormCard {
        FormCard.FormTextDelegate {
            text: i18nc("@info", "Current Color Scheme")
            description: "Breeze"
        }

        FormCard.FormComboBoxDelegate {
            id: combobox
            text: i18nc("@label:listbox", "Default Profile")
            description: i18nc("@info:whatsthis", "The profile to be loaded by default.")
            displayMode: FormCard.FormComboBoxDelegate.ComboBox
            currentIndex: 0
            editable: false
            model: ["Work", "Personal"]
        }

        FormCard.FormDelegateSeparator {
            above: combobox
            below: checkbox
        }

        FormCard.FormCheckDelegate {
            id: checkbox
            text: i18nc("@option:check", "Show Tray Icon")
            onToggled: {
                if (checkState) {
                    console.info("A tray icon appears on your system!")
                } else {
                    console.info("The tray icon disappears!")
                }
            }
        }
    }

    FormCard.FormHeader {
        title: i18nc("@title:group", "Autosave")
    }

    FormCard.FormCard {
        FormCard.FormSwitchDelegate {
            id: autosave
            text: i18nc("@option:check", "Enabled")
        }
        FormCard.FormDelegateSeparator {
            above: autosave
            below: firstradio
            visible: autosave.checked
        }
        FormCard.FormRadioDelegate {
            id: firstradio
            text: i18nc("@option:radio", "After every change")
            visible: autosave.checked
        }
        FormCard.FormRadioDelegate {
            text: i18nc("@option:radio", "Every 10 minutes")
            visible: autosave.checked
        }
        FormCard.FormRadioDelegate {
            text: i18nc("@option:radio", "Every 30 minutes")
            visible: autosave.checked
        }
    }

    FormCard.FormHeader {
        title: i18nc("@title:group", "Accounts")
    }

    FormCard.FormCard {
        FormCard.FormSectionText {
            text: i18nc("@info:whatsthis", "Online Account Settings")
        }
        FormCard.FormTextDelegate {
            id: lastaccount
            leading: Kirigami.Icon {source: "user"}
            text: "John Doe"
            description: i18nc("@info:credit", "The Maintainer ™️")
        }
        FormCard.FormDelegateSeparator {
            above: lastaccount
            below: addaccount
        }
        FormCard.FormButtonDelegate {
            id: addaccount
            icon.name: "list-add"
            text: i18nc("@action:button", "Add a new account")
            onClicked: console.info("Clicked!")
        }
    }
}

Vo všeobecnosti môžete použiť oddeľovače vždy, keď vidíte hlavné rozdiely medzi komponentmi, hoci voľba, kam ich umiestniť, je nakoniec na vás. Napríklad v sekcii Všeobecné sa zaškrtávacie políčko líši od predchádzajúcich komponentov tým, že nezačína textom; v sekcii Automatické ukladanie oddeľovač zoskupuje prepínacie tlačidlá; a v sekcii Účty pridanie oddeľovača medzi posledný účet a tlačidlo poskytuje tlačidlu dodatočný dôraz.

Vlastnosti above a below sú celkom samovysvetľujúce, pokiaľ ide o ich použitie: odovzdáte id komponentov nad a pod oddeľovačom. Keď sú nastavené, oddeľovač rýchlo zmizne vždy, keď je položka nad alebo pod ním zvýraznená/podržaná myšou. Sú najužitočnejšie napríklad pri použití FormDelegateSeparator v situácii, kde môže skončiť vedľa iných oddeľovačov alebo hlavičiek sekcií.

Všimnite si, ako sa oddeľovač nad nastavením ikony v lište nezobrazí, keď je na ňom kurzor.

Stránky FormCard O aplikácii

Nastavenie pre Windows