Ámbito y resolución de nombres
Los enlaces de propiedades de QML, las funciones en línea y los archivos JavaScript importados se ejecutan todos en un ámbito de JavaScript. El ámbito controla a qué variables puede acceder una expresión y qué variable tiene prioridad cuando hay un conflicto entre dos o más nombres.
Dado que el mecanismo de ámbito integrado de JavaScript es muy sencillo, QML lo mejora para que se adapte de forma más natural a las extensiones del lenguaje QML.
Ámbito de JavaScript
Las extensiones de ámbito de QML no interfieren con el ámbito natural de JavaScript. Los programadores de JavaScript pueden reutilizar sus conocimientos existentes al programar funciones, enlaces de propiedades o archivos JavaScript importados en QML.
En el siguiente ejemplo, el método ` addConstant() ` sumará 13 al parámetro pasado, tal y como esperaría el programador, independientemente del valor de las propiedades ` a ` y ` b ` del objeto QML.
QtObject {
property int a: 3
property int b: 9
function addConstant(b) {
var a = 13;
return b + a;
}
}El hecho de que QML respete las reglas normales de ámbito de JavaScript se aplica incluso en los enlaces. Este enlace, totalmente perverso y abominable, asignará 12 a la propiedad ` a ` del objeto QML.
Cada expresión, función o archivo de JavaScript en QML tiene su propio objeto de variable único. Las variables locales declaradas en uno nunca entrarán en conflicto con las variables locales declaradas en otro.
Nombres de tipos y archivos JavaScript importados
Los documentos QML incluyen sentencias de importación que definen los nombres de tipos y los archivos JavaScript visibles para el documento. Además de su uso en la propia declaración de QML, los nombres de tipos son utilizados por el código JavaScript al acceder a propiedades adjuntas y valores de enumeración.
El efecto de una importación se aplica a todos los enlaces de propiedades y a todas las funciones de JavaScript del documento QML, incluso a los que se encuentran en componentes en línea anidados. El siguiente ejemplo muestra un archivo QML sencillo que accede a algunos valores de enumeración y llama a una función de JavaScript importada.
import QtQuick 2.0
import "code.js" as Code
ListView {
snapMode: ListView.SnapToItem
delegate: Component {
Text {
elide: Text.ElideMiddle
text: "A really, really long string that will require eliding."
color: Code.defaultColor()
}
}
}Objeto de ámbito de enlace
Un objeto que tiene un enlace de propiedad se conoce como el objeto de ámbito del enlace. En el siguiente ejemplo, el objeto Item es el objeto de ámbito del enlace.
Item {
anchors.left: parent.left
}Los enlaces tienen acceso a las propiedades del objeto de ámbito sin necesidad de calificaciones. En el ejemplo anterior, el enlace accede directamente a la propiedad ` parent ` de ` Item`, sin necesidad de ningún prefijo de objeto. QML introduce un enfoque más estructurado y orientado a objetos para JavaScript y, por consiguiente, no requiere el uso de la propiedad ` this ` de JavaScript.
Hay que tener cuidado al acceder a propiedades adjuntas desde enlaces debido a su interacción con el objeto de ámbito. Conceptualmente, las propiedades adjuntas existen en todos los objetos, aunque solo afecten a un subconjunto de ellos. Por consiguiente, las lecturas de propiedades adjuntas sin calificar siempre se resolverán como una propiedad adjunta del objeto de ámbito, lo que no siempre es lo que el programador pretendía.
Por ejemplo, el tipo PathView adjunta propiedades de valor interpoladas a sus delegados en función de su posición en la ruta. Dado que PathView solo adjunta de forma significativa estas propiedades al objeto raíz del delegado, cualquier subobjeto que acceda a ellas debe calificar explícitamente el objeto raíz, tal y como se muestra a continuación.
Si el objeto ` Image ` omitiera el prefijo ` root `, accedería inadvertidamente a la propiedad asociada ` PathView.scale `, que no está definida, en sí mismo.
Ámbito del componente
Cada componente QML de un documento QML define un ámbito lógico. Cada documento tiene al menos un componente raíz, pero también puede tener otros subcomponentes en línea. El ámbito del componente es la unión de los identificadores de los objetos dentro del componente y de las propiedades del objeto raíz del componente.
Item {
property string title
Text {
id: titletype
text: "<b>" + title + "</b>"
font.pixelSize: 22
anchors.top: parent.top
}
Text {
text: titletype.text
font.pixelSize: 18
anchors.bottom: parent.bottom
}
}El ejemplo anterior muestra un componente QML sencillo que muestra una cadena de título de texto enriquecido en la parte superior y una copia más pequeña del mismo texto en la parte inferior. El primer tipo ` Text ` accede directamente a la propiedad ` title ` del componente al formar el texto que se va a mostrar. El hecho de que se pueda acceder directamente a las propiedades del tipo raíz facilita enormemente la distribución de datos por todo el componente.
El segundo tipo « Text » utiliza un identificador (id) para acceder directamente al texto del primero. Los identificadores los especifica explícitamente el programador de QML, por lo que siempre tienen prioridad sobre otros nombres de propiedades (excepto los del ámbito de JavaScript). Por ejemplo, en el improbable caso de que el objeto de ámbito del enlace tuviera una propiedad ` titletype ` en el ejemplo anterior, el identificador ` titletype ` seguiría teniendo prioridad.
Jerarquía de instancias de componentes
En QML, las instancias de componentes conectan entre sí sus ámbitos de componente para formar una jerarquía de ámbitos. Las instancias de componentes pueden acceder directamente a los ámbitos de componente de sus antecesores.
La forma más sencilla de demostrarlo es con subcomponentes en línea cuyos ámbitos de componente se definen implícitamente como hijos del componente exterior.
Item {
property color defaultColor: "blue"
ListView {
delegate: Component {
Rectangle {
color: defaultColor
}
}
}
}La jerarquía de instancias de componentes permite que las instancias del componente delegado accedan a la propiedad « defaultColor » del tipo « Item ». Por supuesto, si el componente delegado tuviera una propiedad llamada « defaultColor », esta tendría prioridad.
La jerarquía de ámbitos de las instancias de componentes se extiende también a los componentes fuera de línea. En el siguiente ejemplo, el componente ` TitlePage.qml ` crea dos instancias de ` TitleText `. Aunque el tipo ` TitleText ` se encuentre en un archivo independiente, sigue teniendo acceso a la propiedad ` title ` cuando se utiliza desde dentro de ` TitlePage`. QML es un lenguaje de ámbito dinámico: dependiendo de dónde se utilice, la propiedad ` title ` puede resolverse de forma diferente.
// TitlePage.qml
import QtQuick 2.0
Item {
property string title
TitleText {
size: 22
anchors.top: parent.top
}
TitleText {
size: 18
anchors.bottom: parent.bottom
}
}
// TitleText.qml
import QtQuick 2.0
Text {
property int size
text: "<b>" + title + "</b>"
font.pixelSize: size
}El ámbito dinámico es muy potente, pero debe utilizarse con precaución para evitar que el comportamiento del código QML resulte difícil de predecir. En general, solo debería utilizarse en casos en los que los dos componentes ya estén estrechamente acoplados de otra forma. Al crear componentes reutilizables, es preferible utilizar interfaces de propiedades, como se muestra a continuación:
// TitlePage.qml
import QtQuick 2.0
Item {
id: root
property string title
TitleText {
title: root.title
size: 22
anchors.top: parent.top
}
TitleText {
title: root.title
size: 18
anchors.bottom: parent.bottom
}
}
// TitleText.qml
import QtQuick 2.0
Text {
property string title
property int size
text: "<b>" + title + "</b>"
font.pixelSize: size
}No hagas referencia al objeto raíz id desde otros componentes QML
Evita acceder a ` id ` de un objeto raíz desde fuera del archivo QML en el que está definido. Los valores de ` id ` solo son válidos dentro del mismo documento, y recurrir a ellos desde otros componentes rompe la encapsulación y los límites de los componentes.
// Main.qml
import QtQuick
Item {
id: root
CustomItem { }
}
// CustomItem.qml
import QtQuick
Rectangle {
width: root.width
height: root.height / 2
color: "red"
}En el ejemplo anterior, ` root ` no está declarado en ` CustomItem.qml`. El código sigue funcionando porque ` CustomItem ` se instancia en un contexto en el que existe ` root `, lo cual está permitido por las reglas de ámbito dinámico de QML. Sin embargo, esto crea una dependencia implícita del ámbito exterior, lo que hace que el componente sea poco fiable y más difícil de reutilizar cuando se carga dinámicamente o se utiliza en un contexto diferente. Este patrón también puede dar lugar a errores sutiles. Por ejemplo, si otro objeto de la cadena de ámbitos utiliza el mismo id, puede ocultar el esperado, lo que provocaría un comportamiento inesperado.
Para que los componentes sean fiables y reutilizables, accede al estado externo únicamente a través de propiedades explícitas, alias de propiedades o señales. Evita depender de valores de id del ámbito exterior.
El siguiente ejemplo sustituye el ámbito dinámico por una API de componentes explícita.
// Main.qml
import QtQuick
import QtQuick.Window
Window {
id: root
width: 400
height: 300
visible: true
CustomItem {
width: root.width
height: root.height
boxColor: "blue"
}
}
// CustomItem.qml
import QtQuick
Item {
id: container
property alias boxColor: rect.color
Rectangle {
id: rect
width: container.width
height: container.height / 2
color: "red"
}
}Aplica la misma regla a todos los objetos internos declarados con un ` id ` dentro de un componente.
// MyItem.qml
import QtQuick
Item {
Item {
id: internalCounter
property int count: 5
}
}
// main.qml
import QtQuick
MyItem {
Component.onCompleted: {
console.log(internalCounter.count);
}
}id En el ejemplo anterior, acceder a la variable de ámbito dinámico internalCounter desde otro archivo QML provoca un error « ReferenceError », ya que una variable de ámbito dinámico id es local al documento y no se puede acceder a ella fuera del archivo QML en el que está declarada.
Si un objeto interno necesita exponer su estado o comportamiento, expónlo explícitamente a través de propiedades, alias de propiedades o señales.
El siguiente ejemplo expone el estado interno a través de una API de componente explícita, en lugar de depender del acceso directo a un id local al documento.
// MyItem.qml
import QtQuick
Item {
Item {
id: internalCounter
property int count: 5
}
property alias internalCount: internalCounter.count
}
// main.qml
import QtQuick
MyItem {
Component.onCompleted: {
console.log(internalCount);
}
}Esto ayuda a mantener unos límites claros entre componentes y favorece una mayor escalabilidad y facilidad de prueba.
Propiedades sobrescritas
QML permite que los nombres de las propiedades definidos en la declaración de un objeto sean sobrescritos por propiedades declaradas dentro de otra declaración de objeto que extienda a la primera. Por ejemplo:
// Displayable.qml
import QtQuick 2.0
Item {
property string title
property string detail
Text {
text: "<b>" + title + "</b><br>" + detail
}
function getTitle() { return title }
function setTitle(newTitle) { title = newTitle }
}
// Person.qml
import QtQuick 2.0
Displayable {
property string title
property string firstName
property string lastName
function fullName() { return title + " " + firstName + " " + lastName }
}Aquí, el nombre « title » se asigna tanto al encabezado del texto de salida de «Displayable» como al título honorífico del objeto «Person».
Una propiedad sobrescrita se resuelve según el ámbito en el que se hace referencia a ella. Dentro del ámbito del componente «Person», o desde un ámbito externo que haga referencia a una instancia del componente «Person», « title » se resuelve como la propiedad declarada en «Person.qml». La función « fullName » hará referencia a la propiedad « title » declarada en «Person».
Sin embargo, dentro del componente `Displayable`, ` title ` hace referencia a la propiedad declarada en `Displayable.qml`. Las funciones `getTitle()` y `setTitle()`, así como el enlace de la propiedad ` text ` del objeto `Text`, harán referencia a la propiedad ` title ` declarada en el componente `Displayable`.
A pesar de compartir el mismo nombre, las dos propiedades son totalmente independientes. Un controlador de señal onChanged para una de las propiedades no se activará por un cambio en la otra propiedad con el mismo nombre. Un alias a cualquiera de las propiedades se referirá a una u otra, pero no a ambas.
Objeto global de JavaScript
QML no permite nombres de tipos, identificadores ni propiedades que entren en conflicto con las propiedades del objeto global para evitar cualquier confusión. ¡Los programadores pueden estar seguros de que ` Math.min(10, 9) ` siempre funcionará como se espera!
Consulta «Entorno de ejecución de JavaScript » para obtener más información.
© 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.