Qt WebChannel API JavaScript

Configuration de l'API JavaScript

Pour communiquer avec QWebChannel ou WebChannel, un client doit utiliser et configurer l’API JavaScript fournie par qwebchannel.js. Pour les clients s’exécutant en Qt WebEngine, vous pouvez charger le fichier via qrc:///qtwebchannel/qwebchannel.js si vous chargez la page localement, ou rendre qwebchannel.js accessible depuis un QWebEngineUrlSchemeHandler enregistré auprès de QWebEngineUrlScheme sous le nom QWebEngineUrlScheme::SecureScheme. Pour les clients externes, vous devez copier le fichier sur votre serveur web. Instanciez ensuite un objet ` QWebChannel ` et transmettez-lui un objet `transport` ainsi qu’une fonction de rappel, qui sera appelée une fois l’initialisation du canal terminée et les objets publiés disponibles. Un troisième argument facultatif contient un tableau de fonctions de conversion ou une seule fonction.

L’objet « transport » implémente une interface minimale de passage de messages. Il doit s’agir d’un objet doté d’une fonction « send() », qui prend un message JSON sous forme de chaîne de caractères et le transmet à l’objet « QWebChannelAbstractTransport » côté serveur. De plus, sa propriété « onmessage » doit être appelée lorsqu’un message provenant du serveur est reçu. Vous pouvez également utiliser un WebSocket pour implémenter cette interface.

Notez que l’objet JavaScript ` QWebChannel ` doit être instancié une fois que l’objet de transport est pleinement opérationnel. Dans le cas d’un WebSocket, cela signifie que vous devez créer l’objet ` QWebChannel ` dans le gestionnaire ` onopen ` du socket. Consultez l’exemple autonome «Qt WebChannel » pour voir comment procéder.

Une fonction de wrapper de convertisseur est soit une chaîne de caractères contenant le nom d’un convertisseur intégré, soit une fonction fournie par l’utilisateur qui prend l’objet à traiter en argument et renvoie le type résultant ou « undefined » si la fonction ne s’applique pas. Si « undefined » est renvoyé, le convertisseur suivant est traité. S’il n’existe aucun convertisseur renvoyant une valeur autre que « undefined », le traitement se poursuit normalement. « Date » est actuellement la seule fonction de conversion intégrée. Elle prend en paramètre une chaîne de caractères contenant une date au format ISO 8601 et renvoie un nouvel objet Date si la syntaxe est correcte et la date valide.

Interaction avec les QObjects

Une fois que la fonction de rappel transmise à l’objet ` QWebChannel ` est invoquée, le canal a terminé son initialisation et tous les objets publiés sont accessibles au client HTML via la propriété ` channel.objects `. Ainsi, en supposant qu’un objet ait été publié avec l’identifiant « foo », nous pouvons alors interagir avec lui comme le montre l’exemple ci-dessous. Notez que toutes les communications entre le client HTML et le serveur QML/C++ sont asynchrones. Les propriétés sont mises en cache côté HTML. Gardez également à l’esprit que seuls les types de données QML/C++ pouvant être convertis en JSON seront correctement (dé)sérialisés et donc accessibles aux clients HTML.

new QWebChannel(yourTransport, function(channel) {

    // Connect to a signal:
    channel.objects.foo.mySignal.connect(function() {
        // This callback will be invoked whenever the signal is emitted on the C++/QML side.
        console.log(arguments);
    });

    // To make the object known globally, assign it to the window object, i.e.:
    window.foo = channel.objects.foo;

    // Invoke a method:
    foo.myMethod(arg1, arg2, function(returnValue) {
        // This callback will be invoked when myMethod has a return value. Keep in mind that
        // the communication is asynchronous, hence the need for this callback.
        console.log(returnValue);
    });

    // Read a property value, which is cached on the client side:
    console.log(foo.myProperty);

    // Writing a property will instantly update the client side cache.
    // The remote end will be notified about the change asynchronously
    foo.myProperty = "Hello World!";

    // To get notified about remote property changes,
    // simply connect to the corresponding notify signal:
    foo.myPropertyChanged.connect(function() {
        console.log(foo.myProperty);
    });

    // One can also access enums that are marked with Q_ENUM:
    console.log(foo.MyEnum.MyEnumerator);
});

Méthodes et signaux surchargés

Lorsque vous publiez une « QObject » comportant des méthodes surchargées, QWebChannel résoudra les appels de méthode en choisissant la meilleure correspondance. Notez qu’en raison du système de types de JavaScript, il n’existe qu’un seul type « number » qui correspond le mieux à un « double » en C++. Lorsque les surcharges ne diffèrent que par le type d’un paramètre de type numérique, QWebChannel choisira toujours la surcharge qui correspond le mieux au type « number » de JavaScript. Lorsque vous vous connectez à un signal surchargé, le client QWebChannel ne se connectera par défaut qu’à la première surcharge de signal portant ce nom. De plus, les surcharges de méthodes et de signaux peuvent être explicitement demandées via leur signature complète d’ QMetaMethod. Supposons que nous ayons la sous-classe « QObject » suivante côté C++ :

class Foo : public QObject
{
    Q_OBJECT
slots:
    void foo(int i);
    void foo(double d);
    void foo(const QString &str);
    void foo(const QString &str, int i);

signals:
    void bar(int i);
    void bar(const QString &str);
    void bar(const QString &str, int i);
};

Vous pouvez alors interagir avec cette classe côté JavaScript de la manière suivante :

// methods
foo.foo(42); // will call the method named foo which best matches the JavaScript number parameter, i.e. foo(double d)
foo.foo("asdf"); // will call foo(const QString &str)
foo.foo("asdf", 42); // will call foo(const QString &str, int i)
foo["foo(int)"](42); // explicitly call foo(int i), *not* foo(double d)
foo["foo(QString)"]("asdf"); // explicitly call foo(const QString &str)
foo["foo(QString,int)"]("asdf", 42); // explicitly call foo(const QString &str, int i)

// signals
foo.bar.connect(...); // connect to first signal named bar, i.e. bar(int i)
foo["bar(int)"].connect(...); // connect explicitly to bar(int i)
foo["bar(QString)"].connect(...); // connect explicitly to bar(const QString &str)
foo["bar(QString,int)"].connect(...); // connect explicitly to bar(const QString &str, int i)