QMLドキュメント内のJavaScript式

QMLが提供するJavaScriptホスト環境では、条件演算子、配列、変数の設定、ループなど、標準的なJavaScript構文を実行できます。標準的なJavaScriptのプロパティに加え、QMLグローバルオブジェクトには、UIの構築やQML環境とのやり取りを簡略化する多数のヘルパーメソッドが含まれています。

QMLが提供するJavaScript環境は、Webブラウザのそれよりも厳格です。例えば、QMLではJavaScriptグローバルオブジェクトのメンバーに要素を追加したり、変更したりすることはできません。通常のJavaScriptでは、変数を宣言せずに使用することで、意図せずこれを行ってしまう可能性があります。QMLではこれが例外をスローするため、すべてのローカル変数は明示的に宣言する必要があります。 QMLから実行されるJavaScriptコードに対する制限の詳細については、「JavaScript環境の制限」を参照してください。

QMLドキュメントのさまざまな部分にJavaScriptコードを含めることができます：

1. プロパティバインディングの本体。これらの JavaScript 式は、QMLオブジェクトのプロパティ間の関係を記述します。プロパティの依存関係が変更されると、指定された関係に従って、そのプロパティも自動的に更新されます。
2. シグナルハンドラの本文。これらの JavaScript 文は、QML オブジェクトが関連するシグナルをエミットするたびに自動的に評価されます。
3. カスタムメソッドの定義。QMLオブジェクトの本体内で定義されたJavaScript関数は、そのオブジェクトのメソッドとなります。
4. 独立したJavaScript リソース (.js) ファイル。これらのファイルは実際には QML ドキュメントとは別個のものですが、QML ドキュメントにインポートすることができます。インポートされたファイル内で定義された関数や変数は、プロパティバインディング、シグナルハンドラ、およびカスタムメソッド内で使用できます。

プロパティバインディングにおける JavaScript

次の例では、Rectangle のcolor プロパティは、TapHandler のpressed プロパティに依存しています。この関係は、条件式を使用して記述されます：

import QtQuick 2.12

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: inputHandler.pressed ? "steelblue" : "lightsteelblue"

    TapHandler {
        id: inputHandler
    }
}

実際、式の結果がプロパティに代入可能な型の値である限り、どのようなJavaScript式（どれほど複雑であっても）でもプロパティバインディングの定義で使用できます。これには副作用も含まれます。ただし、複雑なバインディングや副作用は、コードのパフォーマンス、可読性、保守性を低下させる可能性があるため、推奨されません。

プロパティバインディングを定義するには2つの方法があります。最も一般的な方法は、前述の例で示したように、プロパティの初期化時に行うものです。2つ目の（そしてはるかに稀な）方法は、以下に示すように、命令型JavaScriptコード内からQt.binding()関数が返す関数をプロパティに代入することです：

import QtQuick 2.12

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: "red"

    TapHandler {
        id: inputHandler
    }

    Component.onCompleted: {
        color = Qt.binding(function() { return inputHandler.pressed ? "steelblue" : "lightsteelblue" });
    }
}

プロパティバインディングの定義方法の詳細については、プロパティバインディングのドキュメントを参照してください。また、バインディングと値の代入の違いについては、「プロパティの代入とプロパティバインディング」に関するドキュメントを参照してください。

シグナルハンドラ内のJavaScript

QML オブジェクト型は、特定のイベントの発生に応じてシグナルを発信できます。これらのシグナルは、シグナルハンドラ関数によって処理され、クライアントはこれらを定義してカスタムプログラムロジックを実装できます。

Rectangle型で表されるボタンに、TapHandler とTextラベルがあるとします。TapHandler は、ユーザーがボタンを押すとtapped シグナルを発行します。クライアントは、onTapped ハンドラ内でJavaScript式を使用して、このシグナルに応答することができます。 QMLエンジンは、必要に応じてハンドラー内で定義されたこれらのJavaScript式を実行します。通常、シグナルハンドラーは、他のイベントを発生させたり、プロパティの値を割り当てたりするために、JavaScript式にバインドされます。

import QtQuick 2.12

Rectangle {
    id: button
    width: 200; height: 80; color: "lightsteelblue"

    TapHandler {
        id: inputHandler
        onTapped: {
            // arbitrary JavaScript expression
            console.log("Tapped!")
        }
    }

    Text {
        id: label
        anchors.centerIn: parent
        text: inputHandler.pressed ? "Pressed!" : "Press here!"
    }
}

シグナルおよびシグナルハンドラに関する詳細については、以下のトピックを参照してください。

• シグナルとハンドラのイベントシステム
• QML オブジェクト属性

スタンドアロン関数内の JavaScript

