Declaraciones de importación

Sintaxis de una sentencia import

Una sentencia import permite a los clientes indicar al motor qué módulos, recursos JavaScript y directorios de componentes se utilizan en un documento QML. Los tipos que pueden utilizarse en un documento dependen de los módulos, recursos y directorios que importe el documento.

Existen tres tipos diferentes de importaciones. Cada tipo de importación tiene una sintaxis ligeramente diferente, y se aplican diferentes semánticas a los distintos tipos de importación.

Importaciones de módulos (espacios de nombres)

El tipo de importación más comú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ódulo es la siguiente:

import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]

• <ModuleIdentifier> es un identificador especificado en notación URI con puntos, que identifica de forma exclusiva el espacio de nombres de tipos proporcionado por el módulo.
• El <Version.Number> es una versión de la forma MajorVersion.MinorVersion que especifica qué definiciones de varios tipos de objetos y recursos JavaScript estarán disponibles debido a la importación. Puede omitirse, en cuyo caso se importará la última versión del módulo. También es posible omitir sólo la versión menor. Entonces se importará la última versión menor de la versión mayor dada.
• <Qualifier> es un identificador de espacio de nombres local opcional en el que se instalarán los tipos de objeto y recursos JavaScript proporcionados por el módulo, si se indica. Si se omite, los tipos de objeto y recursos 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 módulo no cualificada:

import QtQuick

Esta importación permite el uso de todos los tipos proporcionados por el módulo QtQuick sin necesidad de especificar un calificador. Por ejemplo, el código cliente para crear un rectángulo es el siguiente:

import QtQuick

Rectangle {
    width: 200
    height: 100
    color: "red"
}

Un ejemplo de importación no cualificada con versión sería

import QtQuick 2.10

En ese caso, cualquier tipo definido en Qt Quick 2.11 y superiores o en cualquier versión mayor, como la 6.0, no estaría disponible para el archivo.

Un ejemplo de importación cualificada de módulos es el siguiente:

import QtQuick as Quick

Esta importación permite importar al mismo tiempo varios módulos que proporcionan nombres de tipos en conflicto, pero como cada uso de un tipo proporcionado por un módulo que se ha importado a un espacio de nombres cualificado debe ir precedido del cualificador, el motor QML puede resolver el conflicto sin ambigüedades.

A continuación se muestra un ejemplo de código cliente que crea un rectángulo tras utilizar una importación cualificada de módulo:

import QtQuick as Quick

Quick.Rectangle {
    width: 200
    height: 100
    color: "red"
}

Para obtener más información sobre las importaciones cualificadas, consulte la próxima sección sobre Importación a un espacio de nombres local cualificado.

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 tanto, al intentar utilizar el tipo Rectangle se producirá un error:

Rectangle {
    width: 200
    height: 100
    color: "red"
}

En este caso, el motor emitirá un error y se negará a cargar el archivo.

Importaciones de módulos C

Normalmente, los tipos C++ se declaran utilizando las macros QML_ELEMENT y QML_NAMED_ELEMENT() y se registran a través del sistema de compilación utilizando QML_IMPORT_NAME y QML_IMPORT_MAJOR_VERSION. El nombre de importación y la versión dados de esta forma forman un módulo que puede ser importado para acceder a los tipos.

Esto es muy común en aplicaciones cliente que definen sus propios tipos de objeto QML en C++.

Importación a un espacio de nombres local cualificado

La sentencia import puede utilizar opcionalmente la palabra clave as para especificar que los tipos deben importarse a un determinado espacio de nombres local del documento. Si se especifica un espacio de nombres, cualquier referencia a los tipos que la importación ponga a disposición deberá ir precedida del calificador de espacio de nombres local.

A continuación, el módulo QtQuick se importa en el 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 puede hacerse con las propiedades, señales y métodos.

La importación con espacio de nombres es ú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 en espacios de nombres diferentes para garantizar que el código hace referencia 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!" }
}

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

Importación de directorios

Un directorio que contenga documentos QML también puede importarse directamente en un documento QML. Esto proporciona una forma sencilla de segmentar los tipos QML en agrupaciones reutilizables: directorios en el sistema de archivos.

La forma genérica de una importación de directorios es la siguiente:

import "<DirectoryPath>" [as <Qualifier>]

A las importaciones de directorios se les aplica una semántica similar a la de las importaciones de módulos en <Qualifier>; para obtener más información sobre este tema, consulte la sección anterior sobre Importación a un espacio de nombres local cualificado.

Para obtener más información sobre las importaciones de directorios, consulte la documentación detallada sobre importaciones de directorios.

Importación de recursos JavaScript

Los recursos JavaScript pueden importarse directamente en un documento QML. Cada recurso JavaScript debe tener un identificador que permita acceder a él.

La forma genérica de una importación de recursos JavaScript es la siguiente:

import "<JavaScriptFile>" as <Identifier>

Tenga en cuenta que <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 JavaScript de módulos

Los archivos Javascript pueden ser proporcionados por módulos, 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.js

una aplicación cliente puede importar los recursos 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 en un espacio de nombres local del documento, los identificadores de recursos 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 JavaScript, consulte la documentación sobre la definición de recursos JavaScript en QML, y para obtener más información sobre cómo importar recursos JavaScript y cómo se pueden utilizar las importaciones desde dentro de los recursos JavaScript, consulte la documentación detallada sobre la importación de recursos JavaScript en QML.

Ruta de importación de QML

Cuando se importa un módulo identificado, el motor QML busca en la ruta de importación un módulo que coincida.

Esta ruta de importación, devuelta por QQmlEngine::importPathList(), define las ubicaciones predeterminadas en las que buscará el motor. Por defecto, esta lista contiene, en este orden de precedencia

• 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).
• 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 el atributo Qt::AA_PluginApplication se establece en QCoreApplication, entonces el directorio de la aplicación, cualquier ruta especificada por variables de entorno, y cualquier ruta de bundle 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 a través de QQmlEngine::addImportPath() o de la variable de entorno QML_IMPORT_PATH. Al ejecutar la herramienta qml, también puede utilizar la opción -I para añadir una ruta de importación.

Puede 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 son dos puntos (:). Esto significa que no puede especificar rutas de recursos o URLs en QML_IMPORT_PATH, ya que contienen dos puntos. Sin embargo, puede añadir rutas de recursos y URLs llamando a QQmlEngine::addImportPath() mediante programación.

Depuración de

La variable de entorno QML_IMPORT_TRACE puede ser útil para la depuración cuando hay problemas con la búsqueda y carga de módulos. Consulte Depuración de importaciones de módulos para obtener más información.