En esta página

Convenciones de codificación de QML

Este documento recoge las convenciones de codificación de QML que seguimos en nuestra documentación y ejemplos, y que recomendamos que sigan los demás.

Declaraciones de objetos QML

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

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

Para facilitar la lectura, separamos estas diferentes partes con una línea en blanco.

Por ejemplo, un hipotético objeto QML de 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 utilizas varias propiedades de un grupo de propiedades, plantéate usar la notación de grupo en lugar de la notación de puntos si ello 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
}

se podría escribir 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 sin calificar

Para mejorar la legibilidad y el rendimiento, haz siempre referencia a las propiedades de los componentes padres por su identificador de forma explícita:

Item {
    id: root

    property int rectangleWidth: 50

    Rectangle {
        width: root.rectangleWidth
    }
}

Propiedades obligatorias

Cuando se necesiten datos definidos fuera del componente, indícalo explícitamente utilizando las propiedades obligatorias. Las propiedades obligatorias deben establecerse; de lo contrario, la creación del componente fallará. Son preferibles a las búsquedas sin calificar porque ofrecen un mejor rendimiento y permiten tanto a los usuarios como a las herramientas determinar el tipo de una propiedad externa. Además, eliminan las suposiciones que, de otro modo, un componente tendría que hacer sobre el entorno en el que se crea.

Manejadores de señales

Al gestionar parámetros en los controladores de señales, utiliza funciones que los nombren explícitamente:

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

Código JavaScript

Para mejorar la legibilidad y la facilidad de mantenimiento, por lo general declaramos cada propiedad en una línea separada, incluso en el caso de expresiones sencillas.

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

Para 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)
}

Ten en cuenta también que se recomienda añadir anotaciones de tipo a tu función para poder analizar y refactorizar más fácilmente tu aplicación, ya que tanto los tipos de los parámetros como los de los valores de retorno son visibles de inmediato en la firma de la función.

En el caso de scripts largos, colocaremos las funciones en su propio archivo JavaScript y las importaremos de la siguiente manera:

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 lo tanto, se encuentra dentro de un bloque, utilizamos puntos y comas para indicar el final de cada instrucción:

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

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