En esta página

Personalización de los controles de Qt Quick

Qt Quick Los controles constan de una jerarquía (árbol) de elementos. Para proporcionar una apariencia personalizada, la implementación predeterminada en QML de cada elemento se puede sustituir por una personalizada.

Personalización de un control

A veces querrás crear un aspecto «único» para una parte concreta de tu interfaz de usuario y utilizar un estilo completo en el resto. Quizá estés satisfecho con el estilo que estás utilizando, pero haya un botón concreto que tenga un significado especial.

La primera forma de crear este botón es simplemente definirlo in situ, allí donde se necesite. Por ejemplo, quizá no te convenza que el botón del estilo «Básico» tenga las esquinas cuadradas. Para redondearlas, puedes sobrescribir el elemento ` background ` y establecer la propiedad «radius» de `Rectangle`:

import QtQuick
import QtQuick.Controls.Basic

ApplicationWindow {
    width: 400
    height: 400
    visible: true

    Button {
        id: button
        text: "A Special Button"
        background: Rectangle {
            implicitWidth: 100
            implicitHeight: 40
            color: button.down ? "#d6d6d6" : "#f6f6f6"
            border.color: "#26282a"
            border.width: 1
            radius: 4
        }
    }
}

Nota: dado que los distintos elementos que componen un control en cualquier estilo están diseñados para funcionar conjuntamente, puede que sea necesario sobrescribir otros elementos para conseguir el aspecto deseado. Además, no todos los estilos se pueden personalizar. Consulta la nota de la Referencia de personalización para obtener más información.

La segunda forma de crear el botón es adecuada si tienes pensado utilizar tu botón redondeado en varios lugares. Implica trasladar el código a su propio archivo QML dentro de tu proyecto.

Para este enfoque, copiaremos el código de fondo del archivo « Button.qml » del estilo «Basic». Este archivo se encuentra en la siguiente ruta de tu instalación de Qt:

$QTDIR/qml/QtQuick/Controls/Basic/Button.qml

Una vez hecho esto, solo tendremos que añadir la siguiente línea:

radius: 4

Para evitar confusiones con los controles del propio módulo, llamaremos al archivo « MyButton.qml ». Para utilizar el control en tu aplicación, haz referencia a él por su nombre de archivo:

import QtQuick.Controls.Basic

ApplicationWindow {
    MyButton {
        text: qsTr("A Special Button")
    }
}

La tercera forma de crear el botón es un poco más estructurada, tanto en lo que respecta a la ubicación del archivo en el sistema de archivos como a su uso en QML. En primer lugar, copia un archivo existente tal y como has hecho anteriormente, pero esta vez colócalo en una subcarpeta de tu proyecto llamada (por ejemplo) « controls ». Para utilizar el control, primero importa la carpeta a un espacio de nombres:

import QtQuick.Controls.Basic
import "controls" as MyControls

ApplicationWindow {
    MyControls.Button {
        text: qsTr("A Special Button")
    }
}

Ahora que ya dispones del espacio de nombres « MyControls », puedes nombrar los controles según sus equivalentes reales en el módulo « Qt Quick Controls». Puedes repetir este proceso para cualquier control que desees añadir.

Una ventaja adicional de estos tres métodos es que no es necesario implementar la plantilla desde cero.

Nota: los tres enfoques mencionados aquí no sirven para personalizar el « ToolTip » adjunto, ya que se trata de un elemento compartido creado internamente. Para realizar una personalización puntual de un « ToolTip », consulta Custom Tool Tips. Para personalizar el « ToolTip » adjunto, debe proporcionarse como parte de tu propio estilo.

Creación de un estilo personalizado

Existen varias formas de crear sus propios estilos. A continuación, explicaremos los distintos métodos.

Definición de un estilo

En los controles de Qt Quick, un estilo es, básicamente, un conjunto de archivos QML dentro de un único directorio. Para que un estilo sea utilizable, debe cumplir cuatro requisitos:

  • Debe existir al menos un archivo QML cuyo nombre coincida con el de un control (por ejemplo, Button.qml).
  • Cada archivo QML debe contener el tipo correspondiente de la importación de QtQuick.Templates como elemento raíz. Por ejemplo, Button.qml debe contener una plantilla Button como elemento raíz.

    Si, en cambio, utilizáramos el tipo correspondiente de la importación de QtQuick.Controls, tal y como hicimos en la sección anterior, no funcionaría: el control que estábamos definiendo intentaría derivarse de sí mismo.

  • Debe existir un archivo qmldir junto con los archivos QML. A continuación se muestra un ejemplo de un archivo qmldir sencillo para un estilo que proporciona un botón:
    module MyStyle
    Button 2.15 Button.qml

    Si utilizas la selección de estilos en tiempo de compilación, el archivo `qmldir` también debería importar el estilo de reserva:

    # ...
    import QtQuick.Controls.Basic auto

    Esto también se puede hacer para la selección de estilos en tiempo de ejecución, en lugar de utilizar, por ejemplo, QQuickStyle::setFallbackStyle().

    La estructura de directorios para dicho estilo es la siguiente:

    MyStyle
    ├─── Button.qml
    └─── qmldir
  • Los archivos deben estar en un directorio al que se pueda acceder a través de la ruta de importación de QML.

    Por ejemplo, si la ruta al directorio «MyStyle» mencionado anteriormente fuera /home/user/MyApp/MyStyle, entonces habría que añadir /home/user/MyApp a la ruta de importación de QML.

    Para utilizar «MyStyle» en «MyApp», haz referencia a él por su nombre:

    • ./MyApp -style MyStyle

    El nombre del estilo debe coincidir con las mayúsculas y minúsculas del directorio del estilo; no se admite el uso de «mystyle» ni «MYSTYLE ».

Por defecto, el sistema de estilos utiliza el estilo «Basic» como estilo de reserva para los controles que no están implementados. Para personalizar o ampliar cualquier otro estilo integrado, es posible especificar un estilo de reserva diferente mediante ` QQuickStyle`.

Esto significa que puedes implementar tantos controles como desees para tu estilo personalizado y colocarlos prácticamente en cualquier lugar. Además, permite a los usuarios crear sus propios estilos para tu aplicación.

Vista previa de estilos personalizados en el Diseñador de Qt Quick

Siguiendo el método anterior, es posible obtener una vista previa de un estilo personalizado en el Diseñador de « Qt Quick ». Para ello, asegúrate de que el proyecto cuente con un archivo qtquickcontrols2.conf y de que contenga la siguiente entrada:

[Controls]
Style=MyStyle

Para obtener más información, consulta el ejemplo «Flat Style».

Extensiones de C++ específicas del estilo

En ocasiones, puede que necesites utilizar C++ para ampliar tu estilo personalizado.

  • Si el estilo que utiliza el tipo es el único que emplea una aplicación, registra el tipo en el motor QML añadiendo la macro « QML_ELEMENT » e incluyendo el archivo en tu módulo QML:

    qt_add_qml_module(ACoolItem
        URI MyItems
        VERSION 1.0
        SOURCES
            acoolcppitem.cpp acoolcppitem.h
    )
    CONFIG += qmltypes
    QML_IMPORT_NAME = MyItems
    QML_IMPORT_MAJOR_VERSION = 1

    Si no se puede acceder al archivo de cabecera en el que se declara la clase desde la ruta de inclusión de tu proyecto, es posible que tengas que modificar dicha ruta para que se pueda compilar el código de registro generado.

    INCLUDEPATH += MyItems

    Consulta «Definición de tipos QML desde C++» y «Compilación de una aplicación QML» para obtener más información.

  • Si el estilo que utiliza el tipo es uno de los muchos estilos que utiliza una aplicación, plantéate colocar cada estilo en un módulo independiente. De este modo, los módulos se cargarán según sea necesario.

