インポート文

インポート文の構文

インポート文を使用することで、クライアントはQMLドキュメント内でどのモジュール、JavaScriptリソース、およびコンポーネントディレクトリが使用されているかをエンジンに通知できます。ドキュメント内で使用可能な型は、そのドキュメントによってインポートされるモジュール、リソース、およびディレクトリによって異なります。

インポートには3つの異なるタイプがあります。各インポートタイプごとに構文がわずかに異なり、タイプごとに異なる意味論が適用されます。

モジュール（名前空間）のインポート

最も一般的なインポートの種類は、モジュールインポートです。クライアントは、QMLオブジェクト型やJavaScriptリソースを特定の名前空間に登録するQMLモジュールをインポートできます。

モジュールインポートの一般的な形式は次のとおりです。

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

この場合、Qt Quick 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` を使用して登録されます。このように指定されたインポート名とバージョンは、型にアクセスするためにインポート可能なモジュールを構成します。

これは、C++で独自のQMLオブジェクト型を定義するクライアントアプリケーションで最も一般的です。

修飾されたローカル名前空間へのインポート

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!" }
}

名前空間は、ファイルの範囲内におけるモジュールの識別子として機能します。名前空間は、プロパティ、シグナル、メソッドのように外部から参照可能なルートオブジェクトの属性にはなりません。

名前空間付きのインポートは、同じ名前を持つが異なるモジュールにある2つのQML型を使用する必要がある場合に役立ちます。この場合、コードが正しい型を参照するように、2つのモジュールを異なる名前空間にインポートすることができます：

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 リソースの詳細については、QML での JavaScript リソースの定義に関するドキュメントを参照してください。また、JavaScript リソースのインポート方法や、JavaScript リソース内からのインポートの使用方法については、QML での JavaScript リソースのインポートに関する詳細なドキュメントを参照してください。

QML インポートパス

識別されたモジュールがインポートされると、QMLエンジンはインポートパスを検索して一致するモジュールを探し、QMLファイルおよびQMLモジュールプラグインをロードします。Qtは、インポートパス下のすべてのファイルが信頼できるソースからのものであると想定しています。

QQmlEngine::importPathList() によって返されるこのインポートパスは、エンジンが検索するデフォルトの場所を定義します。デフォルトでは、このリストには以下の優先順位で含まれます：

• 該当する場合のプラットフォーム固有のバンドルパス（macOS や Android など）
• アプリケーションバイナリのディレクトリ
• resources 内の qrc:/qt-project.org/imports パス
• resources 内の qrc:/qt/Qml パス（Qt 6.5 以降）
• QML2_IMPORT_PATH 環境変数で指定されたパス（非推奨）
• QML_IMPORT_PATH 環境変数で指定されたパス
• で指定された場所QLibraryInfo::QmlImportsPath

QCoreApplication でQt::AA_PluginApplication 属性が設定されている場合、アプリケーションディレクトリ、環境変数で指定されたパス、およびリソースファイルシステム外のプラットフォーム固有のバンドルパスは、デフォルトで省略されます。

追加のインポートパスは、QQmlEngine::addImportPath() またはQML_IMPORT_PATH 環境変数を通じて追加できます。qml ツールを実行する際は、-I オプションを使用してインポートパスを追加することもできます。

QML_IMPORT_PATH 環境変数では、パス区切り文字を使用して複数のインポートパスを指定できます。 Windows ではパス区切り文字はセミコロン (;) ですが、その他のプラットフォームではコロン (:) です。つまり、リソースパスや URL にはそれ自体がコロンを含んでいるため、QML_IMPORT_PATH で指定することはできません。ただし、QQmlEngine::addImportPath() をプログラムから呼び出すことで、リソースパスや URL を追加することは可能です。

デバッグ

モジュールの検索や読み込みに問題がある場合、QML_IMPORT_TRACE 環境変数がデバッグに役立ちます。詳細については、「モジュールインポートのデバッグ」を参照してください。