En esta página

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 {}

El tipo de botón cuadrado de «myapplication.qml» hereda las propiedades definidas en «SquareButton.qml».

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

Columna que contiene tres botones cuadrados con diferentes propiedades de color y tamaño

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.