Consideraciones sobre los estilos personalizados

A la hora de implementar su propio estilo y personalizar controles, hay algunos aspectos que debe tener en cuenta para garantizar que su aplicación ofrezca el máximo rendimiento posible.

Evita asignar un identificador a las implementaciones de los delegados de elementos de los estilos

Tal y como se explica en «Definición de un estilo», cuando implementas tu propio estilo para un control, partes de la plantilla correspondiente a ese control. Por ejemplo, el método ` Button.qml ` de un estilo tendrá una estructura similar a esta:

T.Button {
    // ...

    background: Rectangle {
        // ...
    }

    contentItem: Text {
        // ...
    }

    // ...
}

Cuando utilices un botón (Button) en tu aplicación, se crearán los elementos « background » y « contentItem », que se vincularán al elemento raíz « Button »:

// Creates the Button root item, the Rectangle background,
// and the Text contentItem.
Button {
    text: qsTr("Confirm")
}

Supongamos que, a continuación, necesitas realizar una personalización puntual del botón (tal y como se explica en «Personalización de un control»):

import QtQuick
import QtQuick.Controls.Basic

ApplicationWindow {
    width: 400
    height: 400
    visible: true

    Button {
        id: button
        text: "A Special Button"
        background: Rectangle {
            implicitWidth: 100
            implicitHeight: 40
            color: button.down ? "#d6d6d6" : "#f6f6f6"
            border.color: "#26282a"
            border.width: 1
            radius: 4
        }
    }
}

En QML, esto normalmente daría lugar a la creación tanto de la implementación predeterminada background como del elemento personalizado puntual background. Los controles de Qt Quick utilizan una técnica que evita la creación de ambos elementos y, en su lugar, solo crea el elemento personalizado background, lo que mejora considerablemente el rendimiento en la creación de controles.

Esta técnica se basa en la ausencia de un identificador (id) en la implementación del estilo de ese elemento. Si se asigna un identificador, la técnica no funciona y se crearán ambos elementos. Por ejemplo, puede resultar tentador asignar un identificador a background o contentItem para que otros objetos del archivo puedan hacer referencia a esos elementos:

T.Button {
    // ...

    background: Rectangle {
        id: backgroundRect
        // ...
    }

    contentItem: Text {
        // Use backgroundRect in some way...
    }

    // ...
}

Con este código, cada vez que se cree una instancia de Button con un fondo personalizado, se crearán ambos fondos, lo que dará lugar a un rendimiento de creación subóptimo.

Antes de Qt 5.15, el fondo antiguo y en desuso se eliminaba para liberar los recursos asociados a él. Sin embargo, dado que el control no es propietario de los elementos, no debería eliminarlos. A partir de Qt 5.15, los elementos antiguos ya no se eliminan, por lo que el elemento « backgroundRect » permanecerá más tiempo del necesario —normalmente hasta que se cierre la aplicación—. Aunque el elemento antiguo quedará oculto, visualmente desvinculado del control y eliminado del árbol de accesibilidad, es importante tener en cuenta el tiempo de creación y el consumo de memoria de estos elementos no utilizados a la hora de asignar un identificador en este contexto.

Evita las asignaciones imperativas de elementos personalizados

La técnica mencionada en la sección anterior solo funciona cuando un elemento se asigna de forma declarativa por primera vez, por lo que las asignaciones imperativas darán lugar a elementos huérfanos. Utiliza siempre enlaces declarativos para asignar elementos personalizados siempre que sea posible.

No importe QtQuick.Controls en las implementaciones de QML

Al escribir el código QML para la implementación de un control en tu estilo, es importante no importar QtQuick.Controls. Si lo haces, el compilador de QML no podrá compilar el código QML.

Implementa los tipos utilizados por otros tipos

Supongamos que estás utilizando ScrollViews en tu aplicación y decides que quieres personalizar sus barras de desplazamiento. Es tentador limitarse a implementar un archivo personalizado ScrollBar.qml y dejar que ScrollView detecte automáticamente el archivo ScrollBar personalizado. Sin embargo, esto no funcionará. Debes implementar tanto ScrollBar.qml como ScrollView.qml.

Propiedades asociadas

Es habitual que un estilo tenga ciertas propiedades o atributos que se aplican a todos los controles. Las propiedades adjuntas son una forma estupenda de ampliar un elemento en QML sin tener que modificar ningún código C++ existente perteneciente a ese elemento. Por ejemplo, tanto el estilo «Material» como el «Universal» tienen una propiedad de tema adjunta que controla si un elemento y sus hijos se representarán con un tema claro u oscuro.

A modo de ejemplo, añadamos una propiedad adjunta que controle la elevación. Nuestro estilo ilustrará la elevación con una sombra proyectada; cuanto mayor sea la elevación, mayor será la sombra.

El primer paso es crear una nueva aplicación de controles « Qt Quick » en Qt Creator o en Qt Extension for Visual Studio Code. A continuación, añadimos un tipo de C++ (en Qt Creator o en Qt Extension for Visual Studio Code) que almacena la elevación. Dado que el tipo se utilizará para todos los controles compatibles con nuestro estilo, y porque es posible que queramos añadir otras propiedades adjuntas más adelante, lo llamaremos «MyStyle». Aquí está MyStyle.h:

#ifndef MYSTYLE_H
#define MYSTYLE_H

#include <QObject>
#include <QtQml>

class MyStyle : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int elevation READ elevation WRITE setElevation NOTIFY elevationChanged)

public:
    explicit MyStyle(QObject *parent = nullptr);

    static MyStyle *qmlAttachedProperties(QObject *object);

    int elevation() const;
    void setElevation(int elevation);

signals:
    void elevationChanged();

private:
    int m_elevation;
};

QML_DECLARE_TYPEINFO(MyStyle, QML_HAS_ATTACHED_PROPERTIES)

#endif // MYSTYLE_H

MyStyle.cpp:

#include "mystyle.h"

MyStyle::MyStyle(QObject *parent) :
    QObject(parent),
    m_elevation(0)
{
}

MyStyle *MyStyle::qmlAttachedProperties(QObject *object)
{
    return new MyStyle(object);
}

int MyStyle::elevation() const
{
    return m_elevation;
}

void MyStyle::setElevation(int elevation)
{
    if (elevation == m_elevation)
        return;

    m_elevation = elevation;
    emit elevationChanged();
}

El tipo « MyStyle » es especial en el sentido de que no debe instanciarse, sino que debe utilizarse por sus propiedades asociadas. Por ese motivo, lo registramos de la siguiente manera en « main.cpp »:

#include <QGuiApplication>
#include <QQmlApplicationEngine>

#include "mystyle.h"

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    qmlRegisterUncreatableType<MyStyle>("MyStyle", 1, 0, "MyStyle", "MyStyle is an attached property");

    QQmlApplicationEngine engine;
    // Make the directory containing our style known to the QML engine.
    engine.addImportPath(":/");
    engine.load(QUrl(QLatin1String("qrc:/main.qml")));

    return app.exec();
}

