En esta página

Buenas prácticas para QML y Qt Quick

A pesar de todas las ventajas que ofrecen QML y Qt Quick, pueden resultar complicados en determinadas situaciones. En las siguientes secciones se detallan algunas de las mejores prácticas que te ayudarán a obtener mejores resultados a la hora de desarrollar aplicaciones.

Utiliza controles integrados en lugar de controles de interfaz de usuario personalizados

Una interfaz de usuario fluida y moderna es clave para el éxito de cualquier aplicación en el mundo actual, y ahí es donde QML resulta tan útil para un diseñador o desarrollador. Qt ofrece los controles de interfaz de usuario más básicos necesarios para crear una interfaz fluida y de aspecto moderno. Se recomienda consultar esta lista de controles de interfaz de usuario antes de crear tu propio control de interfaz de usuario personalizado.

Además de estos controles de interfaz de usuario básicos que ofrece el propio « Qt Quick », también hay disponible un amplio conjunto de controles de interfaz de usuario con los controles « Qt Quick ». Estos se adaptan a los casos de uso más comunes sin necesidad de modificaciones y ofrecen muchas más posibilidades gracias a sus opciones de personalización. En concreto, los controles de Qt Quick ofrecen opciones de estilo que se ajustan a las últimas tendencias en diseño de interfaz de usuario. Solo si estos controles de interfaz de usuario no satisfacen las necesidades de tu aplicación, se recomienda crear un control personalizado.

Puede utilizar los controles al diseñar interfaces de usuario en Qt Design Studio. Además, ofrece animaciones basadas en líneas de tiempo, efectos visuales, diseños y una vista previa en tiempo real para la creación de prototipos de aplicaciones.

Convenciones de codificación

Consulte las convenciones de codificación de QML.

Incorporación de recursos de la aplicación

La mayoría de las aplicaciones dependen de recursos, como imágenes e iconos, para ofrecer una experiencia de usuario enriquecedora. A menudo puede resultar complicado hacer que estos recursos estén disponibles para la aplicación, independientemente del sistema operativo de destino. Los sistemas operativos más populares emplean políticas de seguridad que restringen el acceso al sistema de archivos, lo que dificulta la carga de estos recursos. Como alternativa, Qt ofrece su propio sistema de recursos integrado en el binario de la aplicación, lo que permite acceder a los recursos de la aplicación independientemente del sistema operativo de destino.

Por ejemplo, para un proyecto en C++, consideremos la siguiente estructura de directorios:

MyModule
├── images
│   ├── image1.png
│   └── image2.png
├── CMakeLists.txt
└── main.qml

Esta estructura se puede representar como un módulo QML de CMake de la siguiente manera:

qt_add_qml_module(my_module
   URI MyModule
   VERSION 1.0
   QML_FILES
       main.qml
   RESOURCES
       images/image1.png
       images/image2.png
   # ...
)

Todos los archivos QML que figuren en « QML_FILES » se compilarán automáticamente por adelantado.

Debes mantener los archivos QML en el mismo directorio que el archivo `CMakeLists.txt` en el que figura ` qt_add_qml_module`. De lo contrario, sus importaciones implícitas serán diferentes de las de los módulos QML a los que pertenecen. Esto suele ser una fuente frecuente de errores.

Separar la interfaz de usuario de la lógica de negocio

Uno de los objetivos clave que la mayoría de los desarrolladores de aplicaciones desean alcanzar es crear una aplicación fácil de mantener. Una de las formas de lograrlo es separar la interfaz de usuario (frontend) de la lógica de negocio (backend). A continuación se exponen algunas razones por las que la interfaz de usuario de una aplicación debería escribirse en QML:

  • Los lenguajes declarativos son muy adecuados para definir interfaces de usuario.
  • El código QML es más sencillo de escribir, ya que es menos prolijo que el C++ y no es un lenguaje de tipado fuerte. Esto también lo convierte en un lenguaje excelente para la creación de prototipos, una cualidad que resulta vital a la hora de colaborar con diseñadores, por ejemplo.
  • En QML se puede utilizar fácilmente JavaScript para responder a eventos.

