JavaScript-Ausdrücke in QML-Dokumenten

Die von QML bereitgestellte JavaScript-Hostumgebung kann gültige Standard-JavaScript-Konstrukte wie bedingte Operatoren, Arrays, Variablenzuweisungen und Schleifen ausführen. Zusätzlich zu den Standard-JavaScript-Eigenschaften enthält das QML-Globalobjekt eine Reihe von Hilfsmethoden, die die Erstellung von Benutzeroberflächen und die Interaktion mit der QML-Umgebung vereinfachen.

Die von QML bereitgestellte JavaScript-Umgebung ist strenger als die in einem Webbrowser. So ist es beispielsweise in QML nicht möglich, Elemente des globalen JavaScript-Objekts hinzuzufügen oder zu ändern. In normalem JavaScript kann dies versehentlich geschehen, wenn eine Variable verwendet wird, ohne sie zuvor zu deklarieren. In QML löst dies eine Ausnahme aus, sodass alle lokalen Variablen explizit deklariert werden müssen. Eine vollständige Beschreibung der Einschränkungen für JavaScript-Code, der aus QML heraus ausgeführt wird, finden Sie unter „Einschränkungen der JavaScript-Umgebung “.

Verschiedene Teile von QML-Dokumenten können JavaScript-Code enthalten:

1. Der Hauptteil von Eigenschaftsbindungen. Diese JavaScript-Ausdrücke beschreiben Beziehungen zwischen den Eigenschaften von QML-Objekten. Wenn sich die Abhängigkeiten einer Eigenschaft ändern, wird die Eigenschaft entsprechend der angegebenen Beziehung automatisch aktualisiert.
2. Der Hauptteil von Signal-Handlern. Diese JavaScript-Anweisungen werden automatisch ausgewertet, sobald ein QML-Objekt das zugehörige Signal aussendet.
3. Die Definition benutzerdefinierter Methoden. JavaScript-Funktionen, die im Hauptteil eines QML-Objekts definiert werden, werden zu Methoden dieses Objekts.
4. Eigenständige JavaScript-Ressourcendateien (.js). Diese Dateien sind eigentlich von QML-Dokumenten getrennt, können jedoch in QML-Dokumente importiert werden. Funktionen und Variablen, die in den importierten Dateien definiert sind, können in Eigenschaftsbindungen, Signal-Handlern und benutzerdefinierten Methoden verwendet werden.

JavaScript in Eigenschaftsbindungen

Im folgenden Beispiel hängt die Eigenschaft „ color “ von „ Rectangle “ von der Eigenschaft „ pressed “ von „ TapHandler “ ab. Diese Beziehung wird mithilfe eines bedingten Ausdrucks beschrieben:

import QtQuick 2.12

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

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

    TapHandler {
        id: inputHandler
    }
}

Tatsächlich kann jeder JavaScript-Ausdruck (egal wie komplex) in einer Eigenschaftsbindungsdefinition verwendet werden, solange das Ergebnis des Ausdrucks ein Wert ist, dessen Typ der Eigenschaft zugewiesen werden kann. Dies schließt Nebeneffekte ein. Von komplexen Bindungen und Nebeneffekten wird jedoch abgeraten, da sie die Leistung, Lesbarkeit und Wartbarkeit des Codes beeinträchtigen können.

Es gibt zwei Möglichkeiten, eine Eigenschaftsbindung zu definieren: Die gängigste wird im vorangegangenen Beispiel bei der Initialisierung einer Eigenschaft gezeigt. Die zweite (und weitaus seltenere) Möglichkeit besteht darin, der Eigenschaft eine von der Funktion ` Qt.binding()` zurückgegebene Funktion innerhalb von imperativem JavaScript-Code zuzuweisen, wie unten dargestellt:

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" });
    }
}

Weitere Informationen zur Definition von Eigenschaftsbindungen finden Sie in der Dokumentation zu Eigenschaftsbindungen, und Informationen darüber, wie sich Bindungen von Wertzuweisungen unterscheiden, finden Sie in der Dokumentation zum Thema „Eigenschaftszuweisung versus Eigenschaftsbindung “.

JavaScript in Signal-Handlern

QML-Objekttypen können als Reaktion auf bestimmte Ereignisse Signale aussenden. Diese Signale können von Signalbehandlungsfunktionen verarbeitet werden, die von Clients definiert werden können, um benutzerdefinierte Programmlogik zu implementieren.

Angenommen, eine Schaltfläche vom Typ „Rectangle“ verfügt über eine „ TapHandler “ und ein „Text“-Label. Die „ TapHandler “ sendet ihr Signal „ tapped “ aus, wenn der Benutzer die Schaltfläche drückt. Die Clients können im „ onTapped “-Handler mithilfe von JavaScript-Ausdrücken auf das Signal reagieren. Die QML-Engine führt diese im Handler definierten JavaScript-Ausdrücke nach Bedarf aus. In der Regel wird ein Signal-Handler an JavaScript-Ausdrücke gebunden, um andere Ereignisse auszulösen oder Eigenschaftswerte zuzuweisen.

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

