Инструкции импорта

Синтаксис инструкции импорта

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

Типы импорта

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

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

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

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

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

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

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

import QtQuick

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

import QtQuick

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

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

import QtQuick 2.10

В этом случае любые типы, определённые в QtQuick 2.11 и выше или в любой более поздней основной версии, например 6.0, не будут доступны в файле.

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

import QtQuick as Quick

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

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

import QtQuick 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 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 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 as Project
import QtMultimedia as Project

Project.Rectangle {
    width: 100; height: 50

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

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

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

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

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

Аналогичные семантики для <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
import projects.MyQMLProject.MyFunctions

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

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

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

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

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

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

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

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

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

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

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

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

Отладка

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