Заявления 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 может быть полезна для отладки при проблемах с поиском и загрузкой модулей. См. Отладка импорта модулей для получения дополнительной информации.