En esta página

Qt para WebAssembly

Qt para WebAssembly te permite ejecutar aplicaciones Qt en la web.

WebAssembly (abreviado Wasm) es un formato de instrucciones binarias diseñado para ejecutarse en una máquina virtual, por ejemplo, en un navegador web.

Con Qt para WebAssembly, puedes distribuir tu aplicación como una aplicación web que se ejecuta en un entorno aislado del navegador. Este enfoque es adecuado para aplicaciones web distribuidas que no requieren acceso completo a las capacidades del dispositivo anfitrión.

Nota: Qt for WebAssembly es una plataforma compatible, pero algunos módulos aún no son compatibles o se encuentran en fase de Tech Preview. Consulte Módulos de Qt compatibles.

Primeros pasos con Qt for WebAssembly

Compilar aplicaciones Qt para WebAssembly es similar a compilar Qt para otras plataformas. Debes instalar un SDK (Emscripten), instalar Qt (o compilar Qt desde el código fuente) y, por último, compilar la aplicación. Existen algunas diferencias; por ejemplo, Qt para WebAssembly admite menos módulos y menos funciones que otras compilaciones de Qt.

Instalación de Emscripten

Emscripten es un conjunto de herramientas para compilar en WebAssembly. Permite ejecutar Qt en la web a una velocidad casi nativa sin necesidad de complementos del navegador.

Cada versión menor de Qt está orientada a una versión específica de Emscripten, que permanece inalterada en las versiones de parches. Los paquetes binarios de Qt se compilan utilizando la versión de Emscripten de destino. Las aplicaciones deben utilizar la misma versión, ya que Emscripten no garantiza la compatibilidad ABI entre versiones.

La versión de Emscripten compatible con la 6.12.0 es la 5.0.5.

Consulta la documentación de Emscripten para obtener más información sobre cómo instalar el SDK de Emscripten.

Utiliza emsdk para instalar versiones específicas de Emscripten. Por ejemplo, para instalarla para la versión 6.12.0, escribe:

  • ./emsdk install 5.0.5
  • ./emsdk activate 5.0.5

Tras la instalación, deberías tener el compilador Emscripten en tu ruta. Compruébalo con el siguiente comando:

em++ --version

En Windows, Emscripten ya está en la ruta de acceso tras la instalación. En macOS o Linux, debes añadirlo a la ruta de acceso de la siguiente manera:

source /path/to/emsdk/emsdk_env.sh

Compruébalo con el siguiente comando:

em++ --version

Puedes compilar Qt desde el código fuente si necesitas más flexibilidad a la hora de seleccionar la versión de Emscripten. En este caso, las versiones mencionadas anteriormente son las mínimas requeridas. Se espera que las versiones posteriores funcionen, pero pueden introducir cambios de comportamiento que requieran modificaciones en Qt.

Instalación de Qt

Descarga Qt desde la sección «Descargas» de tu cuenta de Qt. Ofrecemos versiones para Linux, macOS y Windows como plataformas de desarrollo.

Las compilaciones binarias están diseñadas para ejecutarse en el mayor número posible de navegadores y están disponibles en versiones de un solo subproceso y de varios subprocesos. Las compilaciones binarias no admiten características no estándar como Wasm SIMD y Wasm exceptions.

Compilación de Qt a partir del código fuente

La compilación a partir del código fuente te permite establecer opciones de configuración de Qt, como la compatibilidad con subprocesos, el nivel de OpenGL ES o la compatibilidad con SIMD. Descarga el código fuente de Qt desde la sección «Descargas» de tu cuenta de Qt.

Configura Qt como una compilación cruzada para la plataforma wasm-emscripten. Esto establece las opciones de configuración -static, -no-feature-thread y -no-make examples. Puedes habilitar la compatibilidad con subprocesos mediante la opción de configuración -feature-thread. No se admiten compilaciones de bibliotecas compartidas.

Necesitas una compilación del host de la misma versión de Qt. Además, debes establecer la ruta a la compilación del host en la variable CMake QT_HOST_PATH o mediante el argumento de configuración -qt-host-path.

./configure -qt-host-path /path/to/Qt -platform wasm-emscripten -prefix $PWD/qtbase

Nota: «configure» siempre utiliza el generador y la herramienta de compilación Ninja si hay disponible un ejecutable « ninja ». Ninja es multiplataforma, cuenta con numerosas funciones, ofrece un gran rendimiento y se recomienda en todas las plataformas. El uso de otros generadores podría funcionar, pero no está oficialmente soportado.

En Windows, asegúrate de tener Mingw-w64 en tu PATH y ejecuta «configure» con lo siguiente:

configure -qt-host-path C:\Path\to\Qt -no-warnings-are-errors -platform wasm-emscripten -prefix %CD%\qtbase

A continuación, compila los módulos necesarios:

cmake --build . -t qtbase -t qtdeclarative [-t another_module]

Compilación de aplicaciones desde la línea de comandos

Qt para WebAssembly permite compilar aplicaciones utilizando CMake con ninja o make.

$ /path/to/qt-wasm/qtbase/bin/qt-cmake .
$ cmake --build .

Nota: Al utilizar CMake (en lugar de qt-cmake en Linux o qt-cmake.bat en Windows), recuerda especificar un archivo de cadena de herramientas con «-DCMAKE_TOOLCHAIN_FILE», al igual que en cualquier otra compilación multiplataforma. Para más detalles, consulta aquí: Introducción a CMake.

La compilación de la aplicación genera varios archivos de salida, entre ellos un archivo .wasm que contiene el código de la aplicación y de Qt (enlazado estáticamente), y un archivo .html que se puede abrir en el navegador para ejecutar la aplicación.

Nota: Emscripten genera archivos .wasm relativamente grandes en el nivel de depuración «-g». Considera la posibilidad de compilar con «-g2» para las compilaciones de depuración.

Ejecución de aplicaciones

Para ejecutar la aplicación se necesita un servidor web. Los archivos resultantes de la compilación son todos de contenido estático, por lo que cualquier servidor web servirá. Algunos casos de uso pueden requerir una configuración especial del servidor, como proporcionar certificados HTTPS o configurar los encabezados HTTP necesarios para habilitar la compatibilidad con el multihilo.