Weitere Informationen zu Signalen und Signal-Handlern finden Sie in den folgenden Themen:

• Signal- und Handler-Ereignissystem
• QML-Objektattribute

JavaScript in eigenständigen Funktionen

Programmlogik kann auch in JavaScript-Funktionen definiert werden. Diese Funktionen können inline in QML-Dokumenten (als benutzerdefinierte Methoden) oder extern in importierten JavaScript-Dateien definiert werden.

JavaScript in benutzerdefinierten Methoden

Benutzerdefinierte Methoden können in QML-Dokumenten definiert und von Signal-Handlern, Eigenschaftsbindungen oder Funktionen in anderen QML-Objekten aufgerufen werden. Solche Methoden werden oft als Inline-JavaScript-Funktionen bezeichnet, da ihre Implementierung in der QML-Objekttypdefinition (QML-Dokument) enthalten ist und nicht in einer externen JavaScript-Datei.

Ein Beispiel für eine benutzerdefinierte Inline-Methode lautet wie folgt:

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))
    }
}

Die Fibonacci-Funktion wird immer dann ausgeführt, wenn das „ TapHandler “ ein „ tapped “-Signal aussendet.

Weitere Informationen zum Definieren benutzerdefinierter Methoden in QML mithilfe von JavaScript finden Sie in der Dokumentation zu QML-Objektattributen.

In einer JavaScript-Datei definierte Funktionen

Nicht-triviale Programmlogik sollte am besten in eine separate JavaScript-Datei ausgelagert werden. Diese Datei kann mithilfe einer ` import `-Anweisung in QML importiert werden, ähnlich wie bei QML-Modulen.

Beispielsweise könnte die Methode „ fibonacci() “ aus dem vorherigen Beispiel in eine externe Datei namens „ fib.js “ verschoben und wie folgt aufgerufen werden:

import QtQuick 2.12
import "fib.js" as MathFunctions

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

Weitere Informationen zum Laden externer JavaScript-Dateien in QML finden Sie im Abschnitt „Importieren von JavaScript-Ressourcen in QML“.

Signale mit JavaScript-Funktionen verknüpfen

QML-Objekttypen, die Signale aussenden, stellen, wie im vorherigen Abschnitt beschrieben, auch Standard-Signalhandler für ihre Signale bereit. Manchmal möchte ein Client jedoch eine in einem QML-Objekt definierte Funktion auslösen, wenn ein anderes QML-Objekt ein Signal aussendet. Solche Szenarien lassen sich durch eine Signalverbindung handhaben.

Ein von einem QML-Objekt ausgesendetes Signal kann mit einer JavaScript-Funktion verbunden werden, indem die Methode ` connect() ` des Signals aufgerufen und die JavaScript-Funktion als Argument übergeben wird. Der folgende Code verbindet beispielsweise das Signal ` tapped ` des Objekts ` TapHandler` mit der Funktion ` jsFunction() ` in ` script.js`:

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

Die Methode „ jsFunction() “ wird jedes Mal aufgerufen, wenn das Signal „ tapped “ des „ TapHandler “ ausgegeben wird.

Weitere Informationen finden Sie unter „Signale mit Methoden und Signalen verknüpfen “.

JavaScript im Startcode der Anwendung

Gelegentlich ist es erforderlich, beim Start der Anwendung (oder einer Komponenteninstanz) imperativen Code auszuführen. Es ist zwar verlockend, das Startskript einfach als globalen Code in eine externe Skriptdatei einzufügen, dies kann jedoch erhebliche Einschränkungen mit sich bringen, da die QML-Umgebung möglicherweise noch nicht vollständig eingerichtet ist. Beispielsweise könnten einige Objekte noch nicht erstellt oder einige Eigenschaftsbindungen noch nicht eingerichtet worden sein. Die genauen Einschränkungen für globalen Skriptcode finden Sie unter „Einschränkungen der JavaScript-Umgebung “.

Ein QML-Objekt sendet das Signal „ Component.completed “ aus, sobald seine Instanziierung abgeschlossen ist. Der JavaScript-Code im entsprechenden „ Component.onCompleted “-Handler wird ausgeführt, nachdem das Objekt instanziiert wurde. Daher ist der beste Ort zum Schreiben von Startcode für die Anwendung der „ Component.onCompleted “-Handler des Objekts der obersten Ebene, da dieses Objekt das Signal „ Component.completed “ aussendet, sobald die QML-Umgebung vollständig eingerichtet ist.

Beispiel:

import QtQuick 2.0

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

    Component.onCompleted: startupFunction();
}

Jedes Objekt in einer QML-Datei – einschließlich verschachtelter Objekte und verschachtelter QML-Komponenteninstanzen – kann diese angehängte Eigenschaft nutzen. Wenn beim Start mehr als ein ` onCompleted() `-Handler ausgeführt werden soll, werden diese nacheinander in einer nicht definierten Reihenfolge ausgeführt.

Ebenso sendet jedes „ Component “ kurz vor seiner Löschung ein „ destruction()“-Signal aus.