JavaScript ホスト環境

QMLは、QMLアプリケーションの作成に特化したJavaScriptホスト環境を提供します。この環境は、ブラウザやNode.jsなどのサーバーサイドJavaScript環境が提供するホスト環境とは異なります。例えば、QMLには、ブラウザ環境で一般的に見られるwindow オブジェクトやDOM API は提供されません。

共通の基盤

ブラウザやサーバーサイドの JavaScript 環境と同様に、QML Runtime はECMAScript 言語仕様の標準を実装しています。これにより、Object、Array、Math など、標準で定義されているすべての組み込み型や関数にアクセスできます。QML Runtime は、この標準の第 7 版を実装しています。

Nullish Coalescing(??) (Qt 5.15 以降) およびOptional Chaining(?.) (Qt 6.2 以降) も QML Runtime で実装されています。

さらに、Qt 6.8 以降では、数値リテラル区切り記号（1_000_000 におけるアンダースコア）がサポートされています。

標準の ECMAScript 組み込み関数については、QML のドキュメントには明示的に記載されていません。それらの使用方法の詳細については、ECMA-262 第 7 版規格、またはW3Schools JavaScript リファレンス（JavaScript オブジェクトのリファレンスセクション）など、数多くのオンライン JavaScript リファレンスやチュートリアルサイトをご参照ください。 多くのサイトはブラウザ上の JavaScript に焦点を当てているため、場合によっては、特定の関数やオブジェクトが標準の ECMAScript の一部であるか、それともブラウザ環境固有のものであるかを確認するために、仕様書を再確認する必要があるかもしれません。 上記の W3Schools のリンクの場合、「JavaScript Objects Reference 」セクションは概ね標準を網羅していますが、「Browser Objects Reference 」および「HTML DOM Objects Reference 」のセクションはブラウザ固有のものであり（したがって QML には適用されません）。

型注釈とアサーション

QMLドキュメント内の関数宣言には、型注釈を含めることができ、また含めるべきです。型注釈は、引数の宣言および関数自体に付加され、戻り値の型を明示します。以下の関数は、int およびstring パラメータを受け取り、QtObject を返します：

function doThings(a: int, b: string) : QtObject { ... }

型注釈は、 Qt Creator やqmllintといったツールがコードを理解し、より適切な診断情報を提供することを助けます。さらに、C++ から関数を利用しやすくなります。詳細については、「C++ から QML オブジェクトとの連携」を参照してください。

この規則の例外は、シグナルハンドラに割り当てられる関数です。そこでは、シグナルの型との潜在的な不一致を避けるため、型注釈の使用が禁止されています。シグナル自体がすでに必要な情報を提供しているため、これはツール運用上の問題にはなりません。

型アサーション（as-cast とも呼ばれる）は、オブジェクトを別のオブジェクト型にキャストするためにも使用できます。オブジェクトが実際に指定された型である場合、型アサーションは同じオブジェクトを返します。そうでない場合は、null を返します。以下のスニペットでは、parent オブジェクトがRectangle であることを確認してから、その特定のメンバにアクセスしています。

Item {
    property color parentColor: (parent as Rectangle)?.color || "red"
}

オプショナルチェーン（?. ）を使用することで、親オブジェクトが実際には矩形（rectangle）でない場合でも例外がスローされるのを回避できます。その場合、「red」はparentColor として扱われます。

Qt 6.7 以降、関数の呼び出し時には型注釈が常に強制されます。必要に応じて、値は必要な型に強制変換されます。 以前は、型注釈はインタプリタおよびJITコンパイラでは無視されていましたが、C++へのコンパイル時には qmlcachegenおよびqmlscによって強制されていました。これにより、一部の特殊なケースにおいて動作に違いが生じる可能性がありました。インタプリタおよびJITの従来の動作を明示的に要求するには、QMLドキュメントに以下を追加してください：

pragma FunctionSignatureBehavior: Ignored

QML グローバルオブジェクト

QML JavaScript ホスト環境は、QML グローバルオブジェクトのドキュメントに詳述されているように、多数のホストオブジェクトと関数を実装しています。

これらのホストオブジェクトおよび関数は、モジュールがインポートされているかどうかに関係なく、常に利用可能です。