Emrun

Emscripten proporciona la utilidad emrun para ejecutar aplicaciones a modo de prueba. Emrun inicia un servidor web, abre un navegador y, además, captura y reenvía la salida estándar (stdout) y los errores estándar (stderr) (que normalmente se dirigen a la consola de JavaScript).

/path/to/emscripten/emrun --browser=firefox appname.html

http.server de Python

Otra opción es iniciar un servidor web de desarrollo y, a continuación, abrir el navegador por separado. Una de las opciones más sencillas es http.server de Python:

python -m http.server

Ten en cuenta que se trata únicamente de un servidor web sencillo y que no admite SharedArrayBuffer, necesario para el multihilo, ya que no se envían los encabezados COOP (Cross-Origin-Opener-Policy) y COEP (Cross-Origin-Embedder-Policy) requeridos que se mencionan a continuación.

qtwasmserver

Qt proporciona un servidor web para desarrolladores que utiliza mkcert para generar certificados HTTPS. Esto permite probar funciones web que requieren un contexto seguro. Ten en cuenta que la entrega a través de http://localhost también se considera segura, sin necesidad de un certificado.

El servidor web también establece los encabezados COOP y COEP en valores que habilitan la compatibilidad con SharedArrayBuffer y el multihilo.

El script `qtwasmserver` inicia un servidor que, por defecto, se vincula a `localhost`. Se pueden añadir direcciones adicionales utilizando el argumento de línea de comandos `-a`, o bien utilizar ` --all ` para vincularse a todas las direcciones disponibles.

El script «qtwasmserver» se encuentra en los archivos fuente en

qtbase/util/wasm/qtwasmserver/qtwasmserver.py

o se puede instalar mediante pip:

pip install qtwasmserver

Para obtener más información sobre qtwasmserver, consulta qtwasmserver

Uso de qtwasmserver:

python /path/to/qtbase/util/wasm/qtwasmserver/qtwasmserver.py --all

Compilación de aplicaciones con Qt Creator

Qt Creator: Compilar aplicaciones para la web.

Implementación de aplicaciones en la web

Al crear una aplicación se generan varios archivos (sustituye «app» por el nombre de la aplicación en la siguiente tabla).

Archivo generadoBreve descripción
app.htmlContenedor HTML
qtloader.jsAPI de JavaScript para cargar aplicaciones Qt
app.jsEntorno de ejecución de JavaScript generado por Emscripten
app.wasmBinario de la aplicación

Puedes implementar app.html tal cual o descartarlo y utilizar un archivo HTML personalizado. También es posible realizar pequeños ajustes, como cambiar la imagen de la pantalla de inicio del logotipo de Qt por el logotipo de la aplicación. En ambos casos, qtloader.js proporciona una API de JavaScript para cargar la aplicación.

Comprime el archivo WASM utilizando gzip o brotli antes de la implementación, ya que ofrecen una mejor relación de compresión que otras herramientas. Consulta «Minimizar el tamaño de los binarios» para obtener más información.

Al habilitar determinadas funciones, como el multihilo y SIMD, se generan binarios .wasm que son incompatibles con los navegadores que no admiten la función habilitada. Es posible sortear esta limitación compilando varios archivos .wasm y utilizando luego la detección de características de JavaScript para seleccionar el adecuado, pero ten en cuenta que Qt no proporciona ninguna funcionalidad para hacerlo.

Uso de qtloader

Qt proporciona una API de JavaScript para descargar, compilar y crear instancias de aplicaciones Qt para WebAssembly. Esta API de carga envuelve la funcionalidad de carga proporcionada por Emscripten y ofrece características adicionales útiles para las aplicaciones basadas en Qt. Está implementada en el archivo qtloader.js. Durante la compilación, se guarda una copia de este archivo en el directorio de compilación.

Un uso típico sería el siguiente:

const app_container_element = ...;
const instance = await qtLoad({
    qt: {
        containerElements: [ app_container_element ],
        onLoaded: () => { /* handle application load completed */  },
        onExit: () => {  /* handle application exit */ },
    }
});

El código llama a la función de carga qtLoad() con un objeto de configuración. Este objeto de configuración puede contener cualquier opción de configuración de emscripten, así como un objeto de configuración especial «qt». El objeto de configuración «qt» admite las siguientes propiedades:

PropiedadBreve descripción
containerElementsMatriz de elementos contenedores HTML. La aplicación los interpreta como QScreens.
onLoadedFunción de llamada de retorno que se ejecuta cuando la aplicación ha terminado de cargarse.
onExitFunción de llamada de retorno que se ejecuta cuando la aplicación se cierra.

La matriz containerElements es la interfaz principal entre Qt y la página web, donde los elementos HTML de esta matriz (normalmente elementos <DIV>) especifican la ubicación del contenido de la aplicación en la página web.

La aplicación considera cada elemento contenedor como una instancia de ` QScreen ` y puede colocar ventanas de la aplicación sobre las instancias de pantalla como de costumbre. Las ventanas con el estado « Qt::WindowFullScreen » activado ocupan todo el área de la pantalla, mientras que las ventanas que no están en «pantalla completa» muestran los elementos decorativos de la ventana.

La función qtLoad() devuelve una promesa, que proporciona una instancia de Emscripten cuando se espera su resolución. La instancia permite acceder a las funciones exportadas por Embind. Qt exporta varias de estas funciones, y estas funciones conforman la API de la instancia.

Uso de la API de la instancia de Qt

Qt proporciona varias funciones de instancia. Actualmente, estas permiten añadir y eliminar elementos del contenedor en tiempo de ejecución.

PropiedadBreve descripción
qtAddContainerElementAñade un elemento del contenedor. Al añadir un elemento, se añadirá un nuevo objeto ` QScreen`.
qtRemoveContainerElementElimina un elemento contenedor y su pantalla correspondiente.
qtSetContainerElementsEstablece todos los elementos contenedores
qtResizeContainerElementHace que Qt detecte los cambios en el tamaño del elemento contenedor.

