Instrucciones de importación
Sintaxis de una instrucción de importación
Una instrucción de importación permite a los clientes indicar al motor qué módulos, recursos JavaScript y directorios de componentes se utilizan dentro de un documento QML. Los tipos que se pueden utilizar dentro de un documento dependen de los módulos, recursos y directorios que importe dicho documento.
Existen tres tipos diferentes de importaciones. Cada tipo de importación tiene una sintaxis ligeramente diferente, y se aplican semánticas distintas a cada uno de ellos.
Importaciones de módulos (espacios de nombres)
El tipo más común de importación es la importación de módulos. Los clientes pueden importar módulos QML que registran tipos de objetos QML y recursos JavaScript en un espacio de nombres determinado.
La forma genérica de una importación de módulos es la siguiente:
import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]<ModuleIdentifier>es un identificador especificado en notación URI con puntos, que identifica de forma única el espacio de nombres de tipos proporcionado por el módulo.- El «
<Version.Number>» es una versión de la formaMajorVersion.MinorVersionque especifica qué definiciones de los distintos tipos de objetos y recursos JavaScript estarán disponibles gracias a la importación. Se puede omitir; en ese caso, se importa la última versión del módulo. También es posible omitir únicamente la versión menor. En ese caso, se importa la última versión menor de la versión principal dada. - El
<Qualifier>es un identificador de espacio de nombres local opcional en el que se instalarán los tipos de objeto y los recursos de JavaScript proporcionados por el módulo, si se especifica. Si se omite, los tipos de objeto y los recursos de JavaScript proporcionados por el módulo se instalarán en el espacio de nombres global.
A continuación se muestra un ejemplo de importación de un módulo sin calificador:
import QtQuickEsta importación permite utilizar todos los tipos proporcionados por el módulo QtQuick sin necesidad de especificar un calificador. Por ejemplo, el código de cliente para crear un rectángulo es el siguiente:
import QtQuick
Rectangle {
width: 200
height: 100
color: "red"
}Un ejemplo de importación no calificada con versión sería
import QtQuick 2.10En ese caso, cualquier tipo definido en Qt Quick 2.11 y versiones posteriores, o en cualquier versión mayor posterior, como la 6.0, no estaría disponible para el archivo.
Un ejemplo de importación de un módulo calificado es el siguiente:
import QtQuick as QuickEsta importación permite importar al mismo tiempo varios módulos que proporcionan nombres de tipos conflictivos; sin embargo, dado que cada uso de un tipo proporcionado por un módulo que se haya importado a un espacio de nombres calificado debe ir precedido del calificador, el motor QML puede resolver el conflicto sin ambigüedad.
A continuación se muestra un ejemplo de código de cliente que crea un rectángulo tras utilizar una importación de módulo calificado:
import QtQuick as Quick
Quick.Rectangle {
width: 200
height: 100
color: "red"
}Para obtener más información sobre las importaciones calificadas, consulta la siguiente sección sobre la importación a un espacio de nombres local calificado.
Tenga en cuenta que, si un documento QML no importa un módulo que proporciona un tipo de objeto QML concreto, pero intenta utilizar ese tipo de objeto de todos modos, se producirá un error. Por ejemplo, el siguiente documento QML no importa QtQuick y, por lo tanto, el intento de utilizar el tipo Rectangle fallará:
Rectangle {
width: 200
height: 100
color: "red"
}En este caso, el motor generará un error y se negará a cargar el archivo.
Importaciones de módulos C++
Normalmente, los tipos de C++ se declaran utilizando las macros QML_ELEMENT y QML_NAMED_ELEMENT() y se registran a través del sistema de compilación mediante QML_IMPORT_NAME y QML_IMPORT_MAJOR_VERSION. El nombre de importación y la versión proporcionados de esta forma conforman un módulo que puede importarse para acceder a los tipos.
Esto es más habitual en aplicaciones cliente que definen sus propios tipos de objetos QML en C++.
Importación a un espacio de nombres local calificado
La instrucción ` import ` puede utilizar opcionalmente la palabra clave ` as ` para especificar que los tipos deben importarse a un espacio de nombres local del documento concreto. Si se especifica un espacio de nombres, cualquier referencia a los tipos puestos a disposición por la importación debe ir precedida del calificador del espacio de nombres local.
A continuación, el módulo QtQuick se importa al espacio de nombres «CoreItems». Ahora, cualquier referencia a los tipos del módulo QtQuick debe ir precedida del nombre CoreItems:
import QtQuick as CoreItems
CoreItems.Rectangle {
width: 100; height: 100
CoreItems.Text { text: "Hello, world!" }
// WRONG! No namespace prefix - the Text type won't be found
Text { text: "Hello, world!" }
}Un espacio de nombres actúa como identificador de un módulo dentro del ámbito del archivo. El espacio de nombres no se convierte en un atributo del objeto raíz al que se pueda hacer referencia externamente, como ocurre con las propiedades, las señales y los métodos.
La importación con espacio de nombres resulta útil si es necesario utilizar dos tipos QML que tienen el mismo nombre pero se encuentran en módulos diferentes. En este caso, los dos módulos pueden importarse a espacios de nombres distintos para garantizar que el código se refiera al tipo correcto:
import QtQuick as CoreItems
import TextWidgets as MyModule
CoreItems.Rectangle {
width: 100; height: 100
MyModule.Text { text: "Hello from my custom text item!" }
CoreItems.Text { text: "Hello from Qt Quick!" }
}Ten en cuenta que se pueden importar varios módulos en el mismo espacio de nombres, del mismo modo que se pueden importar varios módulos en el espacio de nombres global. Por ejemplo:
import QtQuick as Project
import QtMultimedia as Project
Project.Rectangle {
width: 100; height: 50
Project.Audio {
source: "music.wav"
autoPlay: true
}
}Importaciones de directorios
Un directorio que contenga documentos QML también puede importarse directamente en un documento QML. Esto ofrece una forma sencilla de segmentar los tipos QML en agrupaciones reutilizables: los directorios del sistema de archivos.
La forma genérica de importar un directorio es la siguiente:
import "<DirectoryPath>" [as <Qualifier>]Nota: Las rutasde importación son transparentes en red: las aplicaciones pueden importar documentos desde rutas remotas con la misma facilidad que desde rutas locales. Consulte las reglas generales de resolución de URL para la transparencia de red en documentos QML. Si el directorio es remoto, debe contener un archivo ` qmldir ` que enumere la importación del directorio, ya que el motor QML no puede determinar el contenido de un directorio remoto si dicho archivo ` ` no existe.
A las importaciones de directorios se les aplica una semántica similar a la de las importaciones de módulos en lo que respecta a ` <Qualifier> `; para obtener más información sobre este tema, consulta la sección anterior sobre la importación a un espacio de nombres local calificado.
Para obtener más información sobre las importaciones de directorios, consulta la documentación detallada al respecto.
Importaciones de recursos de JavaScript
Los recursos de JavaScript pueden importarse directamente en un documento QML. Cada recurso de JavaScript debe tener un identificador mediante el cual se acceda a él.
La forma genérica de una importación de recursos de JavaScript es la siguiente:
import "<JavaScriptFile>" as <Identifier>Ten en cuenta que el « <Identifier> » debe ser único dentro de un documento QML, a diferencia del calificador de espacio de nombres local, que puede aplicarse a las importaciones de módulos.
Recursos de JavaScript procedentes de módulos
Los módulos pueden proporcionar archivos JavaScript añadiendo definiciones de identificadores al archivo « qmldir », que especifica el módulo.
Por ejemplo, si el módulo ` projects.MyQMLProject.MyFunctions ` se especifica con el siguiente archivo ` qmldir ` y se instala en la ruta de importación de QML:
module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.jsuna aplicación cliente puede importar los recursos de JavaScript declarados en el módulo importando el módulo y utilizando el identificador asociado a un recurso declarado:
import QtQuick
import projects.MyQMLProject.MyFunctions
Item {
Component.onCompleted: { SystemFunctions.cleanUp(); }
}Si el módulo se ha importado a un espacio de nombres local del documento, los identificadores de los recursos de JavaScript deben ir precedidos del calificador del espacio de nombres para poder utilizarse:
import QtQuick
import projects.MyQMLProject.MyFunctions as MyFuncs
import org.example.Functions as TheirFuncs
Item {
Component.onCompleted: {
MyFuncs.SystemFunctions.cleanUp();
TheirFuncs.SystemFunctions.shutdown();
}
}Más información
Para obtener más información sobre los recursos de JavaScript, consulta la documentación sobre cómo definir recursos de JavaScript en QML; y para obtener más información sobre cómo importar recursos de JavaScript y cómo se pueden utilizar las importaciones desde dentro de los recursos de JavaScript, consulta la documentación detallada sobre la importación de recursos de JavaScript en QML.
Ruta de importación de QML
Cuando se importa un módulo identificado, el motor de Qml busca en la ruta de importación un módulo coincidente para cargar archivos Qml y complementos de módulos Qml. Qt asume que todos los archivos de la ruta de importación proceden de una fuente de confianza.
Esta ruta de importación, tal y como la devuelve la función ` QQmlEngine::importPathList()`, define las ubicaciones predeterminadas que el motor debe buscar. Por defecto, esta lista contiene, en este orden de prioridad:
- Rutas de paquetes específicas de la plataforma, si procede (por ejemplo, en macOS o Android)
- El directorio del binario de la aplicación
- La ruta qrc:/qt-project.org/imports dentro de los recursos.
- La ruta qrc:/qt/Qml dentro de los recursos (desde Qt 6.5).
- Las rutas especificadas por la variable de entorno `
QML2_IMPORT_PATH` (obsoleta) - Rutas especificadas por la variable de entorno `
QML_IMPORT_PATH` - La ubicación especificada por QLibraryInfo::QmlImportsPath
Si se establece el atributo ` Qt::AA_PluginApplication ` en ` QCoreApplication`, entonces el directorio de la aplicación, cualquier ruta especificada por variables de entorno y cualquier ruta de paquetes específica de la plataforma fuera del sistema de archivos de recursos se omiten por defecto.
Se pueden añadir rutas de importación adicionales mediante QQmlEngine::addImportPath() o la variable de entorno QML_IMPORT_PATH. Al ejecutar la herramienta qml, también puedes utilizar la opción -I para añadir una ruta de importación.
Se pueden especificar varias rutas de importación en la variable de entorno QML_IMPORT_PATH uniéndolas mediante el separador de rutas. En Windows, el separador de rutas es un punto y coma (;); en otras plataformas, es dos puntos (:). Esto significa que no se pueden especificar rutas de recursos ni URL en QML_IMPORT_PATH, ya que estas contienen dos puntos. Sin embargo, se pueden añadir rutas de recursos y URL llamando a QQmlEngine::addImportPath() mediante programación.
Nota: Se recomienda que las aplicaciones y bibliotecas coloquen sus módulos en «qrc:/qt/Qml». Esto ocurre de forma predeterminada cuando el módulo se crea con `qt_add_qml_module()` y QTP0001 está habilitado.
Depuración
La variable de entorno ` QML_IMPORT_TRACE ` puede resultar útil para la depuración cuando surgen problemas a la hora de localizar y cargar módulos. Consulte «Depuración de importaciones de módulos » 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.