QML での JavaScript リソースのインポート

JavaScriptリソースは、QMLドキュメントや他のJavaScriptリソースからインポートできます。JavaScriptリソースは、相対URLまたは絶対URLのいずれかを介してインポートできます。 相対URLの場合、その場所は、インポートを含むQML ドキュメントまたはJavaScriptリソースの場所を基準として解決されます。スクリプトファイルにアクセスできない場合、エラーが発生します。JavaScriptをネットワークリソースから取得する必要がある場合、スクリプトがダウンロードされるまで、コンポーネントのstatus は「Loading」に設定されます。

JavaScriptリソースは、QMLモジュールや他のJavaScriptリソースをインポートすることもできます。JavaScriptリソース内のimport文の構文は、QMLドキュメント内のimport文とは若干異なります。これについては、以下で詳しく説明します。

QMLドキュメントからのJavaScriptリソースのインポート

QMLドキュメントでは、次の構文を使用してJavaScriptリソースをインポートできます。

import "ResourceURL" as Qualifier

例：

import "jsfile.js" as Logic

インポートされた JavaScript リソースは、常に「as」キーワードを使用して修飾されます。 JavaScriptリソースの修飾子は大文字で始まり、一意でなければなりません。そのため、修飾子とJavaScriptファイルの間には常に一対一の対応関係があります。（これはまた、修飾子の名前がDate やMath などの組み込みJavaScriptオブジェクトと同じ名前にできないことを意味します）。

インポートされた JavaScript ファイルで定義された関数は、"Qualifier.functionName(params)" という構文を介して、インポート元の QML ドキュメントで定義されたオブジェクトから利用可能です。JavaScript リソース内の関数は、通常の JavaScript 型に加え、任意の QML 値型やオブジェクト型をパラメータとして受け取ることができます。QML からそのような関数を呼び出す際、パラメータおよび戻り値には通常のデータ型変換ルールが適用されます。

JavaScriptリソース内でのインポート

QtQuick 2.0 では、標準の QML インポート構文のバリエーションを使用して、JavaScript リソースが他の JavaScript リソースや QML 型の名前空間をインポートできるようにする機能が追加されました（この場合、前述のすべてのルールと条件が適用されます）。

QtQuick 2.0 では、JavaScript リソースがこのように別のスクリプトや QML モジュールをインポートできるようになったため、いくつかの追加のセマンティクスが定義されています：

• import 文を含むスクリプトは、それをインポートした QML ドキュメントからのインポートを継承しません（例えば、Component.errorString へのアクセスは失敗します）
• import 文を含まないスクリプトは、それをインポートした QML ドキュメントからのインポートを継承します（例えば、Component.errorString へのアクセスは成功します）
• 共有スクリプト（.pragma library として定義されたもの）は、たとえそのスクリプトが他のスクリプトやモジュールをインポートしていなくても、QMLドキュメントからのインポートを継承しません

特定のスクリプトが任意の数のQMLファイルからインポートされる可能性があることを考慮すると、最初の挙動は概念的に正しいものです。2番目の挙動は、下位互換性を確保するために維持されています。 3番目のセマンティクスは、共有スクリプトに関する現在のセマンティクスから変更はありませんが、新たに発生し得るケース（スクリプトが他のスクリプトやモジュールをインポートする場合）に関して、ここで明確化されています。

別の JavaScript リソースからの JavaScript リソースのインポート

JavaScriptリソースは、次のような方法で別のJavaScriptリソースをインポートできます：

import * as MathFunctions from "factorial.mjs";

あるいは：

.import "filename.js" as Qualifier

前者はECMAScriptモジュールをインポートするための標準的なECMAScript構文であり、mjs というファイル拡張子で示されるECMAScriptモジュール内からのみ機能します。後者はQML エンジンによって提供されるJavaScriptの拡張機能であり、モジュール以外のケースでも機能します。ECMAScript標準に置き換えられた拡張機能であるため、その使用は推奨されません。

JavaScript ファイルがこの方法でインポートされると、修飾子付きでインポートされます。その結果、そのファイル内の関数は、インポート元スクリプトからその修飾子を介して（つまり、Qualifier.functionName(params) として）利用可能になります。

場合によっては、修飾子を使用せずに、インポート元のコンテキストで関数を利用できるようにしたいことがあります。その場合は、ECMAScriptモジュールやJavaScriptのimport 文を、as 修飾子なしで使用する必要があります。

たとえば、左下のQMLコードはscript.mjs 内でshowCalculations() を呼び出しています。これにより、factorial.mjs 内のfactorial() を呼び出すことが可能になります。これは、import を使用してfactorial.mjs をインクルードしているためです。

import QtQuick
import "script.mjs" as MyScript

Item {
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            MyScript.showCalculations(10)
            console.log("Call factorial() from QML:",
                MyScript.factorial(10))
        }
    }
}

// script.mjs
import { factorial } from "factorial.mjs"
export { factorial }

export function showCalculations(value) {
    console.log(
        "Call factorial() from script.js:",
        factorial(value));
}

// factorial.mjs
export function factorial(a) {
    a = parseInt(a);
    if (a <= 0)
        return 1;
    else
        return a * factorial(a - 1);
}

Qt.include() 関数は、ECMAScript モジュールを使用せず、またインポートの修飾も行わずに、ある JavaScript ファイルから別のファイルをインポートします。これにより、もう一方のファイル内のすべての関数と変数が現在のファイルのネームスペースで利用可能になりますが、そのファイルで定義されたすべてのプラグマやインポートは無視されます。関数呼び出しは決して呼び出し元のコンテキストを変更してはならないため、これは推奨されません。

Qt.include()は非推奨であり、使用を避けるべきです。将来のQtのバージョンで削除される予定です。

JavaScriptリソースからのQMLモジュールのインポート

JavaScriptリソースは、次のようにQMLモジュールをインポートできます。

.import TypeNamespace MajorVersion.MinorVersion as Qualifier

以下は、JavaScriptでインポートされたモジュール内のQML型を使用する方法を示す例です：

.import Qt.test 1.0 as JsQtTest

var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3

特に、シングルトン型を通じて提供される機能にアクセスする場合に役立ちます。詳細については、QML_SINGLETON を参照してください。

JavaScriptリソースは、デフォルトでは、そのリソースをインポートしているコンポーネントのすべてのインポートにアクセスできます。ただし、コンポーネントがステートレスライブラリとして宣言されている場合（.pragma library を使用）、または明示的な `.import ` ステートメントが含まれている場合は、そのコンポーネントのインポートにはアクセスできません。