Portabilidad al qtloader de Qt 6.6

Qt 6.6 incluye un nuevo qtloader con una implementación simplificada y un alcance más reducido. Esto conlleva cambios en la API que pueden requerir la adaptación del código JavaScript de la aplicación. Qt proporciona una API de compatibilidad para facilitar la transición. Dependiendo del caso de uso, hay varias formas de proceder:

  • Si estás utilizando directamente el archivo ` app.html ` generado, este también se actualizará en el momento de la compilación. No es necesario realizar ninguna acción.
  • Si utilizas el conjunto básico de funciones de qtloader, puedes utilizar la API de compatibilidad incluida en Qt 6.6 como medida temporal. Esta API se eliminará en una versión futura; debes planificar la actualización para utilizar el nuevo qtloader. Es necesario realizar el paso 1 de la adaptación que se indica a continuación.
  • Si utiliza funciones avanzadas (como añadir elementos contenedores en tiempo de ejecución), será necesario realizar la migración al nuevo cargador o a la nueva API de instancias. Se deben seguir los pasos de migración 1 y 2 que se indican a continuación.

Pasos de migración

  1. Incluye el « app.js » (entorno de ejecución de JavaScript generado por Emscripten) en el archivo HTML de carga.
    <script src="app.js"></script>

    Antes de Qt 6.6, qtloader cargaba y evaluaba este archivo JavaScript. Esto ya no se hace, por lo que el archivo debe incluirse mediante una etiqueta <script>.

  2. Adapta el código para utilizar la nueva API de JavaScript y de instancias.

Consulte las secciones de la documentación anteriores.

Navegadores compatibles

Ordenadores de sobremesa

Qt for WebAssembly se ha desarrollado y probado en los siguientes navegadores:

  • Chrome
  • Firefox
  • Safari
  • Edge

Qt debería funcionar si el navegador es compatible con WebAssembly. Los navegadores que admiten WebAssembly suelen ser compatibles con WebGL, aunque algunos incluyen en una lista negra las GPU más antiguas o no compatibles.El archivo s/qtloader.js proporciona API para comprobar si WebGL está disponible.

Qt no utiliza directamente las funciones del sistema operativo, por lo que no supone ninguna diferencia si, por ejemplo, Firefox se ejecuta en Windows o en macOS. Qt sí utiliza algunas adaptaciones del sistema operativo, por ejemplo, para el manejo de las teclas Ctrl/Cmd en macOS.

Dispositivos móviles

Las aplicaciones de Qt para WebAssembly se ejecutan en navegadores móviles como Safari para móviles y Chrome para Android.

Módulos Qt compatibles

Qt para WebAssembly es compatible con un subconjunto de los módulos y funciones de Qt. A continuación se enumeran los módulos probados; es posible que otros módulos funcionen o no.

Los siguientes módulos se encuentran en fase de «Technology Preview». Es posible que tengan una funcionalidad limitada o que sufran cambios significativos en futuras versiones.

En todos los casos, es posible que la compatibilidad con los módulos no sea completa y que existan limitaciones adicionales, ya sea debido al entorno aislado del navegador o a que la adaptación de la plataforma Qt aún no esté terminada. Consulta «Desarrollo con Qt para WebAssembly» para obtener más información.

Desarrollo con Qt para WebAssembly

Compilación con CMake

Si es necesario realizar una configuración específica para Emscripten en CMake, se puede utilizar el siguiente código:

if(EMSCRIPTEN)
    # WebAssembly specific code
else()
    # other platforms
endif()

Este código permite incorporar configuraciones específicas de Emscripten al tiempo que garantiza la compatibilidad con otras plataformas.

OpenGL y WebGL

Qt para WebAssembly admite el renderizado con aceleración por hardware mediante https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API WebGL.

WebGL se ajusta estrechamente a OpenGL ES, con la siguiente correspondencia de versiones:

OpenGLWebGL
OpenGL ES 2.0WebGL 1
OpenGL ES 3.0WebGL 2

Qt utiliza la versión más alta disponible de WebGL. Normalmente, en los navegadores actuales es WebGL 2, pero podría ser WebGL 1 si el hardware lo limita. Recomendamos orientar la aplicación a dispositivos que admitan WebGL 2 con Qt para WebAssembly.

Las diferencias entre OpenGL para web y para escritorio se describen en «Diferencias entre WebGL y OpenGL». Existen diferencias adicionales entre WebGL 1.0 y WebGL 2.0, que se recogen en la especificación de WebGL 2.0.

De forma predeterminada, se utiliza un subconjunto de ES2 (y ES3) compatible con WebGL. Si necesitas utilizar glDrawArrays y glDrawElements sin búferes vinculados, puedes habilitar la compatibilidad completa con ES2 añadiendo

target_link_options(<your target> PRIVATE -s FULL_ES2=1)

y/o la emulación completa de ES3 añadiendo

target_link_options(<your target> PRIVATE -s FULL_ES3=1)

en el archivo ` CMakeLists.txt` de tu proyecto.

Para obtener más información sobre la compatibilidad de Emscripten con OpenGL, visita https://emscripten.org/docs/porting/multimedia_and_graphics/OpenGL-support.html

Limitaciones del contexto OpenGL

WebGL no admite múltiples contextos por superficie. Esto tiene implicaciones para las aplicaciones que utilizan ` QOpenGLContext `, ya sea directamente o de forma indirecta a través de otras clases, como ` QOpenGLWidget`.

Cada instancia de ` QOpenGLContext ` debe utilizarse únicamente con una única superficie. En la práctica, el contexto se asocia a la superficie en la primera llamada a `makeCurrent()`. No se admite llamar a `makeCurrent()` posteriormente en una superficie diferente, ni desde un ` QOpenGLContext ` distinto con la misma superficie.

No se admite el uso compartido de contextos OpenGL. La llamada a ` QOpenGLContext::setShareContext()` no tiene ningún efecto, y ` QOpenGLContext::shareContext()` siempre devuelve `nullptr`.

