Diseños de formulario

Cree con facilidad áreas de interacción atractivas con FormLayouts de Kirigami

Los componentes Kirigami.FormLayout le facilitan la creación de formularios que se ajusten a las Directrices de interfaces humanas de KDE. Son óptimos para los cuadros de diálogo de configuración y para grandes grupos de controles y campos de entrada que están relacionados entre sí.

When provided with enough space, form layouts will take up two columns. The column on the left will be occupied by the labels provided for the form's children components, while the right will be taken up by the children components themselves. In more space-constrained windows (or on mobile), forms will consist of a single vertical column with the labels of children components being placed above their respective component.

Formulario sencillo

Kirigami.FormLayout components are similar in use to QtQuick Layout components such as ColumnLayout or RowLayout. The child components will be automatically arranged according to the size available to the form layout.

Children of a Kirigami.FormLayout have a property named Kirigami.FormData.label . This property lets you set the label that will be provided for the child component in question.

import QtQuick 2.15
import QtQuick.Layouts 1.15
import QtQuick.Controls 2.15 as Controls
import org.kde.kirigami 2.20 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:"
            }
        }
    }
}
Un diseño de formulario simple en modo escritorio

Un diseño de formulario simple en modo escritorio

Secciones y separadores

FormLayouts can also be divided into sections. Setting where a section starts is as easy as setting a child component's Kirigami.FormData.isSection to true. This will provide the component with some extra margin at the top to demarcate the start of the new section.

Kirigami.Separator components are best suited for starting new sections. Separators are used to draw a thin horizontal line, demarcating the end of a section. If you would rather not have a line drawn between sections, you can use a standard QML Item property. Alternatively you could use the Kirigami.FormData.isSection property on any other component.

However, this is not recommended. On components where Kirigami.FormData.isSection is set to true, the label text provided for this component's Kirigami.FormData.label property will be displayed as the section's header text.

This header text is larger than the normal label text, and provides users with a nice visual cue of what the form layout section is about.

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:"
    }
}
Un diseño de formulario con secciones

Un diseño de formulario con secciones

Hijos con casillas de verificación

Una funcionalidad útil de Kirigami.FormLayout es que puede asignar casillas de verificación a sus hijos. Esto puede ser de utilidad en las páginas de preferencias donde quiera permitir que el usuario active o desactive una preferencia y también quiera que el usuario proporcione información adicional en un componente, como un campo de texto.

Kirigami.FormLayout {
    anchors.fill: parent

    Controls.TextField {
        Kirigami.FormData.label: "First name:"
    }
    Controls.TextField {
        Kirigami.FormData.label: "Middle name:"
        Kirigami.FormData.checkable: true
        enabled: Kirigami.FormData.checked
    }
    Controls.TextField {
        Kirigami.FormData.label: "Last name:"
    }
}
Un diseño de formulario con una etiqueta que se puede marcar.

Un diseño de formulario con una etiqueta que se puede marcar.

Forzar un diseño de escritorio o móvil

If you would rather have your form layout stay consistent regardless of your application's environment, you can use the wideMode property of the Kirigami.FormLayout component:

  • Cuando vale true, el formulario se estructurará en formato de pantalla ancha optimizado para el escritorio (a doble columna)
  • Cuando vale false, el formulario se organizará en un formato para móviles (a una sola columna)
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:"
    }
}
Un diseño de formulario con diseño móvil forzado

Un diseño de formulario con diseño móvil forzado

Alineación de etiquetas

There are instances when you want a label to be assigned to components that have more than one line or to a list of components. This can be achieved by putting the Kirigami.FormData.label in the ColumnLayout, as you might have noticed in Sections and Separators. By default the label is positioned in the vertical center of the layout, which is not always desirable. We can change this with help of 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
        }
    }
}
Un diseño de formulario con una etiqueta alineada a la parte superior

Un diseño de formulario con una etiqueta alineada a la parte superior

Setting the label alignment is particularly convenient to manage components or lists of components whose size you do not know beforehand. Elisa is a very good example of this:

La etiqueta Comment solo está alineada a la parte superior cuando su correspondiente componente tiene más de una línea.

La etiqueta Comment solo está alineada a la parte superior cuando su correspondiente componente tiene más de una línea.

Podemos hacer algo similar a esto con un operador ternario de 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
        }
    }
}