En esta página

QTP0004

Los directorios adicionales con archivos QML en un módulo QML requieren archivos qmldir adicionales.

Esta política se introdujo en Qt 6.8. Hace que el sistema de compilación genere un archivo «qmldir» adicional por cada directorio adicional que contenga archivos QML en un módulo QML.

Al habilitar esta política, se garantiza que la importación implícita de cada uno de los componentes QML del módulo sea la misma que la del propio módulo. Esto significa que todos los componentes pueden verse entre sí sin necesidad de importar explícitamente el módulo.

El comportamiento « OLD » de esta política consiste en que solo se genera un archivo «qmldir» para el directorio raíz de un módulo.

El comportamiento « NEW » de esta política consiste en que, para cada directorio con archivos QML dentro de un módulo, se genera un archivo «qmldir» independiente. Cada archivo «qmldir» generado contiene una directiva « prefer » que redirige la importación implícita a la ubicación canónica del recurso del módulo.

Antecedentes

El motor QML siempre realiza una importación implícita del directorio en el que se encuentra un archivo QML. En el caso de los archivos del directorio raíz del módulo, esta importación implícita apunta al propio módulo, por lo que todos los componentes hermanos son visibles. Sin embargo, cuando los archivos QML se ubican en subdirectorios, la importación implícita apunta a ese subdirectorio en su lugar. Los componentes del subdirectorio no pueden ver entonces a otros componentes del mismo módulo sin añadir una declaración explícita ` import `. Esto suele ser una fuente frecuente de errores.

Con el comportamiento de « NEW », el sistema de compilación genera un archivo «qmldir» en cada subdirectorio que contiene una directiva « prefer » que apunta a la ubicación canónica de los recursos del módulo. Esto hace que la importación implícita de cada archivo QML del módulo equivalga a importar el propio módulo, de modo que todos los componentes puedan encontrarse entre sí independientemente de su directorio.

Ejemplo

Consideremos un módulo con archivos QML repartidos en varios subdirectorios:

qt_add_qml_module(mymodule
    URI MyModule
    QML_FILES
        Main.qml
        controls/MyButton.qml
        views/MyView.qml
)

Una necesidad habitual es que views/MyView.qml utilice MyButton desde el subdirectorio controls. Con el comportamiento « OLD », esto falla de forma silenciosa: views/MyView.qml importa implícitamente el subdirectorio views, por lo que MyButton no se encuentra a menos que se añada import MyModule de forma explícita.

Con el comportamiento de NEW, se genera un qmldir adicional tanto en el subdirectorio controls como en el views. Cada uno de ellos redirige la importación implícita a la ubicación canónica del recurso del módulo, de modo que views/MyView.qml puede utilizar MyButton y cualquier otro tipo del módulo sin necesidad de una importación explícita.

Puedes establecer la política de forma explícita en tu proyecto antes de llamar a qt_add_qml_module():

qt_policy(SET QTP0004 NEW)

Como alternativa, llama a ` qt_standard_project_setup() ` con una versión de ` REQUIRES ` 6.8 o posterior.

Qt 6.8 emite advertencias si no se configura explícitamente la política.

Nota: El comportamiento de una política en « OLD » está obsoleto y podría eliminarse en el futuro.

Véase también qt_policy(), qt_standard_project_setup(), qt_cmake_policies y qt_add_qml_module().

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