Los lenguajes fuertemente tipados, como el C++, son los más adecuados para la lógica de negocio de una aplicación, es decir, el backend. Normalmente, este tipo de código realiza tareas como cálculos complejos o procesamiento de datos, que son más rápidos en lenguajes fuertemente tipados que en QML.

Qt ofrece varios enfoques para integrar QML con un lenguaje fuertemente tipado en una aplicación. Un caso de uso típico es mostrar una lista de datos en una interfaz de usuario. Si el conjunto de datos es estático, sencillo y pequeño, un modelo escrito en QML puede ser suficiente.

El siguiente fragmento de código muestra ejemplos de modelos escritos en QML:

model: [ "Item 1", "Item 2", "Item 3" ]

model: 10

Para conjuntos de datos más grandes y dinámicos, utiliza un lenguaje fuertemente tipado, como C++, para gestionar la lógica de negocio.

Exposición de datos desde C++ a QML

La refactorización de QML es mucho más sencilla que la de C++, por lo que, para facilitar el mantenimiento, debemos esforzarnos por que los tipos de C++ sean lo más independientes posible de QML. Esto se puede lograr «introduciendo» referencias a los tipos de C++ en QML.

Esto se puede hacer utilizando propiedades obligatorias y configurándolas mediante QQmlApplicationEngine::setInitialProperties. También es posible crear uno o varios singletons que devuelvan todos los datos que el lado de C++ quiera proporcionar a QML.

Con este enfoque, el código C++ permanece inalterado en caso de que sea necesario refactorizar el QML en el futuro.

Para obtener una guía rápida sobre cómo elegir el enfoque correcto para exponer tipos de C++ a QML, consulta «Elegir el método de integración correcto entre C++ y QML».

El uso de Qt Design Studio

Qt Design Studio utiliza archivos de interfaz de usuario con la extensión .ui.qml para separar las partes visuales de la interfaz de usuario de la lógica de la misma, que se implementa en archivos .qml. Debes editar los archivos de interfaz de usuario únicamente en la vista « 2D » de Qt Design Studio. Si utilizas alguna otra herramienta para añadir código que Qt Design Studio no admita, se mostrarán mensajes de error. Corrige los errores para volver a habilitar la edición visual de los archivos de interfaz de usuario. Por lo general, debes trasladar el código no compatible a un archivo .qml.

Uso de vistas « Qt Quick »

Almacenamiento del estado en modelos

Consulta Avoid Storing State in Delegates.

Uso de diseños de « Qt Quick »

Qt ofrece diseños « Qt Quick » para organizar visualmente los elementos de « Qt Quick » en un diseño. A diferencia de su alternativa, los posicionadores de elementos, los diseños « Qt Quick » también pueden cambiar el tamaño de sus elementos secundarios al redimensionar la ventana. Aunque los diseños « Qt Quick » suelen ser la opción preferida para la mayoría de los casos de uso, hay que tener en cuenta lo siguiente a la hora de utilizarlos:

Qué hacer

  • Utiliza ` anchors ` o las propiedades ` width ` y ` height ` para especificar el tamaño del diseño en relación con su elemento padre que no sea un diseño.
  • Utilice la propiedad adjunta ` Layout ` para establecer los atributos de tamaño y alineación de los elementos hijos inmediatos del diseño.

Lo que no se debe hacer

  • No definas tamaños preferidos para elementos que proporcionen `implicitWidth` e `implicitHeight`, a menos que sus tamaños implícitos no sean satisfactorios.
  • No utilices anclajes en un elemento que sea hijo directo de un diseño. En su lugar, utiliza « Layout.preferredWidth » y « Layout.preferredHeight »:
    RowLayout {
        id: layout
        anchors.fill: parent
        spacing: 6
        Rectangle {
            color: 'orange'
            Layout.fillWidth: true
            Layout.minimumWidth: 50
            Layout.preferredWidth: 100
            Layout.maximumWidth: 300
            Layout.minimumHeight: 150
            Text {
                anchors.centerIn: parent
                text: parent.width + 'x' + parent.height
            }
        }
        Rectangle {
            color: 'plum'
            Layout.fillWidth: true
            Layout.minimumWidth: 100
            Layout.preferredWidth: 200
            Layout.preferredHeight: 100
            Text {
                anchors.centerIn: parent
                text: parent.width + 'x' + parent.height
            }
        }
    }

