Заявления import

Синтаксис оператора import

Оператор import позволяет клиенту указать движку, какие модули, JavaScript-ресурсы и каталоги компонентов используются в документе QML. Типы, которые могут быть использованы в документе, зависят от того, какие модули, ресурсы и каталоги импортированы в документе.

Типы импорта

Существует три различных типа импорта. Каждый тип импорта имеет немного отличающийся синтаксис, и к разным типам импорта применяются различные семантики.

Импорт модуля (пространства имен)

Наиболее распространённым типом импорта является импорт модуля. Клиенты могут импортировать QML-модули, которые регистрируют типы QML-объектов и JavaScript-ресурсы в заданном пространстве имен.

Общая форма импорта модуля:

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

• <ModuleIdentifier> — это идентификатор, заданный в обозначении URI с точками, который однозначно идентифицирует пространство имён типов, предоставляемое модулем.
• <Version.Number> — это версия в формате MajorVersion.MinorVersion, которая определяет, какие определения различных типов объектов и JavaScript-ресурсов будут доступны благодаря импорту.
• <Qualifier> — это необязательный локальный идентификатор пространства имён, в который будут установлены типы объектов и JavaScript-ресурсы, предоставляемые модулем, если он указан. Если он опущен, типы объектов и JavaScript-ресурсы, предоставляемые модулем, будут установлены в глобальное пространство имён.

Пример импорта модуля без квалификатора:

import QtQuick 2.0

Этот импорт позволяет использовать все типы, предоставляемые модулем QtQuick, без необходимости указывать квалификатор. Например, код клиента для создания прямоугольника выглядит следующим образом:

import QtQuick 2.0

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

Пример импорта модуля с квалификатором:

import QtQuick 2.0 as Quick

Этот импорт позволяет импортировать несколько модулей, предоставляющих конфликтующие имена типов, одновременно, однако, поскольку каждый вызов типа, предоставляемого модулем, импортированным в квалифицированное пространство имен, должен предваряться квалификатором, конфликт однозначно разрешается движком QML.

Пример кода клиента, который создаёт прямоугольник после использования импорта модуля с квалификатором, выглядит следующим образом:

import QtQuick 2.0 as Quick

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

Для получения дополнительной информации об импорте с квалификатором, см. раздел Импорт в квалифицированное локальное пространство имен.

Обратите внимание, что если документ QML не импортирует модуль, который предоставляет определённый тип QML-объекта, но пытается использовать этот тип, произойдёт ошибка. Например, следующий документ QML не импортирует QtQuick, и поэтому попытка использовать тип Rectangle завершится ошибкой:

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

В этом случае движок выведет ошибку и откажется от загрузки файла.

Импорт пространств имен, не являющихся модулями

Типы также могут быть зарегистрированы в пространствах имён напрямую с помощью различных функций регистрации в C++ (таких как qmlRegisterType()). Типы, зарегистрированные в пространстве имён таким образом, могут быть импортированы путём импорта пространства имён, как если бы идентификатор пространства имён был идентификатором модуля.

Это наиболее распространено в клиентских приложениях, которые определяют свои собственные типы QML-объектов в C++ и регистрируют их в системе типов QML вручную.

Импорт в квалифицированное локальное пространство имен

Оператор import может необязательно использовать ключевое слово as для указания того, что типы должны быть импортированы в определённое локальное пространство имён документа. Если пространство имён указано, то любые ссылки на типы, доступные благодаря импорту, должны предваряться квалификатором локального пространства имён.

Ниже модуль QtQuick импортируется в пространство имен «CoreItems». Теперь любые ссылки на типы из модуля QtQuick должны предваряться именем CoreItems:

import QtQuick 2.0 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!" }
}

Пространство имён действует как идентификатор модуля в рамках файла. Пространство имён не становится атрибутом корневого объекта, на который можно ссылаться внешне, как можно сделать со свойствами, сигналами и методами.

Пространство имён полезно, если необходимо использовать два QML-типа с одинаковым именем, но расположенные в разных модулях. В этом случае оба модуля можно импортировать в разные пространства имён, чтобы гарантировать, что код ссылается на правильный тип:

import QtQuick 2.0 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!" }
}

