Definición de tipos de objetos mediante documentos QML
Una de las características principales de QML es que permite definir fácilmente y de forma sencilla tipos de objetos QML a través de documentos QML para adaptarse a las necesidades de cada aplicación QML. El módulo estándar Qt Quick proporciona varios tipos, como Rectangle, Text y Image, para crear una aplicación QML; además de estos, puedes definir fácilmente tus propios tipos QML para reutilizarlos dentro de tu aplicación. Esta capacidad de crear tus propios tipos constituye la base de cualquier aplicación QML.
Definición de un tipo de objeto con un archivo QML
Nombrar tipos de objeto QML personalizados
Para crear un tipo de objeto, se debe colocar un documento QML en un archivo de texto denominado <TypeName>.qml, donde <TypeName> es el nombre deseado para el tipo. El nombre del tipo debe cumplir los siguientes requisitos:
- Debe estar compuesto por caracteres alfanuméricos o guiones bajos.
- Debe comenzar con una letra mayúscula.
A continuación, el motor reconoce automáticamente este documento como una definición de un tipo QML. Además, un tipo definido de esta manera queda automáticamente disponible para otros archivos QML dentro del mismo directorio local, ya que el motor busca en el directorio inmediato al resolver los nombres de los tipos QML.
Nota: El motor QML no busca automáticamente en directorios remotos de esta manera. Debes añadir un archivo qmldir si tus documentos se cargan a través de la red. Consulta Importación de directorios de documentos QML.
Definición de un tipo QML personalizado
Por ejemplo, a continuación se muestra un documento que declara un ` Rectangle ` con un elemento secundario ` MouseArea`. El documento se ha guardado en un archivo denominado ` SquareButton.qml`:
// SquareButton.qml
import QtQuick 2.0
Rectangle {
property int side: 100
width: side; height: side
color: "red"
MouseArea {
anchors.fill: parent
onClicked: console.log("Button clicked!")
}
}Dado que el archivo se llama « SquareButton.qml », ahora puede utilizarse como un tipo denominado « SquareButton » en cualquier otro archivo QML dentro del mismo directorio. Por ejemplo, si hubiera un archivo « myapplication.qml » en el mismo directorio, podría hacer referencia al tipo « SquareButton »:
// myapplication.qml
import QtQuick 2.0
SquareButton {}
Esto crea un « Rectangle » rojo de 100 x 100 con un « MouseArea » en su interior, tal y como se define en SquareButton.qml. Cuando el motor carga este documento myapplication.qml, carga el documento SquareButton.qml como un componente y crea una instancia del mismo para generar un objeto SquareButton.
El tipo SquareButton encapsula el árbol de objetos QML declarados en SquareButton.qml. Cuando el motor QML crea una instancia de un objeto SquareButton a partir de este tipo, está creando una instancia de un objeto del árbol Rectangle declarado en SquareButton.qml.
Nota: Las mayúsculas y minúsculas del nombre del archivo son importantes en algunos sistemas de archivos (especialmente en UNIX). Se recomienda que las mayúsculas y minúsculas del nombre del archivo coincidan exactamente con las del nombre del tipo QML deseado —por ejemplo, Box.qml y no BoX.qml —, independientemente de la plataforma en la que se vaya a implementar el tipo QML.
Componentes en línea
A veces, puede resultar incómodo crear un nuevo archivo para un tipo, por ejemplo, al reutilizar un pequeño delegado en varias vistas. Si en realidad no necesitas exponer el tipo, sino que solo necesitas crear una instancia, Component es una opción. Pero si quieres declarar propiedades con los tipos de componente, o si quieres utilizarlo en varios archivos, Component no es una opción. En ese caso, puedes utilizar componentes en línea. Los componentes en línea declaran un nuevo componente dentro de un archivo. La sintaxis para ello es
component <component name> : BaseType {
// declare properties and bindings here
}Dentro del archivo que declara el componente en línea, se puede hacer referencia al tipo simplemente por su nombre.
// Images.qml
import QtQuick
Item {
component LabeledImage: Column {
property alias source: image.source
property alias caption: text.text
Image {
id: image
width: 50
height: 50
}
Text {
id: text
font.bold: true
}
}
Row {
LabeledImage {
id: before
source: "before.png"
caption: "Before"
}
LabeledImage {
id: after
source: "after.png"
caption: "After"
}
}
property LabeledImage selectedImage: before
}En otros archivos, debe ir precedido del nombre del componente que lo contiene.
// LabeledImageBox.qml
import QtQuick
Rectangle {
property alias caption: image.caption
property alias source: image.source
border.width: 2
border.color: "black"
Images.LabeledImage {
id: image
}
}Nota: Los componentesen línea no comparten su ámbito con el componente en el que se declaran. En el siguiente ejemplo, cuando se crea « A.MyInlineComponent » en el archivo B.qml, se producirá un «ReferenceError», ya que « root » no existe como identificador en B.qml. Por lo tanto, es recomendable no hacer referencia en un componente en línea a objetos que no formen parte del mismo.
// A.qml
import QtQuick
Item {
id: root
property string message: "From A"
component MyInlineComponent : Item {
Component.onCompleted: console.log(root.message)
}
}
// B.qml
import QtQuick
Item {
A.MyInlineComponent {}
}Nota: Los componentesen línea no se pueden anidar.
Importación de tipos definidos fuera del directorio actual
Si SquareButton.qml no se encontrara en el mismo directorio que myapplication.qml, el tipo SquareButton tendría que hacerse disponible de forma específica mediante una instrucción de importación en myapplication.qml. Podría importarse desde una ruta relativa en el sistema de archivos o como un módulo instalado; consulta «módulo» para obtener más detalles.
Atributos accesibles de los tipos personalizados
La definición del objeto raíz en un archivo .qml define los atributos que están disponibles para un tipo QML. Todas las propiedades, señales y métodos que pertenecen a este objeto raíz —ya sean declarados de forma personalizada o procedan del tipo QML del objeto raíz— son accesibles desde el exterior y pueden leerse y modificarse para los objetos de este tipo.
Por ejemplo, el tipo de objeto raíz en el archivo SquareButton.qml anterior es Rectangle. Esto significa que cualquier propiedad definida por el tipo Rectangle puede modificarse para un objeto SquareButton. El código siguiente define tres objetos SquareButton con valores personalizados para algunas de las propiedades del objeto raíz Rectangle del tipo SquareButton:
// application.qml
import QtQuick 2.0
Column {
SquareButton { side: 50 }
SquareButton { x: 50; color: "blue" }
SquareButton { radius: 10 }
}
Los atributos a los que pueden acceder los objetos del tipo QML personalizado incluyen cualquier propiedad, método y señal personalizados que se hayan definido adicionalmente para un objeto. Por ejemplo, supongamos que el objeto ` Rectangle ` de ` SquareButton.qml ` se hubiera definido de la siguiente manera, con propiedades, métodos y señales adicionales:
// SquareButton.qml
import QtQuick 2.0
Rectangle {
id: root
property bool pressed: mouseArea.pressed
signal buttonClicked(real xPos, real yPos)
function randomizeColor() {
root.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
}
property int side: 100
width: side; height: side
color: "red"
MouseArea {
id: mouseArea
anchors.fill: parent
onClicked: (mouse)=> root.buttonClicked(mouse.x, mouse.y)
}
}Cualquier objeto ` SquareButton ` podría utilizar la propiedad ` pressed `, la señal ` buttonClicked ` y el método ` randomizeColor() ` que se han añadido al objeto raíz ` Rectangle`:
// application.qml
import QtQuick 2.0
SquareButton {
id: squareButton
onButtonClicked: (xPos, yPos)=> {
console.log("Clicked", xPos, yPos)
randomizeColor()
}
Text { text: squareButton.pressed ? "Down" : "Up" }
}Tenga en cuenta que los objetos ` SquareButton ` no pueden acceder a ninguno de los valores ` id ` definidos en ` SquareButton.qml `, ya que solo se puede acceder a los valores de `id` desde el ámbito del componente en el que se ha declarado dicho componente. La definición del objeto SquareButton anterior no puede hacer referencia a mouseArea para referirse al elemento secundario MouseArea, y si tuviera un id de root en lugar de squareButton, esto no entraría en conflicto con el id del mismo valor para el objeto raíz definido en SquareButton.qml, ya que ambos se declararían dentro de ámbitos separados.
© 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.