Nota: Tantolos diseños como los anclajes son tipos de objetos que consumen más memoria y tiempo de instanciación. Evita utilizarlos (especialmente en delegados de listas y tablas, y en estilos para controles) cuando basten simples enlaces a las propiedades x, y, width y height.

Seguridad de tipos

Al declarar propiedades en QML, resulta fácil y cómodo utilizar el tipo «var»:

property var name
property var size
property var optionsMenu

Sin embargo, este enfoque presenta varias desventajas:

  • Si se asigna un valor con un tipo incorrecto, el error notificado apuntará a la ubicación de la declaración de la propiedad, en lugar de a la ubicación donde se asignó la propiedad. Esto ralentiza el proceso de desarrollo, ya que dificulta la localización de los errores.
  • No es posible realizar un análisis estático para detectar errores como los mencionados anteriormente.
  • El tipo subyacente real de la propiedad no siempre resulta evidente de inmediato para el lector.

En su lugar, utiliza siempre el tipo real siempre que sea posible:

property string name
property int size
property MyMenu optionsMenu

Señales de cambio de propiedad

Es preferible utilizar las señales de interacción explícita en lugar de las señales de cambio de valor para evitar errores sutiles.

El uso de « valueChanged » puede dar lugar a cascadas de eventos en las que el valor cambia constantemente porque, de alguna manera, se redondea o se normaliza.

El uso exclusivo de señales de interacción explícitas evita toda esta clase de problemas.

Por ejemplo, ` Slider ` tiene estas señales similares: ` moved ` y ` valueChanged`.

Slider {
    value: someValueFromBackend

    onValueChanged: pushToBackend(value)
    // or
    onMoved: pushToBackend(value)
}

Ambos casos parecen similares, y es posible que prefieras utilizar valueChanged.

Los desarrolladores suelen pasar por alto el hecho de que la señal « Slider » puede cambiar automáticamente su valor, por ejemplo, debido a la limitación a valores mínimos o máximos o al redondeo. En este caso, se emite la señal « valueChanged ». Si utilizas la señal « valueChanged », es posible que observes que se emite en momentos inesperados.

Para evitar posibles problemas, utiliza una señal de interacción: la señal que se emite cuando el usuario interactúa con el control. En este ejemplo, si utilizas la señal « moved », la ranura solo se activará si el usuario modifica el control.

Rendimiento

Para obtener información sobre el rendimiento en QML y Qt Quick, consulta «Consideraciones y sugerencias sobre el rendimiento de QML».

Prefiere los enlaces declarativos a las asignaciones imperativas

En QML, es posible utilizar código JavaScript imperativo para realizar tareas como responder a eventos de entrada, enviar datos a través de una red, etc. El código imperativo ocupa un lugar importante en QML, pero también es importante saber cuándo no utilizarlo.

Por ejemplo, consideremos la siguiente asignación imperativa:

Rectangle {
    Component.onCompleted: color = "red"
}

Esto presenta las siguientes desventajas:

  • Es lento. La propiedad «color» se evaluará primero con un valor construido por defecto y, posteriormente, de nuevo con «red».
  • Retrasa los errores que podrían detectarse en tiempo de compilación hasta el tiempo de ejecución, lo que ralentiza el proceso de desarrollo.
  • Sobrescribe cualquier enlace declarativo que estuviera en vigor. En la mayoría de los casos esto es intencionado, pero a veces puede ser involuntario. Consulta Depuración de la sobrescritura de enlaces para obtener más información.
  • Interfiere con las herramientas; el Diseñad Qt Quick, por ejemplo, no es compatible con JavaScript.

En su lugar, el código se puede reescribir para que sea un enlace declarativo:

Rectangle {
    color: "red"
}

