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