A continuación, copiamos « Button.qml » del estilo «Basic» en $QTDIR/qml/QtQuick/Controls/Basic/ a una nueva carpeta « myproject » en el directorio de nuestro proyecto. Añadimos el archivo « Button.qml » recién copiado a qml.qrc, que es el archivo de recursos que contiene nuestros archivos QML.

A continuación, añadimos una sombra al delegado background del botón:

// ...
import QtQuick.Effects
import MyStyle
// ...

background: Rectangle {
    // ...

    layer.enabled: control.enabled && control.MyStyle.elevation > 0
    layer.effect: MultiEffect {
        shadowEnabled: true
        shadowHorizontalOffset: 3
        shadowVerticalOffset: 3
        shadowColor: control.visualFocus ? "#330066ff" : "#aaaaaa"
        shadowBlur: control.pressed ? 0.8 : 0.4
    }
}

Ten en cuenta que:

  • No nos molestamos en utilizar la sombra cuando la elevación es 0
  • Cambiamos el color de la sombra dependiendo de si el botón tiene el foco o no
  • Hacemos que el tamaño de la sombra dependa de la elevación

Para probar la propiedad adjunta, creamos un « Row » con dos botones en « main.qml »:

import QtQuick
import QtQuick.Controls

import MyStyle 1.0

ApplicationWindow {
    id: window
    width: 400
    height: 400
    visible: true

    Row {
        spacing: 20
        anchors.centerIn: parent

        Button {
            text: "Button 1"
        }
        Button {
            text: "Button 2"
            MyStyle.elevation: 10
        }
    }
}

Uno de los botones no tiene elevación, y el otro tiene una elevación de 10.

Una vez hecho esto, podemos ejecutar nuestro ejemplo. Para indicar a la aplicación que utilice nuestro nuevo estilo, pasamos -style MyStyle como argumento de la aplicación, aunque hay muchas formas de especificar el estilo que se va a utilizar.

El resultado final:

Botones con diseño personalizado

Ten en cuenta que la instrucción « import MyStyle 1.0 » solo es necesaria porque estamos utilizando la propiedad adjunta que pertenece a MyStyle. Ambos botones utilizarán nuestro estilo personalizado, incluso si elimináramos la importación.

Referencia de personalización

Los siguientes fragmentos de código muestran ejemplos en los que se han personalizado los controles del estilo «Basic» utilizando el mismo enfoque que el descrito en la sección «Personalización de un control ». El código puede utilizarse como punto de partida para implementar una apariencia personalizada.

Nota: Los estilos de macOS y Windows no son adecuados para la personalización. En su lugar, se recomienda basar siempre un control personalizado en un único estilo que esté disponible en todas las plataformas, por ejemplo, el estilo «Básico», «Fusion», «Imagine», «Material» o «Universal». De este modo, se garantiza que el aspecto sea siempre el mismo, independientemente del estilo con el que se ejecute la aplicación. Para saber cómo utilizar un estilo diferente, consulta «Uso de estilos en los controles de Qt Quick ». También puedes crear tu propio estilo.

Nota: Al modificar el tamaño de los controles, el tamaño real del contenido suele permanecer igual. Por ejemplo, algunos estilos pueden hacer que su botón ocupe los límites del control, pero centren horizontal y/o verticalmente el indicador de selección y el texto de un « CheckBox ». Si no se desea el comportamiento predeterminado de redimensionamiento, sobrescriba los delegados correspondientes.

Personalización de ApplicationWindow

ApplicationWindow consta de un único elemento visual: background.

import QtQuick
import QtQuick.Controls.Basic

ApplicationWindow {
    visible: true

    background: Rectangle {
        gradient: Gradient {
            GradientStop { position: 0; color: "#ffffff" }
            GradientStop { position: 1; color: "#c1bbf9" }
        }
    }
}

Personalización de BusyIndicator

BusyIndicator Consta de dos elementos visuales: background y contentItem.

Indicador de actividad con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

BusyIndicator {
    id: control

    contentItem: Item {
        implicitWidth: 64
        implicitHeight: 64

        Item {
            id: item
            x: parent.width / 2 - 32
            y: parent.height / 2 - 32
            width: 64
            height: 64
            opacity: control.running ? 1 : 0

            Behavior on opacity {
                OpacityAnimator {
                    duration: 250
                }
            }

            RotationAnimator {
                target: item
                running: control.visible && control.running
                from: 0
                to: 360
                loops: Animation.Infinite
                duration: 1250
            }

            Repeater {
                id: repeater
                model: 6

                Rectangle {
                    id: delegate
                    x: item.width / 2 - width / 2
                    y: item.height / 2 - height / 2
                    implicitWidth: 10
                    implicitHeight: 10
                    radius: 5
                    color: "#21be2b"

                    required property int index

                    transform: [
                        Translate {
                            y: -Math.min(item.width, item.height) * 0.5 + 5
                        },
                        Rotation {
                            angle: delegate.index / repeater.count * 360
                            origin.x: 5
                            origin.y: 5
                        }
                    ]
                }
            }
        }
    }
}

Personalización del botón

El botón consta de dos elementos visuales: background y contentItem.

Botón con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

Button {
    id: control
    text: qsTr("Button")

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        elide: Text.ElideRight
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        border.color: control.down ? "#17a81a" : "#21be2b"
        border.width: 1
        radius: 2
    }
}

Personalización de la casilla de selección

CheckBox consta de tres elementos visuales: background, contentItem y indicator.

Casilla de selección con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

CheckBox {
    id: control
    text: qsTr("CheckBox")
    checked: true

    indicator: Rectangle {
        ancho implícito: 26
        alto implícito: 26
       x: control.leftPadding
        y: parent.height / 2 - height / 2
        radius: 3
        border.color: control.down? "#17a81a": "#21be2b"

        Rectangle {
            ancho: 14
            alto: 14
           x: 6
            y: 6
            radius: 2
            color: control.down? "#17a81a": "#21be2b"
            visible: control.checked
        }
    }

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled? 1.0: 0.3
       color: control.down? "#17a81a": "#21be2b"
        verticalAlignment: Text.AlignVCenter
        leftPadding: control.indicator.width + control.spacing
    }
}

Personalización de CheckDelegate

CheckDelegate consta de tres elementos visuales: background, contentItem y indicator.

Delegado de comprobación con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

CheckDelegate {
    id: control
    text: qsTr("CheckDelegate")
    checked: true

    contentItem: Text {
        rightPadding: control.indicator.width + control.spacing
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter
    }

    indicator: Rectangle {
        implicitWidth: 26
        implicitHeight: 26
        x: control.width - width - control.rightPadding
        y: control.topPadding + control.availableHeight / 2 - height / 2
        radius: 3
        color: "transparent"
        border.color: control.down ? "#17a81a" : "#21be2b"

        Rectangle {
            width: 14
            height: 14
            x: 6
            y: 6
            radius: 2
            color: control.down ? "#17a81a" : "#21be2b"
            visible: control.checked
        }
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        visible: control.down || control.highlighted
        color: control.down ? "#bdbebf" : "#eeeeee"
    }
}

Personalización de ComboBox

ComboBox consta de background, contentItem, popup, indicator y delegate.