La destrucción de una superficie (por ejemplo, un ` QWindow`) provoca la pérdida del contexto asociado. La aplicación debe gestionar esta situación recreando el contexto.

QOpenGLWidget y otras clases que utilizan el uso compartido de contexto internamente no son compatibles.

Multihilo

Qt para WebAssembly admite el multihilo mediante la compatibilidad con Pthreads de Emscripten, en la que cada hilo está respaldado por un web worker. Para habilitar el multihilo, instala el componente «WebAssembly (multihilo)» desde Qt Maintenance Tool, o compila Qt desde el código fuente y pasa el indicador «-feature-thread» a configure.

Por lo general, el código de subprocesos existente se puede reutilizar, aunque puede ser necesario modificarlo para adaptarlo a las particularidades de la implementación de pthread. Algunas características de Emscripten y Qt no son compatibles, entre ellas la función de proxy de subprocesos y el bucle de renderizado multihilo de Qt Quick.

Ten en cuenta que es especialmente importante no bloquear el hilo principal en Qt para WebAssembly, ya que es posible que el hilo principal tenga que atender solicitudes de hilos secundarios. Por ejemplo, todos los temporizadores de Qt se programan en el hilo principal y no se activarán si este se bloquea. Otro ejemplo es que la creación de un nuevo «web worker» (para un hilo) solo puede realizarse desde el hilo principal.

Emscripten ofrece algunas soluciones para esto. Las esperas de corta duración, como la adquisición de un bloqueo mutex, se gestionan mediante espera activa y el procesamiento de eventos mientras se espera el bloqueo. Deben evitarse las esperas más prolongadas en el hilo principal. En concreto, la práctica habitual de llamar a ` QThread::wait()` o `pthread_join()` para esperar a un hilo secundario no funcionará, a menos que la aplicación pueda garantizar que el hilo (y el web worker) ya se haya iniciado y pueda completarse sin ayuda del hilo principal en el momento en que se realice la llamada a `wait()` o `join()`.

La función de multihilo requiere que el navegador sea compatible con la API SharedArrayBuffer. (Normalmente, Emscripten almacena el montón en un objeto ArrayBuffer. Para el multihilo, el montón debe compartirse con los web workers y se necesita un SharedArrayBuffer). Esta API suele estar disponible en todos los navegadores modernos, pero puede estar desactivada si no se cumplen ciertos requisitos de seguridad. En ese caso, los binarios de WebAssembly con soporte para subprocesos habilitado no se ejecutarán, incluso si el binario no inicia realmente un subproceso.