JavaScript オブジェクトと関数

QML エンジンがサポートする JavaScript オブジェクト、関数、およびプロパティの一覧は、「JavaScript オブジェクトおよび関数のリスト」に記載されています。

なお、QML ではネイティブオブジェクトに対して以下の変更が行われます。

• `String ` プロトタイプに `arg() ` 関数が追加されます。
• DateおよびNumberのプロトタイプに、ロケールに応じた変換関数が追加されます。

関連項目：

• Number- JavaScriptのNumberオブジェクト
• Date- JavaScriptのDateオブジェクト
• XMLHttpRequest- JavaScript オブジェクト「XMLHttpRequest」

さらに、QML では `instanceof` 関数の動作を拡張し、QML 型に対する型チェックが可能になっています。これにより、変数が期待通りの型であるかどうかを検証するためにこの関数を使用できます。例えば、次のようにします。

var v = something();
if (!v instanceof Item) {
    throw new TypeError("I need an Item type!");
}

...

JavaScript 環境の制限

QML では、JavaScript コードに対して以下の制限が設けられています:

• .qml ファイル内に記述されたJavaScriptコードは、グローバルオブジェクトを変更することはできません。.jsファイル内のJavaScriptコードはグローバルオブジェクトを変更することができ、その変更内容はインポート時に.qmlファイルから参照可能になります。

  QML において、グローバルオブジェクトは不変です。既存のプロパティを変更または削除することはできず、新しいプロパティを作成することもできません。

  ほとんどの JavaScript プログラムは、意図的にグローバルオブジェクトを変更することはありません。ただし、JavaScript による未宣言変数の自動生成は、グローバルオブジェクトに対する暗黙的な変更にあたるため、QML では禁止されています。

  a 変数がスコープチェーンに存在しないと仮定すると、以下のコードはQMLでは無効となります：

  // Illegal modification of undeclared variable
  a = 1;
  for (var ii = 1; ii < 10; ++ii)
      a = a * ii;
  console.log("Result: " + a);

  これを少し変更するだけで、以下の有効なコードにすることができます。

  var a = 1;
  for (var ii = 1; ii < 10; ++ii)
      a = a * ii;
  console.log("Result: " + a);

  グローバルオブジェクトを（暗黙的または明示的に）変更しようとすると、例外が発生します。この例外がキャッチされなかった場合、問題のあるコードのファイル名と行番号を含む警告メッセージが表示されます。

• グローバルコードは、範囲が制限されたスコープ内で実行されます。

  起動時、QMLファイルが「グローバル」コードを含む外部JavaScriptファイルをインクルードしている場合、そのコードは、外部ファイル自体とグローバルオブジェクトのみを含むスコープ内で実行されます。つまり、通常であればアクセスできるはずのQMLオブジェクトやプロパティにはアクセスできません。

  スクリプトのローカル変数にのみアクセスするグローバルコードは許可されます。以下は、有効なグローバルコードの例です。

  var colors = [ "red", "blue", "green", "orange", "purple" ];

  QMLオブジェクトにアクセスするグローバルコードは、正しく実行されません。

  // Invalid global code - the "rootObject" variable is undefined
  var initialPosition = { rootObject.x, rootObject.y }

  この制限は、QML 環境がまだ完全に構築されていないために生じています。環境のセットアップが完了した後にコードを実行するには、「アプリケーション起動コードでの JavaScript」を参照してください。

• this の値は、QMLのほとんどのコンテキストにおいて未定義です。

  this キーワードは、JavaScriptからプロパティをバインドする際にサポートされています。QMLのバインド式、QMLのシグナルハンドラ、およびQMLで宣言された関数においては、this はスコープオブジェクトを指します。それ以外のすべての状況において、QMLにおけるthis の値は未定義となります。

  特定のオブジェクトを参照するには、id を指定します。例：

  Item {
      width: 200; height: 100
      function mouseAreaClicked(area) {
          console.log("Clicked in area at: " + area.x + ", " + area.y);
      }
      // This will pass area to the function
      MouseArea {
          id: area
          y: 50; height: 50; width: 200
          onClicked: mouseAreaClicked(area)
      }
  }