Cuadro combinado con estilo personalizado

pragma ComponentBehavior: Bound

import QtQuick
import QtQuick.Controls.Basic

ComboBox {
    id: control
    model: ["First", "Second", "Third"]

    delegate: ItemDelegate {
        id: delegate

        required property var model
        required property int index

        width: control.width
        contentItem: Text {
            text: delegate.model[control.textRole]
            color: "#21be2b"
            font: control.font
            elide: Text.ElideRight
            verticalAlignment: Text.AlignVCenter
        }
        highlighted: control.highlightedIndex === index
    }

    indicator: Canvas {
        id: canvas
        x: control.width - width - control.rightPadding
        y: control.topPadding + (control.availableHeight - height) / 2
        width: 12
        height: 8
        contextType: "2d"

        Connections {
            target: control
            function onPressedChanged() { canvas.requestPaint(); }
        }

        onPaint: {
            context.reset();
            context.moveTo(0, 0);
            context.lineTo(width, 0);
            context.lineTo(width / 2, height);
            context.closePath();
            context.fillStyle = control.pressed ? "#17a81a" : "#21be2b";
            context.fill();
        }
    }

    contentItem: Text {
        leftPadding: 0
        rightPadding: control.indicator.width + control.spacing

        text: control.displayText
        font: control.font
        color: control.pressed ? "#17a81a" : "#21be2b"
        verticalAlignment: Text.AlignVCenter
        elide: Text.ElideRight
    }

    background: Rectangle {
        implicitWidth: 120
        implicitHeight: 40
        border.color: control.pressed ? "#17a81a" : "#21be2b"
        border.width: control.visualFocus ? 2 : 1
        radius: 2
    }

    popup: Popup {
        y: control.height - 1
        width: control.width
        height: Math.min(contentItem.implicitHeight, control.Window.height - topMargin - bottomMargin)
        padding: 1

        contentItem: ListView {
            clip: true
            implicitHeight: contentHeight
            model: control.popup.visible ? control.delegateModel : null
            currentIndex: control.highlightedIndex

            ScrollIndicator.vertical: ScrollIndicator { }
        }

        background: Rectangle {
            border.color: "#21be2b"
            radius: 2
        }
    }
}

Tal y como se explica en ComboBox Model Roles, ComboBox admite varios tipos de modelos.

Dado que todos los modelos proporcionan una propiedad anónima con modelData, la siguiente expresión recupera el texto correcto en todos los casos:

text: model[control.textRole]

Cuando se proporciona un textRole específico y un modelo con datos estructurados que ofrece el rol seleccionado, esta expresión es una búsqueda de propiedad normal. Cuando se proporciona un modelo con datos singulares, como una lista de cadenas, y un textRole vacío, esta expresión recupera el modelData.

Personalización de DelayButton

DelayButton consta de dos elementos visuales: background y contentItem.

Botón de retardo con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

DelayButton {
    id: control
    checked: true
    text: qsTr("Delay\nButton")

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: "white"
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        elide: Text.ElideRight
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 100
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        radius: size / 2

        readonly property real size: Math.min(control.width, control.height)
        width: size
        height: size
        anchors.centerIn: parent

        Canvas {
            id: canvas
            anchors.fill: parent

            Connections {
                target: control
                function onProgressChanged() { canvas.requestPaint(); }
            }

            onPaint: {
                var ctx = getContext("2d")
                ctx.clearRect(0, 0, width, height)
                ctx.strokeStyle = "white"
                ctx.lineWidth = parent.size / 20
                ctx.beginPath()
                var startAngle = Math.PI / 5 * 3
                var endAngle = startAngle + control.progress * Math.PI / 5 * 9
                ctx.arc(width / 2, height / 2, width / 2 - ctx.lineWidth / 2 - 2, startAngle, endAngle)
                ctx.stroke()
            }
        }
    }
}

Personalización de Dial

El Dial consta de dos elementos visuales: background y handle.

Esfera con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

Dial {
    id: control
    background: Rectangle {
        x: control.width / 2 - width / 2
        y: control.height / 2 - height / 2
        implicitWidth: 140
        implicitHeight: 140
        width: Math.max(64, Math.min(control.width, control.height))
        height: width
        color: "transparent"
        radius: width / 2
        border.color: control.pressed ? "#17a81a" : "#21be2b"
        opacity: control.enabled ? 1 : 0.3
    }

    handle: Rectangle {
        id: handleItem
        x: control.background.x + control.background.width / 2 - width / 2
        y: control.background.y + control.background.height / 2 - height / 2
        width: 16
        height: 16
        color: control.pressed ? "#17a81a" : "#21be2b"
        radius: 8
        antialiasing: true
        opacity: control.enabled ? 1 : 0.3
        transform: [
            Translate {
                y: -Math.min(control.background.width, control.background.height) * 0.4 + handleItem.height / 2
            },
            Rotation {
                angle: control.angle
                origin.x: handleItem.width / 2
                origin.y: handleItem.height / 2
            }
        ]
    }
}

Personalización de DoubleSpinBox

DoubleSpinBox se puede personalizar de la misma forma que Button.

Personalización de Drawer

El cajón puede incluir un elemento de « background » visual.

background: Rectangle {
    Rectangle {
        x: parent.width - 1
        width: 1
        height: parent.height
        color: "#21be2b"
    }
}

Personalización del marco

El marco consta de un elemento visual: « background ».

Marco con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

Frame {
    background: Rectangle {
        color: "transparent"
        border.color: "#21be2b"
        radius: 2
    }

    Label {
        text: qsTr("Content goes here!")
    }
}

Personalización de GroupBox

GroupBox consta de dos elementos visuales: background y label.

Cuadro de grupo con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

GroupBox {
    id: control
    title: qsTr("GroupBox")

    background: Rectangle {
        y: control.topPadding - control.bottomPadding
        width: parent.width
        height: parent.height - control.topPadding + control.bottomPadding
        color: "transparent"
        border.color: "#21be2b"
        radius: 2
    }

    label: Label {
        x: control.leftPadding
        width: control.availableWidth
        text: control.title
        color: "#21be2b"
        elide: Text.ElideRight
    }

    Label {
        text: qsTr("Content goes here!")
    }
}

Personalización de ItemDelegate

ItemDelegate consiste en dos elementos visuales: background y contentItem.

Delegado de elemento con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

ItemDelegate {
    id: control
    text: qsTr("ItemDelegate")

    contentItem: Text {
        rightPadding: control.spacing
        text: control.text
        font: control.font
        color: control.enabled ? (control.down ? "#17a81a" : "#21be2b") : "#bdbebf"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#dddedf" : "#eeeeee"

        Rectangle {
            width: parent.width
            height: 1
            color: control.down ? "#17a81a" : "#21be2b"
            anchors.bottom: parent.bottom
        }
    }
}

Personalización de Label

La etiqueta puede tener un elemento visual de tipo « background ».

Etiqueta con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

Label {
    text: qsTr("Label")
    color: "#21be2b"
}

Personalización de «Menu»

Menú con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