Para habilitar SharedArrayBuffer se requiere un contexto de navegación seguro (en el que la página se sirva a través de https:// o http://localhost) y que la página se encuentre en modo de aislamiento entre orígenes. Esto último se puede conseguir configurando los denominados encabezados COOP y COEP en el servidor web:

  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Embedder-Policy: require-corp

SIMD

Emscripten es compatible con WebAssembly SIMD, que proporciona tipos y operaciones SIMD de 128 bits para WebAssembly.

Compila Qt desde el código fuente y configúralo con el indicador -feature-wasm-simd128 para habilitarlo; esto pasará el indicador -msimd128 en el momento de la compilación y la vinculación. Ten en cuenta que, por el momento, Qt no contiene rutas de código optimizadas para wasm-simd; sin embargo, al habilitar wasm-simd se activará la vectorización automática del compilador, lo que permitirá que este utilice las instrucciones SIMD.

Puede dirigirse directamente a SIMD de WebAssembly utilizando las extensiones vectoriales SIMD de GCC/Clang o las funciones intrínsecas SIMD128 de WASM. Para obtener más información, consulte la documentación sobre SIMD de Emscripten .

Además, Emscripten admite la emulación o traducción de instrucciones SSE de x86 a instrucciones SIMD de WASM. Qt no utiliza esta emulación, ya que el uso de instrucciones SIMD SSE que no tienen un equivalente nativo en SIMD de WASM puede provocar una reducción del rendimiento.

Ten en cuenta que los binarios con SIMD habilitado son incompatibles con los navegadores que no admiten SIMD de WebAssembly, incluso si las rutas de código SIMD no se invocan en tiempo de ejecución. Es posible que sea necesario habilitar la compatibilidad con SIMD en las configuraciones avanzadas del navegador, como «about:config» o «chrome:flags».

Redes

Qt ofrece una compatibilidad limitada con las redes. En general, los protocolos de red que ya se utilizan en la web también pueden emplearse desde Qt, mientras que otros no están disponibles directamente debido al entorno aislado (sandbox) de la web.

Se admiten los siguientes protocolos:

  • QNetworkAccessManager Solicitudes HTTP al servidor de origen de la página web o a un servidor que admita CORS. Esto incluye XMLHttpRequest desde QML.
  • QWebSocket Conexiones a cualquier host. Ten en cuenta que las páginas web servidas a través del protocolo seguro HTTPS solo permiten conexiones WebSockets mediante el protocolo seguro WSS.
  • Sockets TCP POSIX emulados a través de WebSockets, utilizando la funcionalidad proporcionada por Emscripten. Ten en cuenta que esto requiere ejecutar un servidor de reenvío que se encargue de la conversión de sockets.

No se admiten el resto de protocolos de red.

Nota: No se admite« QWebSocketServer » debido a las limitaciones de los navegadores. Los navegadores restringen la funcionalidad de los sockets del lado del servidor para garantizar la seguridad dentro del entorno aislado de la web. Por consiguiente, cualquier funcionalidad que dependa de QWebSocketServer para aceptar conexiones de red entrantes no puede utilizarse dentro del entorno web.

Nota: Qt MQTT los módulos ` QtRemoteObjects ` se pueden utilizar con ` QtWebSockets ` como transportes. No son compatibles oficialmente y pueden funcionar o no, o presentar funciones que falten. Consulte QMqttClient::connectToHostWebSocket y el ejemplo de aplicaciones WebSockets de QtRemoteObjects.

Compartición de recursos entre orígenes (CORS) y política (CORP)

Las aplicaciones WebAssembly que utilizan redes pueden requerir que el servidor establezca los encabezados de respuesta «Cross-Origin Resource Sharing» (CORS) y «Cross-Origin Resource Policy» (CORP). Estos restringen las solicitudes HTTP que se originan en dominios diferentes, lo que supone un riesgo de seguridad.

Utilizando QHttpServer, a continuación se muestra un ejemplo de cómo configurar estos encabezados:

auto headers = response.headers();
headers.append("Access-Control-Allow-Origin", "*");
headers.append("Access-Control-Allow-Origin", "localhost");
headers.append("Access-Control-Allow-Methods", "POST, GET, OPTIONS");

headers.append("Cross-Origin-Opener-Policy", "same-origin");
headers.append("Cross-Origin-Embedder-Policy", "require-corp");
headers.append("Cross-Origin-Resource-Policy", "cross-origin");

Otros servidores conocidos tienen su propia forma de configurar el envío de estos encabezados.

El uso del comodín «*» en Access-Control-Allow-Origin provocará un error si se utiliza junto con Access-Control-Allow-Credentials.

El script de utilidad incluido, qtwasmserver.py, configurará estos encabezados si se utiliza la opción « --cross-origin-isolation ».

Acceso a archivos locales

El acceso al sistema de archivos está aislado en un entorno de sandbox en la web, lo que tiene implicaciones en el funcionamiento de la aplicación con los archivos. La plataforma web proporciona API para acceder al sistema de archivos local de forma controlada por el usuario, así como API para acceder al almacenamiento persistente. Emscripten y Qt envuelven estas características y proporcionan API que resultan más fáciles de utilizar desde aplicaciones en C++ y basadas en Qt.

La plataforma web ofrece funciones para acceder a archivos locales y al almacenamiento persistente:

  • <input type="file"> para mostrar un cuadro de diálogo nativo de apertura de archivos en el que el usuario puede seleccionar un archivo.
  • IndexedDB proporciona almacenamiento local persistente (al que no se puede acceder fuera del navegador).

Emscripten ofrece varios sistemas de archivos con una API similar a POSIX. Entre ellos se incluyen:

  • el sistema de archivos efímero MEMFS, que almacena los archivos en memoria
  • el sistema de archivos persistente IDBFS, que almacena archivos mediante IndexedDB

Emscripten monta un sistema de archivos MEMFS temporal en «/» al iniciarse la aplicación. Esto significa que se puede utilizar QFile, y que, por defecto, leerá y escribirá archivos en memoria. No se conserva al recargar el navegador.

Dado que las páginas web no tienen acceso directo al sistema de archivos local, Qt proporciona una API de « QFileDialog » para su uso con Qt for WebAssembly.

Acceso al portapapeles

Qt admite copiar y pegar texto, URL, tipos de archivo conocidos e imágenes mediante el portapapeles del sistema, con algunas diferencias debidas al entorno aislado web. No admite datos binarios arbitrarios del tipo «application/octet-stream». En general, el acceso al portapapeles requiere el permiso del usuario, que puede obtenerse gestionando un evento de entrada (por ejemplo, CTRL+c) o utilizando la API del portapapeles.

Fuentes

El módulo Qt WASM contiene tres fuentes integradas: «Bitstream Vera Sans» (fuente de reserva), «DejaVu Sans» y «DejaVu Sans Mono».

Estas fuentes ofrecen un conjunto de caracteres limitado. Qt ofrece varias opciones para añadir fuentes adicionales:

Una de ellas es utilizar ` FontLoader ` en QML, que puede obtener una fuente mediante una URL o utilizando el sistema de recursos de Qt (del mismo modo que funcionan las aplicaciones de escritorio habituales).

La otra forma de utilizar una fuente es añadirla a través de QFontDatabase::addApplicationFontFromData.

Accesibilidad y lectores de pantalla

Qt para WebAssembly ofrece compatibilidad básica con los lectores de pantalla. Los elementos sencillos de la interfaz de usuario, como los botones y las casillas de selección, funcionan correctamente, mientras que los elementos más complejos, como las tablas o las vistas en árbol, pueden no ser compatibles. Se admiten tanto Qt Widgets como Qt Quick.

Se han probado las siguientes configuraciones de lectores de pantalla y navegadores, y se sabe que funcionan correctamente. Es posible que otros navegadores y lectores de pantalla también funcionen.

  • VoiceOver con Safari en macOS
  • VoiceOver con Chrome en macOS

La implementación de accesibilidad funciona mediante la creación de elementos HTML «shadow» que proporcionan la información de accesibilidad para los elementos de la interfaz de usuario de Qt. Esta funcionalidad está desactivada por defecto. El usuario final puede activarla seleccionando el botón «activar lector de pantalla» mediante el lector de pantalla. Una vez activada, la página web se completará con elementos de accesibilidad.

Arrastrar y soltar

  • Se admite la función de soltar (archivos y tipos MIME compatibles con el navegador).
  • Se admite la función de arrastrar y soltar dentro de la aplicación.
  • No se admite arrastrar fuera de la aplicación.

Inicio de la aplicación y el bucle de eventos

Qt para WebAssembly admite el método estándar de inicio de Qt, en el que la aplicación crea un objeto ` QApplication ` y llama a la función `exec`:

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QWindow appWindow;

    return app.exec();
}

La llamada a exec() anterior normalmente se bloquea y procesa eventos hasta que se cierra la aplicación. Lamentablemente, esto no es posible en la plataforma web, donde no está permitido bloquear el hilo principal. En su lugar, el control debe devolverse al bucle de eventos del navegador tras procesar cada evento.

Qt soluciona esto haciendo que `exec()` devuelva el control del hilo principal al navegador, al tiempo que conserva la pila. Desde el punto de vista del código de la aplicación, se entra en la función `exec()` y el procesamiento de eventos se produce como de costumbre. Sin embargo, la llamada a `exec()` nunca devuelve un valor, ni siquiera al salir de la aplicación.

