Layouts de formulário

Os componentes Kirigami.FormLayout facilitam a criação de formulários em conformidade com as Diretrizes de Interface Humana do KDE. Eles são ideais para caixas de diálogo de configurações e para grandes grupos de controles e campos de entrada relacionados entre si.

Quando houver espaço suficiente, os layouts de formulário ocuparão duas colunas. A coluna à esquerda será ocupada pelos rótulos fornecidos para os componentes filhos do formulário, enquanto a coluna à direita será ocupada pelos próprios componentes filhos. Em janelas com menos espaço (ou em dispositivos móveis), os formulários consistirão em uma única coluna vertical com os rótulos dos componentes filhos posicionados acima de seus respectivos componentes.

Formulário simples

Os componentes Kirigami.FormLayout são semelhantes em uso aos componentes QtQuick Layout, como ColumnLayout ou RowLayout. Os componentes filhos serão organizados automaticamente de acordo com o tamanho disponível para o layout do formulário.

Os filhos de um Kirigami.FormLayout possuem uma propriedade chamada Kirigami.FormData.label. Esta propriedade permite definir o rótulo que será fornecido para o componente filho em questão.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
    pageStack.initialPage: Kirigami.Page {

        Kirigami.FormLayout {
            anchors.fill: parent

            Controls.TextField {
                Kirigami.FormData.label: "TextField 1:"
            }
            Controls.TextField {
                Kirigami.FormData.label: "TextField 2:"
            }
            Controls.TextField {
                Kirigami.FormData.label: "TextField 3:"
            }
        }
    }
}

Seções e separadores

FormLayouts também podem ser divididos em seções. Definir onde uma seção começa é tão fácil quanto definir Kirigami.FormData.isSection de um componente filho como true. Isso fornecerá ao componente uma margem extra na parte superior para demarcar o início da nova seção.

Componentes Kirigami.Separator são mais adequados para iniciar novas seções. Os separadores são usados ​​para desenhar uma linha horizontal fina, demarcando o final de uma seção. Se você preferir não ter uma linha desenhada entre as seções, pode usar uma propriedade padrão Item do QML. Alternativamente, você pode usar a propriedade Kirigami.FormData.isSection em qualquer outro componente.

No entanto, isso não é recomendado. Em componentes onde Kirigami.FormData.isSection está definido como true, o texto do rótulo fornecido para a propriedade Kirigami.FormData.label deste componente será exibido como o texto do cabeçalho da seção.

Este texto de cabeçalho é maior que o texto normal do rótulo e fornece aos usuários uma boa indicação visual do que se trata a seção de layout do formulário.

Kirigami.FormLayout {
    anchors.fill: parent

    Controls.TextField {
        Kirigami.FormData.label: "TextField 1:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 2:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 3:"
    }
    Kirigami.Separator {
        Kirigami.FormData.isSection: true
        Kirigami.FormData.label: "New Section!"
    }
    ColumnLayout {
        Kirigami.FormData.label: "Radio buttons"
        Controls.RadioButton {
            text: "Radio 1"
            checked: true
        }
        Controls.RadioButton {
            text: "Radio 2"
        }
        Controls.RadioButton {
            text: "Radio 3"
        }
    }
    Item {
        Kirigami.FormData.isSection: true
        Kirigami.FormData.label: "Another Section! (lineless though)"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 4:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 5:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 5:"
    }
}

Forçando um layout de desktop ou móvel

Se preferir que o layout do seu formulário permaneça consistente, independentemente do ambiente do seu aplicativo, você pode usar a propriedade wideMode do componente Kirigami.FormLayout:

• Quando definido como true, o layout do formulário será estruturado em um layout widescreen otimizado para desktop (coluna dupla)
• Quando definido como false, o layout do formulário será estruturado em um layout para dispositivo móvel (coluna única)

Kirigami.FormLayout {
    anchors.fill: parent
    wideMode: false

    Controls.TextField {
        Kirigami.FormData.label: "TextField 1:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 2:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "TextField 3:"
    }
}

Alinhando seus rótulos

Há casos em que você deseja que um rótulo seja atribuído a componentes que possuem mais de uma linha ou a uma lista de componentes. Isso pode ser feito colocando Kirigami.FormData.label no ColumnLayout, como você deve ter notado em Seções e separadores. Por padrão, o rótulo é posicionado no centro vertical do layout, o que nem sempre é desejável. Podemos mudar isso com a ajuda de Kirigami.FormData.labelAlignment.

Kirigami.FormLayout {
    anchors.fill: parent

    ColumnLayout {
        Kirigami.FormData.label: "This is a label:"
        Kirigami.FormData.labelAlignment: Qt.AlignTop

        Controls.Label {
            text: "This is some rather long text \nthat should elide to multiple lines \nto show how the label gets aligned."
            elide: Text.elideLeft
        }
    }
}

Definir o alinhamento dos rótulos é particularmente conveniente para gerenciar componentes ou listas de componentes cujo tamanho você não sabe de antemão. O Elisa é um ótimo exemplo disso:

Podemos fazer algo semelhante a isto com um operador ternário JavaScript:

Kirigami.FormLayout {
    anchors.fill: parent

    ColumnLayout {
        Kirigami.FormData.label: "This is a label:"
        Kirigami.FormData.labelAlignment: labelText.text.lineCount > 1 ? Qt.AlignTop : Qt.AlignVCenter

        Controls.Label {
            id: labelText
            text: "This is some rather long text \nthat should elide to a new line \nso it appears below the Form Label."
            elide: Text.elideLeft
        }
    }
}