プログラムロジックは、JavaScript関数でも定義できます。これらの関数は、QMLドキュメント内でインライン（カスタムメソッドとして）定義することも、インポートされたJavaScriptファイル内で外部定義することもできます。

カスタムメソッド内の JavaScript

カスタムメソッドはQMLドキュメント内で定義でき、シグナルハンドラ、プロパティバインディング、または他のQMLオブジェクト内の関数から呼び出すことができます。このようなメソッドは、その実装が外部のJavaScriptファイルではなくQMLオブジェクトの型定義（QMLドキュメント）に含まれているため、しばしば「インラインJavaScript関数」と呼ばれます。

インラインのカスタムメソッドの例は次のとおりです。

import QtQuick 2.12

Item {
    function fibonacci(n){
        var arr = [0, 1];
        for (var i = 2; i < n + 1; i++)
            arr.push(arr[i - 2] + arr[i -1]);

        return arr;
    }
    TapHandler {
        onTapped: console.log(fibonacci(10))
    }
}

TapHandler がtapped シグナルをエミットするたびに、fibonacci関数が実行されます。

JavaScript を使用して QML でカスタムメソッドを定義する方法の詳細については、QML オブジェクト属性のドキュメントを参照してください。

JavaScript ファイルで定義された関数

複雑なプログラムロジックは、別の JavaScript ファイルに分離するのが最適です。このファイルは、QMLモジュールと同様に、import ステートメントを使用して QML にインポートできます。

たとえば、前述の例にあるfibonacci() メソッドを、fib.js という名前の外部ファイルに移動し、次のようにアクセスすることができます。

import QtQuick 2.12
import "fib.js" as MathFunctions

Item {
    TapHandler {
        onTapped: console.log(MathFunctions.fibonacci(10))
    }
}

QMLへの外部JavaScriptファイルの読み込みに関する詳細については、「QMLでのJavaScriptリソースのインポート」のセクションを参照してください。

シグナルを JavaScript 関数に接続する

前のセクションで説明したように、シグナルを発行する QML オブジェクト型は、そのシグナルに対するデフォルトのシグナルハンドラも提供します。しかし、別の QML オブジェクトがシグナルを発行した際に、QML オブジェクトで定義された関数をクライアント側から呼び出したい場合があります。このようなシナリオは、シグナル接続によって処理できます。

QML オブジェクトが発するシグナルは、そのシグナルの `connect() ` メソッドを呼び出し、引数として JavaScript 関数を渡すことで、JavaScript 関数に接続できます。たとえば、次のコードは、`TapHandler` の `tapped ` シグナルを、script.js 内の `jsFunction() ` に接続しています：

import QtQuick
import "script.js" as MyScript

Item {
    id: item
    width: 200; height: 200

    TapHandler {
        id: inputHandler
    }

    Component.onCompleted: {
        inputHandler.tapped.connect(MyScript.jsFunction)
    }
}

// script.js

function jsFunction() {
    console.log("Called JavaScript function!")
}

TapHandler のtapped シグナルが発行されるたびに、jsFunction() が呼び出されます。

詳細については、「シグナルとメソッドおよびシグナルの接続」を参照してください。

アプリケーション起動コード内の JavaScript

アプリケーション（またはコンポーネントインスタンス）の起動時に、いくつかの命令型コードを実行する必要がある場合があります。起動スクリプトを外部スクリプトファイル内のグローバルコードとして単純に含めるのは魅力的ですが、QML環境が完全に確立されていない可能性があるため、これには深刻な制限が生じる恐れがあります。 たとえば、一部のオブジェクトがまだ作成されていない場合や、一部のプロパティバインディングが確立されていない場合があります。グローバルスクリプトコードの具体的な制限については、「JavaScript 環境の制限」を参照してください。

QMLオブジェクトは、インスタンス化が完了すると、Component.completed というアタッチドシグナルを発行します。対応するComponent.onCompleted ハンドラ内のJavaScriptコードは、オブジェクトがインスタンス化された後に実行されます。したがって、アプリケーションの起動コードを記述するのに最適な場所は、トップレベルオブジェクトのComponent.onCompleted ハンドラ内です。これは、QML環境が完全に確立された時点で、このオブジェクトがComponent.completed を発行するためです。

例：

import QtQuick 2.0

Rectangle {
    function startupFunction() {
        // ... startup code
    }

    Component.onCompleted: startupFunction();
}

QMLファイル内のあらゆるオブジェクト（ネストされたオブジェクトやネストされたQMLコンポーネントインスタンスを含む）は、このアタッチドプロパティを使用できます。起動時に実行すべきonCompleted() ハンドラが複数ある場合、それらは未定義の順序で順次実行されます。

同様に、すべてのComponent は、破棄される直前にdestruction()シグナルを放出します。