Este comportamiento suele ser aceptable, ya que el navegador liberará la memoria de la aplicación en el momento del cierre de la misma. Esto sí implica que el código de cierre no se ejecuta, ya que el objeto de la aplicación queda retenido y su destructor no se ejecuta.

Puedes evitarlo reescribiendo `main()` para que sea asíncrona, lo cual es posible ya que Emscripten no sale del entorno de ejecución cuando `main()` devuelve un valor. De este modo, el código de la aplicación omite la llamada a `exec()` y puede cerrar Qt de forma limpia eliminando la ventana de nivel superior y los objetos de la aplicación.

QApplication *g_app = nullptr;
AppWindow *g_appWindow = nullptr;

int main(int argc, char **argv)
{
    g_app = new QApplication(argc, argv);
    g_appWindow = new AppWindow();
    return 0;
}

Nota: Esto se aplica cuando no se utiliza Asyncify ni JSPI. La llamada a exec() en main() es obligatoria cuando se utiliza Asyncify o JSPI.

Asyncify y JSPI

La compilación predeterminada de Qt para WebAssembly no admite la reentrada en el bucle de eventos, por ejemplo, llamando a QEventLoop::exec() o QDialog::exec(), debido a las restricciones de la plataforma web que impiden que el código C++ síncrono invoque API de JavaScript asíncronas.

Entre las funciones que requieren asyncify/JSPI se incluyen:

  • QDialogs, QMessageBoxes con valores de retorno.
  • Arrastrar y soltar (concretamente, arrastrar).
  • Bucles de eventos anidados o secundarios con exec().

Emscripten ofrece soporte para sortear estas limitaciones mediante la función Asyncify. Esta función está disponible en dos versiones:

  • Asyncify, implementada mediante un paso de posprocesamiento del código WebAssembly.
  • JSPI, implementada mediante la función de integración de JS Promise de WebAssembly.

Consulta las secciones siguientes para obtener más detalles sobre cómo habilitar cada opción y las ventajas e inconvenientes que conlleva. En resumen, Asyncify ya está disponible, pero supone una sobrecarga que se traduce en tiempos de compilación más largos, tamaños de binarios mayores y un menor rendimiento en tiempo de ejecución. JSPI tiene una sobrecarga mínima o nula, pero aún no es compatible con todos los navegadores.

Nota: Llamar a la función `exec()` de la aplicación en `main()` era opcional en versiones anteriores de Qt para WebAssembly, pero ahora es obligatorio cuando se utiliza Asyncify o JSPI.

Asyncify

Activa Asyncify añadiendo los indicadores «-sASYNCIFY -Os» a las opciones del enlazador:

CMake:

target_link_options(<your target> PUBLIC -sASYNCIFY -Os)

qmake:

QMAKE_LFLAGS += -sASYNCIFY -Os

Habilitar «asyncify» supone una sobrecarga que se traduce en un aumento del tamaño de los binarios y del uso de la CPU. Compila con las optimizaciones activadas para minimizar dicha sobrecarga.

JSPI (Integración de JS Promise)

A diferencia de Asyncify, el uso de JSPI requiere compilar Qt desde el código fuente. Para habilitarlo, pasa los parámetros -feature-wasm-jspi y -feature-wasm-exceptions al script de configuración de Qt. (JSPI no es compatible con las excepciones emuladas predeterminadas de Emscripten.)

A continuación, habilita JSPI para tu aplicación añadiendo el indicador -sJSPI a las opciones del enlazador:

CMake:

target_link_options(<your target> PUBLIC -sJSPI)

qmake:

QMAKE_LFLAGS += -sJSPI

Depuración y análisis de rendimiento

La depuración de Wasm se realiza en la consola de JavaScript del navegador. No es posible depurar aplicaciones en Wasm directamente en Qt Creator.

Puedes aumentar el nivel de detalle para facilitar la depuración utilizando los argumentos del enlazador de Emscripten:

  • -s LIBRARY_DEBUG=1 (muestra las llamadas a la biblioteca)
  • -s SYSCALL_DEBUG=1 (muestra las llamadas al sistema)
  • -s FS_LOG=1 (muestra las operaciones del sistema de archivos)
  • -s SOCKET_DEBUG (muestra información sobre sockets y la transferencia de datos de red)

CMake:

target_link_options(<your target> PRIVATE -s LIBRARY_DEBUG=1)

qmake:

QMAKE_LFLAGS_DEBUG += -s LIBRARY_DEBUG=1

Optimización

La optimización de Qt para WebAssembly utiliza la cadena de herramientas de Emscripten para generar binarios, y hay muchos parámetros que pueden afectar al rendimiento y al tamaño de los binarios. Consulta Emscripten: Optimización de código para obtener más información.

Puedes pasar opciones al enlazador y al compilador igual que en las aplicaciones normales de C++:

target_compile_options(<your target> PRIVATE -oz -flto)
target_link_options(<your target> PRIVATE -flto)
QMAKE_CXXFLAGS += -oz -flto
QMAKE_LFLAGS += -flto

Reducir al mínimo el tamaño de los archivos binarios

Para ofrecer una experiencia de usuario fluida, es importante reducir el tiempo de descarga y carga de las aplicaciones WebAssembly. Un binario de aplicación más pequeño es uno de los aspectos clave que permiten una descarga más rápida. Utiliza las siguientes alternativas para reducir el tamaño del binario:

  • Asegúrate de distribuir versiones de lanzamiento. Las versiones de depuración contienen símbolos de depuración y son mucho más grandes.
  • Activa la compresión en el servidor. Los algoritmos más comunes, como gzip y Brotli, funcionan bien con los binarios Wasm y pueden reducir drásticamente su tamaño.
  • Prueba a utilizar opciones del compilador y del enlazador que puedan dar lugar a la generación de binarios más pequeños (por ejemplo, «-os», «-oz»). Los resultados variarán en función de la aplicación concreta.
  • Desactiva las funciones que no se utilicen al compilar Qt para WebAssembly desde el código fuente (véase más abajo).
Desactivación de características

