Заявления об импорте

Синтаксис заявления об импорте

Заявление об импорте позволяет клиенту указать движку, какие модули, 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++-модулей

Обычно C++-типы объявляются с помощью макросов QML_ELEMENT и QML_NAMED_ELEMENT() и регистрируются через систему сборки с помощью QML_IMPORT_NAME и QML_IMPORT_MAJOR_VERSION. Таким образом, имя и версия импорта формируют модуль, который можно импортировать для доступа к типам.

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

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

Заявление 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 не может определить содержимое удалённого каталога, если этот файл не существует.

Аналогичная семантика для <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, чтобы добавить путь импорта.

В переменной среды QML2_IMPORT_PATH можно указать несколько путей импорта, объединив их с разделителем путей. В Windows разделителем путей является точка с запятой (;), на других платформах — двоеточие (:). Это означает, что вы не можете указать пути к ресурсам или URL-адреса в QML2_IMPORT_PATH, так как они сами содержат двоеточия. Однако вы можете добавить пути к ресурсам и URL-адреса, вызвав QQmlEngine::addImportPath() программно.

Отладка

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