Menu {
    id: menu

    Action { text: qsTr("Tool Bar"); checkable: true }
    Action { text: qsTr("Side Bar"); checkable: true; checked: true }
    Action { text: qsTr("Status Bar"); checkable: true; checked: true }

    MenuSeparator {
        contentItem: Rectangle {
            implicitWidth: 200
            implicitHeight: 1
            color: "#21be2b"
        }
    }

    Menu {
        title: qsTr("Advanced")
        // ...
    }

    topPadding: 2
    bottomPadding: 2

    delegate: MenuItem {
        id: menuItem
        implicitWidth: 200
        implicitHeight: 40

        arrow: Canvas {
            x: parent.width - width
            implicitWidth: 40
            implicitHeight: 40
            visible: menuItem.subMenu
            onPaint: {
                var ctx = getContext("2d")
                ctx.fillStyle = menuItem.highlighted ? "#ffffff" : "#21be2b"
                ctx.moveTo(15, 15)
                ctx.lineTo(width - 15, height / 2)
                ctx.lineTo(15, height - 15)
                ctx.closePath()
                ctx.fill()
            }
        }

        indicator: Item {
            implicitWidth: 40
            implicitHeight: 40
            Rectangle {
                width: 26
                height: 26
                anchors.centerIn: parent
                visible: menuItem.checkable
                border.color: "#21be2b"
                radius: 3
                Rectangle {
                    width: 14
                    height: 14
                    anchors.centerIn: parent
                    visible: menuItem.checked
                    color: "#21be2b"
                    radius: 2
                }
            }
        }

        contentItem: Text {
            leftPadding: menuItem.indicator.width
            rightPadding: menuItem.arrow.width
            text: menuItem.text
            font: menuItem.font
            opacity: enabled ? 1.0 : 0.3
            color: menuItem.highlighted ? "#ffffff" : "#21be2b"
            horizontalAlignment: Text.AlignLeft
            verticalAlignment: Text.AlignVCenter
            elide: Text.ElideRight
        }

        background: Rectangle {
            implicitWidth: 200
            implicitHeight: 40
            opacity: enabled ? 1 : 0.3
            color: menuItem.highlighted ? "#21be2b" : "transparent"
        }
    }

    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 40
        color: "#ffffff"
        border.color: "#21be2b"
        radius: 2
    }
}

Personalización de la barra de menús

MenuBar puede tener un elemento visual background, y MenuBarItem consta de dos elementos visuales: background y contentItem.

Barra de menús personalizada con los menús «Archivo» y «Edición»

import QtQuick
import QtQuick.Controls.Basic

MenuBar {
    id: menuBar

    Menu { title: qsTr("File") }
    Menu { title: qsTr("Edit") }
    Menu { title: qsTr("View") }
    Menu { title: qsTr("Help") }

    delegate: MenuBarItem {
        id: menuBarItem

        contentItem: Text {
            text: menuBarItem.text
            font: menuBarItem.font
            opacity: enabled ? 1.0 : 0.3
            color: menuBarItem.highlighted ? "#ffffff" : "#21be2b"
            horizontalAlignment: Text.AlignLeft
            verticalAlignment: Text.AlignVCenter
            elide: Text.ElideRight
        }

        background: Rectangle {
            implicitWidth: 40
            implicitHeight: 40
            opacity: enabled ? 1 : 0.3
            color: menuBarItem.highlighted ? "#21be2b" : "transparent"
        }
    }

    background: Rectangle {
        implicitWidth: 40
        implicitHeight: 40
        color: "#ffffff"

        Rectangle {
            color: "#21be2b"
            width: parent.width
            height: 1
            anchors.bottom: parent.bottom
        }
    }
}

Personalización de PageIndicator

PageIndicator consiste en un background, un contentItem y un delegate.

Indicador de páginas con diseño personalizado que muestra varias páginas

import QtQuick
import QtQuick.Controls.Basic

PageIndicator {
    id: control
    count: 5
    currentIndex: 2

    delegate: Rectangle {
        implicitWidth: 8
        implicitHeight: 8

        radius: width / 2
        color: "#21be2b"

        opacity: index === control.currentIndex ? 0.95 : pressed ? 0.7 : 0.45

        required property int index

        Behavior on opacity {
            OpacityAnimator {
                duration: 100
            }
        }
    }
}

Personalización del panel

El panel consta de un background.

Panel con diseño personalizado y fondo decorativo

import QtQuick
import QtQuick.Controls.Basic

Pane {
    background: Rectangle {
        color: "#eeeeee"
    }

    Label {
        text: qsTr("Content goes here!")
    }
}

Personalización de la ventana emergente

La ventana emergente consta de un background y un contentItem.

Ventana emergente con diseño personalizado, con borde y sombra

import QtQuick
import QtQuick.Controls.Basic

Popup {
    id: popup
    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 200
        border.color: "#444"
    }
    contentItem: Column {}
}

Personalización de la barra de progreso

ProgressBar Consta de dos elementos visuales: background y contentItem.

Barra de progreso con diseño personalizado que muestra el grado de finalización

import QtQuick
import QtQuick.Controls.Basic

ProgressBar {
    id: control
    value: 0.5
    padding: 2

    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 6
        color: "#e6e6e6"
        radius: 3
    }

    contentItem: Item {
        implicitWidth: 200
        implicitHeight: 4

        // Progress indicator for determinate state.
        Rectangle {
            width: control.visualPosition * parent.width
            height: parent.height
            radius: 2
            color: "#17a81a"
            visible: !control.indeterminate
        }

        // Scrolling animation for indeterminate state.
        Item {
            anchors.fill: parent
            visible: control.indeterminate
            clip: true

            Row {
                spacing: 20

                Repeater {
                    model: control.width / 40 + 1

                    Rectangle {
                        color: "#17a81a"
                        width: 20
                        height: control.height
                    }
                }
                XAnimator on x {
                    from: 0
                    to: -40
                    loops: Animation.Infinite
                    running: control.indeterminate
                }
            }
        }
    }
}

En la imagen anterior, el «contentItem» también está animado para representar el estado de la barra de progreso « indeterminate ».

Personalización de RadioButton

RadioButton consiste en tres elementos visuales: background, contentItem y indicator.

Botón de opción con estilo personalizado cuando está seleccionado

import QtQuick
import QtQuick.Controls.Basic

RadioButton {
    id: control
    text: qsTr("RadioButton")
    checked: true

    indicator: Rectangle {
        implicitWidth: 26
        implicitHeight: 26
        x: control.leftPadding
        y: parent.height / 2 - height / 2
        radius: 13
        border.color: control.down ? "#17a81a" : "#21be2b"

        Rectangle {
            width: 14
            height: 14
            x: 6
            y: 6
            radius: 7
            color: control.down ? "#17a81a" : "#21be2b"
            visible: control.checked
        }
    }

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        verticalAlignment: Text.AlignVCenter
        leftPadding: control.indicator.width + control.spacing
    }
}

Personalización de RadioDelegate

RadioDelegate consta de tres elementos visuales: background, contentItem y indicator.

Delegado de radio con estilo personalizado en una lista

import QtQuick
import QtQuick.Controls.Basic

RadioDelegate {
    id: control
    text: qsTr("RadioDelegate")
    checked: true

    contentItem: Text {
        rightPadding: control.indicator.width + control.spacing
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter
    }

    indicator: Rectangle {
        implicitWidth: 26
        implicitHeight: 26
        x: control.width - width - control.rightPadding
        y: parent.height / 2 - height / 2
        radius: 13
        color: "transparent"
        border.color: control.down ? "#17a81a" : "#21be2b"

        Rectangle {
            width: 14
            height: 14
            x: 6
            y: 6
            radius: 7
            color: control.down ? "#17a81a" : "#21be2b"
            visible: control.checked
        }
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        visible: control.down || control.highlighted
        color: control.down ? "#bdbebf" : "#eeeeee"
    }
}

