インポート文

インポート文の構文

Importステートメントにより、クライアントは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

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

この方法は、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リソース

モジュールを指定するqmldir ファイルに識別子定義を追加することで、モジュールから Javascript ファイルを提供することができます。

例えば、qmldir でprojects.MyQMLProject.MyFunctions モジュールを指定し、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エンジンはインポートパスを検索し、 一致するモジュールを探します。

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

• 現在のファイルのディレクトリ
• で指定された場所。QLibraryInfo::QmlImportsPath
• QML_IMPORT_PATH 環境変数によって指定されるパス
• リソース内の qrc:/qt-project.org/imports パス。
• リソース内のqrc:/qt/qmlパス（Qt 6.5以降）。

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

QML_IMPORT_PATH 環境変数で複数のインポートパスを指定するには、パスの区切り文字を使 って連結します。Windowsではパスの区切り文字はセミコロン（;）ですが、他のプ ラットフォームではコロン（:）です。つまり、QML_IMPORT_PATHにリソースパスやURLを指定することはできません。しかし、QQmlEngine::addImportPath()をプログラムで呼び出すことで、リソースパスや URL を追加することができます。

デバッグ

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