No almacenes el estado en delegados

No almacenes un estado en un delegado. El problema es que el delegado se crea y se destruye varias veces, por lo que el estado guardado se perderá.

// Wrong approach:
ListView {
    // ...

    delegate: Button {
        // ...
        property bool someStateProperty
        onClicked: someStateProperty = true
    }
}

En su lugar, almacena el estado fuera del delegado. Por ejemplo, en un modelo. Cuando se destruye el delegado, el estado guardado no se pierde.

// Right approach:
ListView {
    // ...

    delegate: Button {
        // ...
        onClicked: model.someStateProperty = true
    }
}

Haz que las cadenas de texto dirigidas al usuario sean traducibles

Se recomienda hacer que las cadenas destinadas al usuario sean traducibles desde el principio. Consulta «Escribir código fuente para su traducción».

ToolButton {
    id: selectionToolButton
    // ...
    icon.source: "qrc:/images/selection.png"

    Tooltip.Text: qsTr("Select pixels within an area and move them")

    onClicked: canvas.tool = ImageCanvas.SelectionTool
}

No personalices los estilos nativos

Los estilos nativos (estilos de Windows y macOS) no admiten personalización. Asegúrate de no personalizar un estilo nativo.

// Wrong approach:
import QtQuick.Controls.Windows

// Don't customize a native style
Button {
    background: Rectangle { /*...*/ }
}

En su lugar, se recomienda basar siempre un control personalizado en un único estilo disponible en todas las plataformas, por ejemplo, el estilo Basic, Fusion, Imagine, Material o Universal. De este modo, te garantizas que siempre tendrá el mismo aspecto, 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.

// Right approach:
import QtQuick.Controls.Basic

// You can customize a commonly available style
Button {
    background: Rectangle { /*...*/ }
}

Herramientas y utilidades

Para obtener información sobre herramientas y utilidades útiles que facilitan el trabajo con QML y « Qt Quick », consulta «Herramientas y utilidades deQt Quick ».

Grafo de escena

Para obtener información sobre el grafo de escena de Qt Quick, consulta «Grafo de escena deQt Quick ».

Interfaces de usuario escalables

A medida que mejoran las resoluciones de pantalla, una interfaz de usuario escalable de la aplicación cobra cada vez más importancia. Uno de los enfoques para lograrlo consiste en mantener varias copias de la interfaz de usuario para diferentes resoluciones de pantalla y cargar la adecuada en función de la resolución disponible. Aunque esto funciona bastante bien, aumenta la carga de mantenimiento.

Qt ofrece una solución mejor a este problema y recomienda a los desarrolladores de aplicaciones que sigan estos consejos:

  • Utiliza anclajes o el módulo de diseños de Qt Quick para distribuir los elementos visuales.
  • No especifiques anchos ni alturas explícitos para un elemento visual.
  • Proporcione recursos de la interfaz de usuario, como imágenes e iconos, para cada resolución de pantalla que admita su aplicación. El ejemplo de la galería de controles « Qt Quick » lo ilustra bien al proporcionar el archivo qt-logo.png para las resoluciones @2x, @3x y @4x, lo que permite a la aplicación adaptarse a pantallas de alta resolución. Qt elige automáticamente la imagen adecuada para la pantalla en cuestión, siempre que la función de escalado de alto DPI esté activada explícitamente.
  • Utiliza imágenes SVG para los iconos pequeños. Aunque los SVG de mayor tamaño pueden tardar en renderizarse, los pequeños funcionan bien. Las imágenes vectoriales evitan la necesidad de proporcionar varias versiones de una imagen, como ocurre con las imágenes de mapa de bits.
  • Utiliza iconos basados en fuentes, como Font Awesome. Estos se adaptan a cualquier resolución de pantalla y también permiten la coloración. El ejemplo « Qt Quick: Editor de texto» lo ilustra muy bien.

Con esto en marcha, la interfaz de usuario de su aplicación debería adaptarse en función de la resolución de pantalla disponible.

Ejemplo de pantalla de bienvenida de la galería con el logotipo de Qt

© 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.