Una aplicación WebAssembly, por defecto, se vincula estáticamente a las bibliotecas de Qt, lo que permite al compilador eliminar el código muerto. Sin embargo, debido a la naturaleza dinámica de Qt, no siempre es posible que el compilador realice dichas optimizaciones.

Si compilas Qt para WebAssembly a partir del código fuente, puedes desactivar algunas funciones para reducir el tamaño de los binarios de Qt y, por consiguiente, el tamaño de los binarios .wasm. Qt desactiva algunas funciones de forma predeterminada para la plataforma WebAssembly, pero también puedes desactivar aquellas que tu aplicación no utilice. Consulta las funciones desactivadas para obtener más información.

Puedes desactivar las siguientes funciones para reducir el tamaño de los binarios (normalmente entre un 10 % y un 15 %):

Argumento de configuraciónBreve descripción
-no-feature-cssparserAnalizador de hojas de estilo en cascada.
-no-feature-datetimeeditEdición de fechas y horas (depende de datetimeparser).
-no-feature-datetimeparserAnálisis de textos de fecha y hora.
-no-feature-dockwidgetAcoplar widgets dentro de un « QMainWindow » o mostrarlos flotantes como ventanas de nivel superior en el escritorio.
-no-feature-gesturesMarco de trabajo para gestos.
-no-feature-mimetypeGestión de tipos MIME.
-no-feature-qml-networkTransparencia de red.
-no-feature-qml-list-modelListModel Tipo QML.
-no-feature-qml-table-modelTableModel Tipo QML.
-no-feature-quick-canvasElemento de lienzo.
-no-feature-quick-pathElementos de ruta.
-no-feature-quick-pathviewPathView elemento.
-no-feature-quick-treeviewTreeView elemento.
-no-feature-style-stylesheetEstilo de widget configurable mediante CSS.
-no-feature-tableviewImplementación predeterminada del modelo/vista de una vista de tabla.
-no-feature-texthtmlparserAnalizador sintáctico para HTML.
-no-feature-textmarkdownreaderLector de Markdown (CommonMark y GitHub).
-no-feature-textodfwriterGenerador de ODF.

Excepciones de Wasm

Qt se compila por defecto sin soporte para excepciones, por lo que lanzar una excepción provocará la interrupción del programa. Las excepciones de WebAssembly se pueden habilitar compilando desde el código fuente y pasando el indicador -feature-wasm-exceptions al programa configure de Qt. Esto hará que se pase el indicador -fwasm-exceptions al compilador en el momento de la compilación y la vinculación. Qt no admite la habilitación del soporte de Emscripten para la implementación anterior de excepciones basada en JavaScript.

Ten en cuenta que, debido a detalles de la implementación interna, no se admite la llamada a ` QApplication::exec()` cuando las excepciones están habilitadas. En su lugar, escribe la función `main()` de forma que retorne anticipadamente y no llame a `exec()`, tal y como se describe en «Inicio de la aplicación y el bucle de eventos».

Bibliotecas compartidas y enlace dinámico (vista previa tecnológica)

Qt para WebAssembly utiliza el enlace estático de forma predeterminada, de modo que la aplicación se implementa como un único archivo WebAssembly que contiene las bibliotecas de Qt y el código de la aplicación. El enlace dinámico es un modo de compilación alternativo en el que cada biblioteca y cada complemento se distribuyen individualmente.

Por ejemplo, una aplicación que utilice Qt Quick puede hacer uso de las siguientes bibliotecas y complementos:

  • <qtpath>/lib/libQt6Core.so
  • <qtpath>/lib/libQt6Gui.so
  • <qtpath>/lib/libQt6Qml.so
  • <qtpath>/lib/libQt6Quick.so
  • <qtpath>/plugins/imageformats/libqjpeg.so
  • <qtpath>/plugins/imageformats/libqjgif.so
  • <qtpath>/qml/QtQuick/Window/libquickwindowplugin.so

La compatibilidad con enlaces dinámicos en la versión 6.12 se encuentra en fase de «Technology Preview». La implementación es adecuada para la creación de prototipos y la evaluación, pero no para su uso en producción. Las limitaciones y restricciones actuales incluyen:

  • No se admite el multihilo.
  • No se admite Asyncify.

Las aplicaciones Qt compiladas con enlace dinámico requieren que haya dos archivos adicionales junto a los binarios: qt_plugins.json y qt_qml_imports.json. Estos archivos especifican una lista de bibliotecas compartidas que se cargarán al iniciar la aplicación. Existe una herramienta de ayuda para generarlos: wasmdeployqt. Para ver cómo se utiliza esta herramienta, puedes ejecutarla con el indicador « --help » y así obtener una visión general de los indicadores necesarios para ejecutarla, así como ejemplos de uso.

El servidor web que aloja la aplicación debe tener disponibles las bibliotecas compartidas de Qt. Esto se puede lograr copiando el contenido de la carpeta de instalación de Qt al servidor web o creando un enlace en el sistema de archivos.

Inicio rápido

El procedimiento de compilación e implementación es ligeramente diferente al de las compilaciones WASM estáticas y las compilaciones compartidas para escritorio. Te recomendamos que empieces con un pequeño ejemplo antes de pasar a la compilación de una aplicación completa.

  1. Compila Qt desde el código fuente, pasando la opción « -shared » al script de configuración de Qt. Utiliza la opción «-prefix» para establecer el directorio de instalación.
  2. Compila tu aplicación utilizando Qt desde el paso 1.
  3. Crea listas de precarga de complementos ejecutando la herramienta de implementación desde el directorio de compilación de tu aplicación.
    • <qtpath>/qtbase/bin/wasmdeployqt --qt-wasm-dir=<Path to the Qt for WebAssembly directory> --qml-root-path=<Root directory for QML files> --qt-host-dir=<Path to the Qt host directory>

Despliegue de bibliotecas compartidas en profundidad

La compilación de las bibliotecas compartidas de Qt se implementa en dos fases: en la primera, la compilación de Qt y de la aplicación queda disponible para su descarga desde el servidor web; y en la segunda, se descargan los complementos de Qt necesarios y las importaciones de Qt Quick al iniciar la aplicación.