Personalización de RangeSlider

RangeSlider consiste en tres elementos visuales: background, first.handle y second.handle.

Control deslizante de rango con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

RangeSlider {
    id: control
    first.value: 0.25
    second.value: 0.75

    background: Rectangle {
        x: control.leftPadding
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 200
        implicitHeight: 4
        width: control.availableWidth
        height: implicitHeight
        radius: 2
        color: "#bdbebf"

        Rectangle {
            x: control.first.visualPosition * parent.width
            width: control.second.visualPosition * parent.width - x
            height: parent.height
            color: "#21be2b"
            radius: 2
        }
    }

    first.handle: Rectangle {
        x: control.leftPadding + control.first.visualPosition * (control.availableWidth - width)
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 26
        implicitHeight: 26
        radius: 13
        color: control.first.pressed ? "#f0f0f0" : "#f6f6f6"
        border.color: "#bdbebf"
    }

    second.handle: Rectangle {
        x: control.leftPadding + control.second.visualPosition * (control.availableWidth - width)
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 26
        implicitHeight: 26
        radius: 13
        color: control.second.pressed ? "#f0f0f0" : "#f6f6f6"
        border.color: "#bdbebf"
    }
}

Personalización de RoundButton

RoundButton se puede personalizar de la misma manera que Button.

Personalización de ScrollBar

ScrollBar consta de dos elementos visuales: background y contentItem.

Barra de desplazamiento con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

ScrollBar {
    id: control
    size: 0.3
    position: 0.2
    active: true
    orientation: Qt.Vertical

    contentItem: Rectangle {
        implicitWidth: 6
        implicitHeight: 100
        radius: width / 2
        color: control.pressed ? "#81e889" : "#c2f4c6"
        // Hide the ScrollBar when it's not needed.
        opacity: control.policy === ScrollBar.AlwaysOn || (control.active && control.size < 1.0) ? 0.75 : 0

        // Animate the changes in opacity (default duration is 250 ms).
        Behavior on opacity {
            NumberAnimation {}
        }
    }
}

Personalización de ScrollIndicator

ScrollIndicator consta de dos elementos visuales: background y contentItem.

Indicador de desplazamiento con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

ScrollIndicator {
    id: control
    size: 0.3
    position: 0.2
    active: true
    orientation: Qt.Vertical

    contentItem: Rectangle {
        implicitWidth: 2
        implicitHeight: 100
        color: "#c2f4c6"
    }
}

Personalización de ScrollView

ScrollView consiste en un elemento « background » y en barras de desplazamiento horizontales y verticales.

Vista de desplazamiento con estilo personalizado

ScrollView {
    id: control

    width: 200
    height: 200
    focus: true

    Label {
        text: "ABC"
        font.pixelSize: 224
    }

    ScrollBar.vertical: ScrollBar {
        parent: control
        x: control.mirrored ? 0 : control.width - width
        y: control.topPadding
        height: control.availableHeight
        active: control.ScrollBar.horizontal.active
    }

    ScrollBar.horizontal: ScrollBar {
        parent: control
        x: control.leftPadding
        y: control.height - height
        width: control.availableWidth
        active: control.ScrollBar.vertical.active
    }

    background: Rectangle {
        border.color: control.activeFocus ? "#21be2b" : "#bdbebf"
    }
}

Personalización de «Slider»

El Slider consta de dos elementos visuales: background y handle.

Control deslizante con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

Slider {
    id: control
    value: 0.5

    background: Rectangle {
        x: control.leftPadding
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 200
        implicitHeight: 4
        width: control.availableWidth
        height: implicitHeight
        radius: 2
        color: "#bdbebf"

        Rectangle {
            width: control.visualPosition * parent.width
            height: parent.height
            color: "#21be2b"
            radius: 2
        }
    }

    handle: Rectangle {
        x: control.leftPadding + control.visualPosition * (control.availableWidth - width)
        y: control.topPadding + control.availableHeight / 2 - height / 2
        implicitWidth: 26
        implicitHeight: 26
        radius: 13
        color: control.pressed ? "#f0f0f0" : "#f6f6f6"
        border.color: "#bdbebf"
    }
}

Personalización de SpinBox

SpinBox consta de cuatro elementos visuales: « background », « contentItem », « up indicator » y « down indicator ».

Cuadro de selección con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

SpinBox {
    id: control
    value: 50
    editable: true

    contentItem: TextInput {
        z: 2
        text: control.textFromValue(control.value, control.locale)

        font: control.font
        color: "#21be2b"
        selectionColor: "#21be2b"
        selectedTextColor: "#ffffff"
        horizontalAlignment: Qt.AlignHCenter
        verticalAlignment: Qt.AlignVCenter

        readOnly: !control.editable
        validator: control.validator
        inputMethodHints: Qt.ImhFormattedNumbersOnly
    }

    up.indicator: Rectangle {
        x: control.mirrored ? 0 : parent.width - width
        height: parent.height
        implicitWidth: 40
        implicitHeight: 40
        color: control.up.pressed ? "#e4e4e4" : "#f6f6f6"
        border.color: enabled ? "#21be2b" : "#bdbebf"

        Text {
            text: "+"
            font.pixelSize: control.font.pixelSize * 2
            color: "#21be2b"
            anchors.fill: parent
            fontSizeMode: Text.Fit
            horizontalAlignment: Text.AlignHCenter
            verticalAlignment: Text.AlignVCenter
        }
    }

    down.indicator: Rectangle {
        x: control.mirrored ? parent.width - width : 0
        height: parent.height
        implicitWidth: 40
        implicitHeight: 40
        color: control.down.pressed ? "#e4e4e4" : "#f6f6f6"
        border.color: enabled ? "#21be2b" : "#bdbebf"

        Text {
            text: "-"
            font.pixelSize: control.font.pixelSize * 2
            color: "#21be2b"
            anchors.fill: parent
            fontSizeMode: Text.Fit
            horizontalAlignment: Text.AlignHCenter
            verticalAlignment: Text.AlignVCenter
        }
    }

    background: Rectangle {
        implicitWidth: 140
        border.color: "#bdbebf"
    }
}

La personalización de SplitView

SplitView consiste en un delegado visual handle.

Vista dividida con estilo personalizado

SplitView {
    id: splitView
    anchors.fill: parent

    handle: Rectangle {
        implicitWidth: 4
        implicitHeight: 4
        color: SplitHandle.pressed ? "#81e889"
            : (SplitHandle.hovered ? Qt.lighter("#c2f4c6", 1.1) : "#c2f4c6")
    }

    Rectangle {
        implicitWidth: 150
        color: "#444"
    }
    Rectangle {
        implicitWidth: 50
        color: "#666"
    }
}

La personalización de StackView

StackView puede incluir un elemento visual de tipo « background », y permite personalizar las transiciones que se utilizan para las operaciones «push», «pop» y «replace».

import QtQuick
import QtQuick.Controls.Basic

