Qt WebChannel API JavaScript

Configuración de la API JavaScript

Para comunicarse con QWebChannel o WebChannel, un cliente debe utilizar y configurar la API JavaScript proporcionada por qwebchannel.js. Para los clientes que se ejecutan dentro de Qt WebEnginepuede cargar el archivo a través de qrc:///qtwebchannel/qwebchannel.js. Para los clientes externos, debe copiar el archivo en su servidor web. A continuación, instancie un objeto QWebChannel y pásele un objeto de transporte y una función de devolución de llamada, que se invocará una vez que finalice la inicialización del canal y los objetos publicados estén disponibles. Un tercer argumento opcional contiene una matriz de funciones envolventes de convertidor o una sola.

El objeto de transporte implementa una interfaz mínima de paso de mensajes. Debe ser un objeto con una función send(), que toma un mensaje JSON encadenado y lo transmite al objeto QWebChannelAbstractTransport del lado del servidor. Además, su propiedad onmessage debe ser llamada cuando se recibe un mensaje del servidor. Alternativamente, puedes utilizar un WebSocket para implementar la interfaz.

Tenga en cuenta que el objeto JavaScript QWebChannel debe construirse una vez que el objeto de transporte esté completamente operativo. En el caso de un WebSocket, eso significa que debes crear el QWebChannel en el manejador onopen del socket. Echa un vistazo al ejemplo deQt WebChannel Standalone para ver cómo se hace esto.

Una función envolvente de convertidor es una cadena con el nombre de un convertidor incorporado o una función suministrada por el usuario que toma el objeto a procesar como argumento y devuelve el tipo resultante o undefined si la función no se aplica. Si se devuelve undefined se procesa el siguiente convertidor. Si no hay convertidores que devuelvan un valor distinto de undefined, el procesamiento continúa normalmente. "Fecha" es la única función de conversión incorporada actualmente. Toma una cadena con una fecha ISO 8601 y devuelve un nuevo objeto Date si la sintaxis es correcta y la fecha es válida.

Interacción con QObjects

Una vez que el callback pasado al objeto QWebChannel es invocado, el canal ha terminado la inicialización y todos los objetos publicados son accesibles al cliente HTML a través de la propiedad channel.objects. Así, asumiendo que un objeto fue publicado con el identificador "foo", entonces podemos interactuar con él como se muestra en el siguiente ejemplo. Nótese que toda la comunicación entre el cliente HTML y el servidor QML/C++ es asíncrona. Las propiedades se almacenan en caché en el lado HTML. Además, ten en cuenta que sólo los tipos de datos QML/C++ que puedan convertirse a JSON serán (de-)serializados correctamente y, por tanto, accesibles a los clientes 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étodos y señales sobrecargados

Cuando publique un QObject que tenga métodos sobrecargados, QWebChannel resolverá las invocaciones de métodos a la mejor coincidencia. Tenga en cuenta que, debido al sistema de tipos de JavaScript, sólo hay un único tipo "number" que se corresponde mejor con "double" de C++. Cuando las sobrecargas sólo difieren en el tipo de un parámetro numérico, QWebChannel siempre elegirá la sobrecarga que mejor se corresponda con el tipo "number" de JavaScript. Al conectarse a una señal sobrecargada, el cliente QWebChannel sólo se conectará por defecto a la primera sobrecarga de señal de ese nombre. Además, las sobrecargas de métodos y señales pueden solicitarse explícitamente mediante su firma completa QMetaMethod. Supongamos que tenemos la siguiente subclase QObject en el lado 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);
};

Entonces puedes interactuar con esta clase en el lado JavaScript de la siguiente manera:

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