Qt WebChannel API de JavaScript
Configuración de la API de JavaScript
Para comunicarse con QWebChannel o WebChannel, un cliente debe utilizar y configurar la API de JavaScript proporcionada por qwebchannel.js. Para los clientes que se ejecutan dentro de Qt WebEngine, puedes cargar el archivo a través de qrc:///qtwebchannel/qwebchannel.js si cargas la página localmente, o hacer que qwebchannel.js sea accesible desde un QWebEngineUrlSchemeHandler registrado en QWebEngineUrlScheme como QWebEngineUrlScheme::SecureScheme. Para clientes externos, debes copiar el archivo en tu servidor web. A continuación, crea una instancia de un objeto ` QWebChannel ` y pásale 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 conversión 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 convertido a cadena y lo transmite al objeto ` QWebChannelAbstractTransport ` del lado del servidor. Además, se debe llamar a su propiedad ` onmessage ` cuando se reciba un mensaje del servidor. Como alternativa, puedes utilizar un WebSocket para implementar la interfaz.
Ten en cuenta que el objeto ` QWebChannel ` de JavaScript debe crearse una vez que el objeto de transporte esté plenamente operativo. En el caso de un WebSocket, esto significa que debes crear el objeto ` QWebChannel ` en el controlador ` onopen ` del socket. Echa un vistazo al ejemplo independiente de «Qt WebChannel » para ver cómo se hace esto.
Nota: Solo se puede crear un único objeto ` QWebChannel ` por transporte en la misma página.
Una función envolventa de conversor es bien una cadena con el nombre de un conversor integrado, bien una función proporcionada por el usuario que toma como argumento el objeto a procesar y devuelve el tipo resultante o «undefined» si la función no es aplicable. Si se devuelve «undefined», se procesa el siguiente conversor. Si no hay ningún convertidor que devuelva un valor distinto de «undefined», el procesamiento continúa con normalidad. «Date» es la única función de conversión integrada actualmente. Toma una cadena con una fecha en formato 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 se invoca la función de devolución de llamada pasada al objeto ` QWebChannel `, el canal ha finalizado su inicialización y todos los objetos publicados son accesibles para el cliente HTML a través de la propiedad ` channel.objects `. Así pues, suponiendo que se haya publicado un objeto con el identificador «foo», podemos interactuar con él tal y como se muestra en el ejemplo siguiente. Ten en cuenta 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 solo los tipos de datos de QML/C++ que se puedan convertir a JSON se (des)serializarán correctamente y, por lo tanto, serán accesibles para 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 se publica un objeto « QObject » que tiene métodos sobrecargados, QWebChannel resolverá las invocaciones de métodos con la mejor coincidencia. Ten en cuenta que, debido al sistema de tipos de JavaScript, solo existe un único tipo «number» que se corresponde mejor con un «double» de C++. Cuando las sobrecargas solo difieren en el tipo de un parámetro de tipo numérico, QWebChannel siempre elegirá aquella sobrecarga que mejor se corresponda con el tipo «number» de JavaScript. Al conectarse a una señal sobrecargada, el cliente de QWebChannel se conectará, por defecto, únicamente a la primera sobrecarga de señal con ese nombre. Además, las sobrecargas de métodos y señales pueden solicitarse explícitamente mediante su firma completa de QMetaMethod. Supongamos que tenemos la siguiente subclase de QObject en el lado de 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 desde el lado de 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)© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.