StackView {
    id: control

    popEnter: Transition {
        XAnimator {
            from: (control.mirrored ? -1 : 1) * -control.width
            to: 0
            duration: 400
            easing.type: Easing.OutCubic
        }
    }

    popExit: Transition {
        XAnimator {
            from: 0
            to: (control.mirrored ? -1 : 1) * control.width
            duration: 400
            easing.type: Easing.OutCubic
        }
    }
}

Personalización de SwipeDelegate

SwipeDelegate consta de seis elementos visuales: background, contentItem, indicator, swipe.left, swipe.right y swipe.behind.

Delegado de deslizamiento con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

SwipeDelegate {
    id: control
    text: qsTr("SwipeDelegate")

    Component {
        id: component

        Rectangle {
            color: SwipeDelegate.pressed ? "#333" : "#444"
            width: parent.width
            height: parent.height
            clip: true

            Label {
                text: qsTr("Press me!")
                color: "#21be2b"
                anchors.centerIn: parent
            }
        }
    }

    swipe.left: component
    swipe.right: component

    contentItem: Text {
        text: control.text
        font: control.font
        color: control.enabled ? (control.down ? "#17a81a" : "#21be2b") : "#bdbebf"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter

        Behavior on x {
            enabled: !control.down
            NumberAnimation {
                easing.type: Easing.InOutCubic
                duration: 400
            }
        }
    }
}

Personalización de SwipeView

SwipeView puede incluir un elemento visual background. La navegación se implementa mediante contentItem.

import QtQuick
import QtQuick.Controls.Basic

SwipeView {
    id: control

    background: Rectangle {
        color: "#eeeeee"
    }
}

Personalización de Switch

Switch consta de tres elementos visuales: background, contentItem y indicator.

Interruptor con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

Switch {
    id: control
    text: qsTr("Switch")

    indicator: Rectangle {
        implicitWidth: 48
        implicitHeight: 26
        x: control.leftPadding
        y: parent.height / 2 - height / 2
        radius: 13
        color: control.checked ? "#17a81a" : "#ffffff"
        border.color: control.checked ? "#17a81a" : "#cccccc"

        Rectangle {
            x: control.checked ? parent.width - width : 0
            width: 26
            height: 26
            radius: 13
            color: control.down ? "#cccccc" : "#ffffff"
            border.color: control.checked ? (control.down ? "#17a81a" : "#21be2b") : "#999999"
        }
    }

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        verticalAlignment: Text.AlignVCenter
        leftPadding: control.indicator.width + control.spacing
    }
}

Personalización de SwitchDelegate

SwitchDelegate consta de tres elementos visuales: background, contentItem y indicator.

Delegado de conmutador con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

SwitchDelegate {
    id: control
    text: qsTr("SwitchDelegate")
    checked: true

    contentItem: Text {
        rightPadding: control.indicator.width + control.spacing
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        elide: Text.ElideRight
        verticalAlignment: Text.AlignVCenter
    }

    indicator: Rectangle {
        implicitWidth: 48
        implicitHeight: 26
        x: control.width - width - control.rightPadding
        y: parent.height / 2 - height / 2
        radius: 13
        color: control.checked ? "#17a81a" : "transparent"
        border.color: control.checked ? "#17a81a" : "#cccccc"

        Rectangle {
            x: control.checked ? parent.width - width : 0
            width: 26
            height: 26
            radius: 13
            color: control.down ? "#cccccc" : "#ffffff"
            border.color: control.checked ? (control.down ? "#17a81a" : "#21be2b") : "#999999"
        }
    }

    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        visible: control.down || control.highlighted
        color: control.down ? "#bdbebf" : "#eeeeee"
    }
}

Personalización de TabBar

TabBar consiste en dos elementos visuales: background y contentItem.

Barra de pestañas con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

TabBar {
    id: control

    background: Rectangle {
        color: "#eeeeee"
    }

    TabButton {
        text: qsTr("Home")
    }
    TabButton {
        text: qsTr("Discover")
    }
    TabButton {
        text: qsTr("Activity")
    }
}

La personalización de TabButton

TabButton Se puede personalizar de la misma manera que un botón.

Personalización de TextArea

TextArea consiste en un elemento « background ».

Área de texto con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

TextArea {
    id: control
    placeholderText: qsTr("Enter description")

    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 40
        border.color: control.enabled ? "#21be2b" : "transparent"
    }
}

Personalización de TextField

TextField consiste en un elemento « background ».

Campo de texto con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

TextField {
    id: control
    placeholderText: qsTr("Enter description")

    background: Rectangle {
        implicitWidth: 200
        implicitHeight: 40
        color: control.enabled ? "transparent" : "#353637"
        border.color: control.enabled ? "#21be2b" : "transparent"
    }
}

Personalización de ToolBar

ToolBar consiste en un elemento visual: background.

Barra de herramientas con diseño personalizado

ToolBar {
    id: control

    background: Rectangle {
        implicitHeight: 40
        color: "#eeeeee"

        Rectangle {
            width: parent.width
            height: 1
            anchors.bottom: parent.bottom
            color: "transparent"
            border.color: "#21be2b"
        }
    }

    RowLayout {
        anchors.fill: parent
        ToolButton {
            text: qsTr("Undo")
        }
        ToolButton {
            text: qsTr("Redo")
        }
    }
}

Personalización de ToolButton

ToolButton consta de dos elementos visuales: background y contentItem.

Botón de herramienta con estilo personalizado

import QtQuick
import QtQuick.Controls.Basic

ToolButton {
    id: control
    text: qsTr("ToolButton")
    width: 120

    contentItem: Text {
        text: control.text
        font: control.font
        opacity: enabled ? 1.0 : 0.3
        color: control.down ? "#17a81a" : "#21be2b"
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        elide: Text.ElideRight
    }

    background: Rectangle {
        implicitWidth: 40
        implicitHeight: 40
        color: Qt.darker("#33333333", control.enabled && (control.checked || control.highlighted) ? 1.5 : 1.0)
        opacity: enabled ? 1 : 0.3
        visible: control.down || (control.enabled && (control.checked || control.highlighted))
    }
}

Personalización de «ToolSeparator»

ToolSeparator consta de dos elementos visuales: background y contentItem.

Separador de herramientas con diseño personalizado

ToolBar {
    RowLayout {
        anchors.fill: parent

        ToolButton {
            text: qsTr("Action 1")
        }
        ToolButton {
            text: qsTr("Action 2")
        }

        ToolSeparator {
            padding: vertical ? 10 : 2
            topPadding: vertical ? 2 : 10
            bottomPadding: vertical ? 2 : 10

            contentItem: Rectangle {
                implicitWidth: parent.vertical ? 1 : 24
                implicitHeight: parent.vertical ? 24 : 1
                color: "#c3c3c3"
            }
        }

        ToolButton {
            text: qsTr("Action 3")
        }
        ToolButton {
            text: qsTr("Action 4")
        }

        Item {
            Layout.fillWidth: true
        }
    }
}

Personalización de ToolTip

ToolTip consta de dos elementos visuales: background y contentItem.

import QtQuick
import QtQuick.Controls.Basic

ToolTip {
    id: control
    text: qsTr("A descriptive tool tip of what the button does")

    contentItem: Text {
        text: control.text
        font: control.font
        color: "#21be2b"
    }

    background: Rectangle {
        border.color: "#21be2b"
    }
}

