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 exécutés à l'intérieur de Qt WebEnginevous pouvez charger le fichier via qrc:///qtwebchannel/qwebchannel.js. Pour les clients externes, vous devez copier le fichier sur votre serveur web. Instanciez ensuite un objet QWebChannel et transmettez-lui un objet de transport et une fonction de rappel, qui sera invoquée lorsque l'initialisation du canal sera terminée et que les objets publiés seront disponibles. Un troisième argument facultatif contient un tableau de fonctions d'enveloppe de convertisseur ou une seule.

L'objet de transport met en œuvre une interface minimale de transmission de messages. Il doit s'agir d'un objet doté d'une fonction send(), qui prend un message JSON filtré et le transmet à l'objet QWebChannelAbstractTransport côté serveur. En outre, sa propriété onmessage doit être appelée lorsqu'un message du serveur a été reçu. Vous pouvez également utiliser une WebSocket pour mettre en œuvre l'interface.

Notez que l'objet JavaScript QWebChannel doit être construit une fois que l'objet de transport est pleinement opérationnel. Dans le cas d'une WebSocket, cela signifie que vous devez créer l'objet QWebChannel dans le gestionnaire onopen de la socket. Jetez un coup d'œil à l'exemple autonomeQt WebChannel pour voir comment procéder.

Une fonction d'enveloppe de convertisseur est soit une chaîne avec le nom d'un convertisseur intégré, soit une fonction fournie par l'utilisateur qui prend l'objet à traiter comme argument et renvoie le type résultant ou undefined si la fonction ne s'applique pas. Si la fonction renvoie un type indéfini, le convertisseur suivant est traité. Si aucun convertisseur ne renvoie une valeur autre que non définie, le traitement se poursuit normalement. "Date" est la seule fonction de conversion actuellement intégrée. Elle prend une chaîne avec une date ISO 8601 et renvoie un nouvel objet Date si la syntaxe est correcte et si la date est valide.

Interagir avec les QObjects

Une fois que le rappel passé à l'objet QWebChannel est invoqué, 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 interagir avec lui comme indiqué dans 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 du côté HTML. En outre, n'oubliez pas que seuls les types de données QML/C++ qui peuvent être convertis en JSON seront (dé)sérialisés correctement 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 un site QObject qui a des méthodes surchargées, QWebChannel résoudra les invocations de méthodes en fonction de la meilleure correspondance. Notez qu'en raison du système de types de JavaScript, il n'existe qu'un seul type "nombre" qui correspond le mieux au type "double" de C++. Lorsque les surcharges ne diffèrent que par le type d'un paramètre de type nombre, QWebChannel choisira toujours la surcharge qui correspond le mieux au type "nombre" de JavaScript. Lorsque vous vous connectez à un signal surchargé, le client QWebChannel ne se connectera par défaut qu'au premier signal surchargé de ce nom. En outre, les surcharges de méthodes et de signaux peuvent être explicitement demandées par leur signature QMetaMethod complète. Supposons que nous ayons la sous-classe QObject suivante du 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 du 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)