Обратите внимание, что несколько модулей можно импортировать в одно и то же пространство имен так же, как несколько модулей можно импортировать в глобальное пространство имен. Например:

import QtQuick 2.0 as Project
import QtMultimedia 5.0 as Project

Project.Rectangle {
    width: 100; height: 50

    Project.Audio {
        source: "music.wav"
        autoPlay: true
    }
}

Импорт каталога

Каталог, содержащий QML-документы, также может быть импортирован напрямую в QML-документ. Это предоставляет простой способ сегментации QML-типов в переиспользуемые группы: каталоги на файловой системе.

Общая форма импорта каталога:

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

Примечание: Пути импорта прозрачны к сети: приложения могут импортировать документы из удалённых путей так же просто, как и из локальных путей. См. общие правила разрешения URL для Прозрачности сети в QML-документах. Если каталог удалённый, он должен содержать файл списка импорта каталога qmldir, так как движок QML не может определить содержимое удалённого каталога, если этот qmldir файл не существует.

Аналогичные семантики для <Qualifier> применяются к импорту каталога, как и к импорту модуля; для получения дополнительной информации по данной теме, пожалуйста, обратитесь к предыдущему разделу о Импорте в квалифицированное локальное пространство имён.

Для получения дополнительной информации об импорте каталога, пожалуйста, обратитесь к подробной документации по импорту каталогов.

Импорт JavaScript-ресурсов

JavaScript-ресурсы могут быть импортированы непосредственно в документ QML. Каждый JavaScript-ресурс должен иметь идентификатор, с помощью которого он доступен.

Общая форма импорта JavaScript-ресурса:

import "<JavaScriptFile>" as <Identifier>

Обратите внимание, что <Identifier> должен быть уникальным в пределах документа QML, в отличие от квалификатора локального пространства имён, который может применяться к импорту модуля.

JavaScript-ресурсы из модулей

JavaScript-файлы могут предоставляться модулями, добавляя определения идентификаторов в qmldir файл, который определяет модуль.

Например, если модуль projects.MyQMLProject.MyFunctions указан с помощью следующего файла qmldir, и установлен в путь импорта QML:

module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js

приложение-клиент может импортировать объявленные в модуле JavaScript-ресурсы, импортировав модуль и используя идентификатор, связанный с объявленным ресурсом:

import QtQuick 2.0
import projects.MyQMLProject.MyFunctions 1.0

Item {
    Component.onCompleted: { SystemFunctions.cleanUp(); }
}

Если модуль был импортирован в локальное пространство имен документа, идентификаторы JavaScript-ресурсов должны быть опережаемы квалификатором пространства имён, чтобы быть использованными:

import QtQuick 2.0
import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
import org.example.Functions 1.0 as TheirFuncs

Item {
    Component.onCompleted: {
        MyFuncs.SystemFunctions.cleanUp();
        TheirFuncs.SystemFunctions.shutdown();
    }
}

Дополнительная информация

Для получения дополнительной информации о JavaScript-ресурсах, пожалуйста, обратитесь к документации о определении JavaScript-ресурсов в QML, а для получения дополнительной информации об импорте JavaScript-ресурсов и о том, как импорты могут быть использованы изнутри JavaScript-ресурсов, пожалуйста, обратитесь к подробной документации о импорте JavaScript-ресурсов в QML.

Путь импорта QML

При импорте идентифицированного модуля движок QML ищет соответствующий модуль в пути импорта.

Этот путь импорта, возвращаемый методом QQmlEngine::importPathList(), определяет стандартные места, которые движок ищет. По умолчанию этот список содержит:

• Каталог текущего файла
• Место, указанное в QLibraryInfo::Qml2ImportsPath
• Пути, указанные в переменной среды QML2_IMPORT_PATH
• Путь qrc:/qt-project.org/imports внутри ресурсов.

Дополнительные пути импорта можно добавить с помощью метода QQmlEngine::addImportPath() или переменной среды QML2_IMPORT_PATH. При запуске утилиты qmlscene также можно использовать параметр -I для добавления пути импорта.

Отладка

Переменная среды QML_IMPORT_TRACE может быть полезна для отладки при возникновении проблем с поиском и загрузкой модулей. См. Отладка импорта модулей для получения дополнительной информации.