Nota: para personalizar el « attached ToolTip », debe incluirse como parte de su propio estilo. Para realizar una personalización puntual de un « ToolTip », consulte Custom Tool Tips.

Personalización de Tumbler

Tumbler consta de tres elementos visuales: background, contentItem y delegate.

Vaso con diseño personalizado

import QtQuick
import QtQuick.Controls.Basic

Tumbler {
    id: control
    model: 15

    background: Item {
        Rectangle {
            opacity: control.enabled ? 0.2 : 0.1
            border.color: "#000000"
            width: parent.width
            height: 1
            anchors.top: parent.top
        }

        Rectangle {
            opacity: control.enabled ? 0.2 : 0.1
            border.color: "#000000"
            width: parent.width
            height: 1
            anchors.bottom: parent.bottom
        }
    }

    delegate: Text {
        text: qsTr("Item %1").arg(modelData + 1)
        font: control.font
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        opacity: 1.0 - Math.abs(Tumbler.displacement) / (control.visibleItemCount / 2)

        required property var modelData
        required property int index
    }

    Rectangle {
        anchors.horizontalCenter: control.horizontalCenter
        y: control.height * 0.4
        width: 40
        height: 1
        color: "#21be2b"
    }

    Rectangle {
        anchors.horizontalCenter: control.horizontalCenter
        y: control.height * 0.6
        width: 40
        height: 1
        color: "#21be2b"
    }
}

Si quieres definir tu propio «contentItem», utiliza un « ListView » o un « PathView » como elemento raíz. Para un Tumbler con ajuste de ancho, utiliza « PathView »:

Tumbler {
    id: tumbler

    contentItem: PathView {
        id: pathView
        model: tumbler.model
        delegate: tumbler.delegate
        clip: true
        pathItemCount: tumbler.visibleItemCount + 1
        preferredHighlightBegin: 0.5
        preferredHighlightEnd: 0.5
        dragMargin: width / 2

        path: Path {
            startX: pathView.width / 2
            startY: -pathView.delegateHeight / 2
            PathLine {
                x: pathView.width / 2
                y: pathView.pathItemCount * pathView.delegateHeight - pathView.delegateHeight / 2
            }
        }

        property real delegateHeight: tumbler.availableHeight / tumbler.visibleItemCount
    }
}

Para un Tumbler sin envoltura, utiliza ListView:

Tumbler {
    id: tumbler

    contentItem: ListView {
        model: tumbler.model
        delegate: tumbler.delegate

        snapMode: ListView.SnapToItem
        highlightRangeMode: ListView.StrictlyEnforceRange
        preferredHighlightBegin: height / 2 - (height / tumbler.visibleItemCount / 2)
        preferredHighlightEnd: height / 2 + (height / tumbler.visibleItemCount / 2)
        clip: true
    }
}

Personalización de TableViewDelegate

TableViewDelegate hereda de ItemDelegate, lo que significa que se compone de dos elementos visuales: background y contentItem.

Siempre puedes asignar tu propio delegado de edición personalizado a ` editDelegate ` si tienes necesidades que van más allá de lo que ofrece el delegado de edición predeterminado.

Delegado de vista de tabla con estilo personalizado

delegate: TableViewDelegate {
    id: tableCell

    checked: column === 0 ? checkBox.checked : tableView.itemAtIndex(tableView.index(row, 0)).checked
    selected: checked

    background: Item {
        Rectangle {
            anchors.fill: parent
            anchors.margins: tableCell.current ? 3 : 1
            color: tableCell.selected ? "blue" : "white"
        }

        Rectangle {
            anchors.fill: parent
            color: "transparent"
            border.color: "darkblue"
            border.width: tableCell.current ? 2 : 0
        }
    }

    contentItem: Item {
        implicitHeight: 40
        visible: !tableCell.editing

        RowLayout {
            anchors.fill: parent

            CheckBox {
                id: checkBox
                implicitWidth: height
                Layout.fillHeight: true
                checked: false
                visible: tableCell.column === 0
            }

            Text {
                Layout.leftMargin: 4
                Layout.fillWidth: true
                Layout.fillHeight: true
                verticalAlignment: Text.AlignVCenter
                color: tableCell.selected ? "white" : "black"
                text: tableCell.model.display
            }
        }
    }

    TableView.editDelegate: FocusScope {
        width: parent.width
        height: parent.height

        TableView.onCommit: {
            let qaim = tableCell.tableView.model
            if (!qaim)
                return
            const index = qaim.index(tableCell.row, tableCell.column)
            // instead of the edit role, any custom role supported by the model can be checked
            // e.g. if (!tableCell.checked || !tableCell.model.customRole)
            if (!tableCell.checked || !tableCell.model.edit)
                return
            // instead of the edit role, any custom role supported by the model can be set
            // e.g. tableCell.model.customRole = textField.text
            tableCell.model.edit = textField.text
            tableCell.model.display = textField.text
        }

        Component.onCompleted: textField.selectAll()

        TextField {
            id: textField
            anchors.fill: parent
            text: tableCell.model.edit ?? tableCell.model.display ?? ""
            focus: true
        }
    }
}

Personalización de `HeaderViewDelegate`

HeaderViewDelegate hereda de TableViewDelegate, lo que significa que se compone de dos elementos: background y contentItem. Siempre puedes personalizarlos con cualquier elemento que desees.

Delegado de vista de cabecera con estilo personalizado

A continuación se muestra un ejemplo de personalización del delegado de vista de cabecera horizontal:

delegate: HorizontalHeaderViewDelegate {
    id: horizontalDelegate

    required property int index
    required property string modelData

    background: Rectangle {
        height: horizontalDelegate.height
        color: columnCheckBox.checked ? palette.highlight : palette.base
        radius: 8
    }

    contentItem: Item {
        implicitWidth: columnCheckBox.implicitWidth * 2
        implicitHeight: 40

        CheckBox {
            id: columnCheckBox
            anchors.centerIn: parent
            text: horizontalDelegate.modelData
            Component.onCompleted: checked = horizontalDelegate.index === 1
        }
    }
}

A continuación se muestra un ejemplo de cómo personalizar el delegado de la vista de cabecera vertical:

delegate: VerticalHeaderViewDelegate {
    id: verticalDelegate

    required property int index

    background: Rectangle {
        height: verticalDelegate.height
        color: palette.base
        border.width: rowCheckBox.checked ? 2 : 0
        border.color: palette.highlight
        radius: 8
    }

    contentItem: Item {
        implicitWidth: rowCheckBox.implicitWidth * 2
        implicitHeight: 40

        CheckBox {
            id: rowCheckBox
            anchors.centerIn: parent
            text: verticalDelegate.index + 1
            Component.onCompleted: checked = verticalDelegate.index % 3 === 0
        }
    }
}

Personalización de controles con StyleKit

El módulo StyleKit de Qt Labs proporciona un conjunto de tipos QML para aplicar estilos a los controles de Qt Quick, basado en Qt Quick Templates 2. Te permite definir un estilo visual completo para todos tus controles a partir de un único objeto Style, incluyendo soporte para temas, estilos basados en el estado y transiciones. StyleKit se encarga automáticamente de la implementación subyacente de las plantillas, lo que te permite centrarte exclusivamente en aspectos visuales como los colores, las dimensiones, los bordes y las sombras.

El módulo StyleKit de Qt Labs es un módulo de vista previa tecnológica en Qt 6.11.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.