En esta página

Ocultación de propiedades y semántica de la sobrescritura

Ocultación de propiedades

Por defecto, las propiedades pueden quedar enmascaradas: se vuelve a declarar una propiedad en un tipo QML derivado, posiblemente con un nuevo tipo y nuevos atributos. El resultado serán dos propiedades con el mismo nombre, de las cuales solo una será accesible en un contexto determinado. Esto rara vez es lo que se desea. A menudo es algo accidental y, en la mayoría de los casos, los efectos resultan bastante confusos.

Consideremos el siguiente ejemplo: supongamos que tenemos un tipo `Building` utilizado en un software de visualización arquitectónica escrito en QML:

// Building.qml
import QtQuick

Item {
    property int floors
    property string rotation // like CSS rotate, "-120deg"
    property date constructionDate
}

`Building` es un `Item`, ya que hereda de él, pero, y esto es importante, la propiedad ` rotation property ` de ` Item ` ha quedado enmascarada por la propiedad `rotation` recién introducida en `Building`. Al pasar este objeto a una función genérica que maneja «Items», la función intentará leer la propiedad «rotation» del objeto y esperará obtener la propiedad de tipo «real» definida en Item. En cambio, obtiene una cadena, lo que da lugar a resultados inesperados.

Esto también supone un obstáculo para las herramientas de QML. Rara vez pueden determinar con certeza el tipo de una propiedad sin ejecutar el código que la manipula. Esto se debe a que el objeto que contiene la propiedad suele ser de un tipo derivado.

Por lo tanto, esto no solo confunde al usuario y da lugar a errores inesperados difíciles de detectar, sino que también impide que las herramientas generen un código más optimizado.

Para solucionar esto, se introdujeron las palabras clave « final », « override » y « virtual », junto con advertencias y errores adicionales. Su objetivo es ayudar a los usuarios a evitar el enmascaramiento accidental y proporcionar mecanismos explícitos para los casos excepcionales en los que una propiedad realmente necesita sustituir a una propiedad de un tipo base. Nos referimos a este enmascaramiento explícito como «sobrescritura».

Nota: Como se ha explicado anteriormente, la ocultación suele ser accidental y, por lo general, da lugar a un comportamiento ambiguo y difícil de diagnosticar. Siempre que sea posible, es preferible utilizar propiedades con nombres únicos en lugar de recurrir a la ocultación o a la anulación.

Palabras clave «virtual», «override» y «final»

  • La palabra clave « final » marca esta declaración como «final». Puede anular una propiedad de un tipo base, pero no puede ser anulada ni enmascarada por tipos derivados. Esto ayuda a evitar el enmascaramiento accidental y permite que las herramientas de QML generen código más optimizado.
  • La palabra clave « override » indica que la propiedad sobrescribe intencionadamente una propiedad virtual de un tipo base. Una propiedad que sobrescribe a otra no necesita marcarse como « virtual ». Hereda automáticamente la virtualidad de la propiedad que sobrescribe. Si la propiedad original es virtual, la sobrescritura también lo es. Si no lo es, la sobrescritura no es válida y ya producirá un error.
  • La palabra clave « virtual » indica explícitamente que la propiedad está pensada para ser sobrescrita. Añadir « virtual » a la propiedad que sobrescribe no tiene ningún efecto; véase override.

Así es como se pueden utilizar en la práctica:

// Base.qml
QtObject {
 virtual property int a
 virtual property int b
 virtual property var c
 property var d
}

// DerivedMixed.qml
Base {
 override property var a // fine: overrides property "a" of a Base type
 final readonly property int b // fine: overrides property "c" of a Base type; can't be overriden any more
}

// DerivedDerivedMixed.qml
DerivedMixed {
 virtual property int a // warning: overrides virtual property, but lacks "override" or "final"
 override property int a // fine: overrides a property "a" of a DerivedMixed type;
 final property int a // fine: overrides a property "a" of a DerivedMixed type; can't be overriden any more

 virtual property int b // error: can't override a final property
 override property int b // error: can't override a final property
 final property int b // error: can't override a final property

 final property int c // fine: overrides property "c" of a Base type; can't be overriden any more
 override property int d // error: overrides a property that is not marked virtual
}

Nota: Es preferible utilizar « final » en lugar de override

Aquí también hay una lista exhaustiva de combinaciones de `virtual`, `override` y `final` a modo de referencia:

// Base.qml
QtObject {
 property int a          // fine: declaring a property
 virtual property int b  // fine: declaring a property that is intended to be overriden
 final property int c    // fine: declaring a property that can't be overriden
 override property int d // error: does not override anything
 virtual override property int d // parser error: remove override
 virtual final property int d // parser error: virtual and final are mutually exclusive
}

// Derived.qml
Base {
 property int a // warning: overrides a property that is not marked virtual
 property int b // warning: overrides a virtual property, but lacks "override" or "final"
 property int c // error: can't override a final property
}

// DerivedVirtual.qml
Base {
 virtual property int a // warning: overrides a property that is not marked virtual
 virtual property int b // warning: overrides a virtual property, but lacks "override" or "final"
 virtual property int c // error: can't override a final property
}

// DerivedFinal.qml
Base {
 final property int a // warning: overrides a property that is not marked virtual
 final property int b // fine: overrides a property "b" from the Base type; can't be overriden any more
 final property int c // error: can't override a final property
}

// DerivedOverride.qml
Base {
 override property int a // error: overrides a property that is not marked virtual
 override property int b // fine: overrides a property "b" from the Base type
 override property int c // error: can't override a final property
 override final property int d // parser error: remove override
}

Nota: La mayoría de las advertencias se convertirán en errores en el futuro; de momento no podemos convertirlas en errores debido a la compatibilidad con versiones anteriores.

Nota: Estas semánticas son impuestas por el QmlEngine.

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