En el primer paso, haz que la instalación de Qt esté disponible para su descarga desde el servidor web. Dependiendo de las características específicas de la configuración del servidor web, puede haber diferentes formas de lograrlo. Lo habitual es que el cargador de Qt espere encontrar las bibliotecas y los complementos de Qt en un directorio llamado «qt», relativo al archivo HTML que carga la aplicación.

Si ya estás copiando la aplicación al servidor web como parte de la implementación, una opción viable es copiar también Qt. Si estás sirviendo la aplicación directamente desde su directorio de compilación —lo que suele ocurrir durante las fases de desarrollo—, crear un enlace simbólico a Qt puede ser una buena solución.

Prepárate para el segundo paso creando listas de precarga para los componentes de Qt, como los complementos y las importaciones Qt Quick. La precarga garantiza que todos los componentes de Qt necesarios estén disponibles al iniciar la aplicación. La carga diferida, en la que los componentes se descargan bajo demanda, también es posible, pero no se trata aquí.

La precarga la implementa el cargador de JavaScript de Qt, que descarga archivos desde el servidor web al sistema de archivos en memoria proporcionado por Emscripten. Los archivos que se van a descargar se especifican mediante listas de descarga en formato JSON. Qt proporciona una herramienta para generar listas de precarga; consulta la sección «Inicio rápido» más arriba.

Problemas conocidos

  • Los bucles de eventos anidados solo son compatibles cuando se utiliza la característica experimental Asyncify o JSPI.
  • No se admite la impresión.
  • QDnsLookup Las consultas de DNS y QSsl no funcionan y no están admitidas debido al entorno aislado web. El navegador se encarga de las consultas de DNS y los certificados SSL. Las aplicaciones que necesiten realizar consultas de DNS pueden utilizar DNS sobre HTTP.
  • Se pueden utilizar QTcpSockets, pero no todas las funciones de sockets POSIX se gestionan a través de un proxy. Es necesario utilizar un proxy de servidor WebSockets como Websockify.
  • La plataforma no admite todas las clases de Q*Server.
  • QWebSocket Emscripten solo admite conexiones en el hilo principal.
  • QWebSockets para WebAssembly no admite el envío de tramas «ping» o «pong», ya que la API disponible para páginas web y navegadores no expone esta funcionalidad.
  • Para utilizar QtWebSockets, puede que sea necesario configurar el subprotocolo en «mqtt» para utilizar QtMqtt. Utiliza QWebSocketHandshakeOptions al abrir QWebSocket.
  • Fuentes: el entorno aislado de Wasm no permite el acceso a las fuentes del sistema. Los archivos de fuentes deben distribuirse junto con la aplicación, por ejemplo, en los recursos de Qt o mediante descarga. El propio Qt for WebAssembly incorpora una de estas fuentes.
  • Pueden aparecer artefactos debidos a memoria gráfica no inicializada en algunos componentes de Qt Quick Controls 2, como las casillas de selección. Esto se puede observar en ocasiones en pantallas de alta resolución (HighDPi).
  • No se admiten estilos nativos para Windows y macOS, ya que Wasm, como plataforma, no ofrece esa capacidad.
  • Los errores en el momento de la compilación, como «wasm-ld: error: memoria inicial demasiado pequeña», requieren ajustar el tamaño de la memoria inicial. Utiliza QT_WASM_INITIAL_MEMORY para establecer el tamaño inicial en kb, que debe ser un múltiplo de 64 KB (65536). El valor por defecto es 50 MB. En CMakeLists.txt: set_target_properties(<target> PROPERTIES QT_WASM_INITIAL_MEMORY «150MB»)
  • La instrucción «add_executable» en CMakeLists.txt no genera el archivo <target>.html ni copia qtloader.js. Utiliza «qt_add_executable» en su lugar.

Otros temas

Referencia de opciones de configuración de Qt

Las siguientes opciones de configuración son relevantes a la hora de compilar Qt para WebAssembly a partir del código fuente.

Argumento de «configure»Breve descripción
-feature-threadWasm multihilo.
-feature-wasm-simd128Habilita la compatibilidad con SIMD de WebAssembly.
-feature-wasm-exceptionsHabilita la compatibilidad con excepciones de WebAssembly.
-device-option QT_EMSCRIPTEN_ASYNCIFY=1Habilita la compatibilidad con asyncify.
-device-option QT_EMSCRIPTEN_ASYNCIFY=2Habilita la compatibilidad con asyncify (JSPI).

Qt desactiva de forma predeterminada algunas funciones para la plataforma WebAssembly, con el fin de reducir el tamaño del binario. Puedes habilitar explícitamente una función al configurar Qt para WebAssembly:

Argumento de configuraciónBreve descripción
-feature-topleveldomainProporciona soporte para comprobar si un dominio es un dominio de primer nivel.

Tamaños habituales de descarga

Tamaño previsto (tamaño de la descarga): los módulos Wasm generados por el compilador pueden ser grandes, pero se comprimen bien:

Ejemplogzipbrotli
helloglwindow (QtCore + QtGui)2,8 MB2,1 M
wiggly widget (QtCore + QtGui + QtWidgets)4,3 M3,2 M
SensorTag (QtCore + QtGui + QtWidgets + QtQuick + QtCharts)8,6 M6,3 M

La compresión suele gestionarse en el lado del servidor web, utilizando funciones de compresión estándar: el servidor comprime automáticamente los archivos o utiliza versiones precomprimidas de los mismos. Por lo general, no es necesario aplicar un tratamiento especial a los archivos Wasm.

Para obtener más información, consulta «Minimizar el tamaño de los binarios».

Ejemplos

Ejemplos y demostraciones de aplicaciones Qt que se ejecutan en un navegador web: Demostraciones de Qt

Recursos externos

Licencia

Qt para WebAssembly está disponible bajo licencias comerciales de The Qt Company. Además, está disponible bajo la Licencia Pública General de GNU, versión 3. Consulte Licencias de Qt para obtener más detalles.

Véase también https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS y https://developer.mozilla.org/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy.

© 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.