Buenas prácticas para la escalabilidad de QML y Qt Quick

Convenciones de codificación de QML

Este documento contiene las convenciones de codificación de QML que seguimos en nuestra documentación y ejemplos y que recomendamos que otros sigan.

Declaraciones de objetos QML

A lo largo de nuestra documentación y ejemplos, los atributos de los objetos QML se estructuran siempre en el siguiente orden:

id
declaraciones de propiedades
declaraciones de señales
funciones JavaScript
propiedades del objeto
objetos hijo

Para una mejor legibilidad, separamos estas diferentes partes con una línea vacía.

Por ejemplo, un hipotético objeto QML foto tendría este aspecto:

Rectangle {
    id: photo                                               // id on the first line makes it easy to find an object

    property bool thumbnail: false                          // property declarations
    property alias image: photoImage.source

    signal clicked                                          // signal declarations

    function doSomething(x)                                 // javascript functions
    {
        return x + photoImage.width;
    }

    color: "gray"                                           // object properties
    x: 20                                                   // try to group related properties together
    y: 20
    height: 150
    width: {                                                // large bindings
        if (photoImage.width > 200) {
            photoImage.width;
        } else {
            200;
        }
    }

    states: [
        State {
            name: "selected"
            PropertyChanges { target: border; color: "red" }
        }
    ]

    transitions: [
        Transition {
            from: ""
            to: "selected"
            ColorAnimation { target: border; duration: 200 }
        }
    ]

    Rectangle {                                             // child objects
        id: border
        anchors.centerIn: parent
        color: "white"

        Image {
            id: photoImage
            anchors.centerIn: parent
        }
    }
}

Propiedades agrupadas

Si utiliza varias propiedades de un grupo de propiedades, considere la posibilidad de utilizar la notación de grupo en lugar de la notación de puntos si mejora la legibilidad.

Por ejemplo, esto

Rectangle {
    anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20
}

Text {
    text: "hello"
    font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase
}

podría escribirse así:

Rectangle {
    anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 }
}

Text {
    text: "hello"
    font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase }
}

Acceso no cualificado

Para mejorar la legibilidad y el rendimiento, haga siempre referencia explícita a las propiedades de los componentes padre por su id:

Item {
    id: root

    property int rectangleWidth: 50

    Rectangle {
        width: root.rectangleWidth
    }
}

Propiedades requeridas

Cuando requiera datos definidos fuera del componente, hágalo explícito utilizando Propiedades requeridas. Las propiedades obligatorias deben establecerse o, de lo contrario, la creación del componente fallará. Son preferibles a las búsquedas no cualificadas porque son más eficaces y permiten tanto a los usuarios como a las herramientas razonar sobre el tipo de una propiedad externa. Además, eliminan las suposiciones que un componente tiene que hacer sobre el entorno en el que se crea.

Manejadores de señales

Al manejar parámetros en manejadores de señales, utilice funciones que los nombren explícitamente:

MouseArea {
    onClicked: event => { console.log(`${event.x},${event.y}`); }
}

Código JavaScript

Para mejorar la legibilidad y el mantenimiento, generalmente declaramos cada propiedad en una línea independiente, incluso en el caso de expresiones sencillas.

Rectangle {
    color: "blue"
    width: parent.width / 3
}

Para las expresiones de script que abarcan varias líneas, utilizamos un formato de bloque:

Rectangle {
    color: "blue"
    width: {
        var w = parent.width / 3;
        console.debug(w);
        return w;
    }
}

Si el script tiene más de un par de líneas o puede ser utilizado por diferentes objetos, recomendamos crear una función y llamarla de esta forma:

function calculateWidth(object : Item) : double
{
    var w = object.width / 3;
    // ...
    // more javascript code
    // ...
    console.debug(w);
    return w;
}

Rectangle {
    color: "blue"
    width: calculateWidth(parent)
}

Tenga en cuenta también que es recomendable añadir anotaciones de tipo a su función para razonar y refactorizar más fácilmente su aplicación, ya que tanto los tipos de parámetros como los de retorno son inmediatamente visibles desde la firma de la función.

Para scripts largos, pondremos las funciones en su propio archivo JavaScript y lo importaremos así:

import "myscript.js" as Script

Rectangle { color: "blue"; width: Script.calculateWidth(parent) }

Si el código tiene más de una línea y, por tanto, está dentro de un bloque, utilizaremos punto y coma para indicar el final de cada sentencia:

MouseArea {
    anchors.fill: parent
    onClicked: event => {
        var scenePos = mapToItem(null, event.x, event.y);
        console.log("MouseArea was clicked at scene pos " + scenePos);
    }
}

Mejores prácticas para la escalabilidad de QML y Qt Quick

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