Заявления 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++ модулей

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

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

Отладка

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