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

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

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

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