SVG en Qt: elige el renderizador y comprueba el archivo

Para SVG en una aplicación Qt Widgets, empieza por QSvgWidget cuando quieras mostrar un dibujo. Utiliza QSvgRenderer cuando necesites pintarlo sobre un destino elegido. La distinción importa: pintar una vez en un QImage de tamaño fijo deja píxeles para mostrar, mientras que conservar el SVG permite renderizarlo de nuevo a otro tamaño. La guía de renderizado de Qt describe ambos métodos.

Elige primero el método y después comprueba el diseño. Una vista previa del navegador puede mostrar el diseño previsto, pero no demuestra que Qt admita todas las funciones utilizadas por el archivo.

Elige un método de visualización antes de editar el SVG

Qt documenta QSvgWidget como widget de visualización SVG y expone su renderizador mediante renderer(). El widget pertenece a SvgWidgets; su dependencia CMake es Qt6::SvgWidgets. La referencia de clase resulta más útil aquí que un ejemplo antiguo que solo añade el módulo general de SVG.

Mostrar un SVG no crea un editor de ilustraciones. Conserva un original independiente si alguien necesitará mover una hoja, modificar una esquina o recolorear un detalle separado.

Prueba un original pequeño antes de la ilustración completa

Guarda este dibujo original como leaf.svg. Utiliza una hoja con relleno, una nervadura clara y un círculo coral separado:

<svg xmlns="http://www.w3.org/2000/svg" width="160" height="100" viewBox="0 0 160 100">
  <path d="M24 78C20 34 56 18 98 26C90 62 58 86 24 78Z" fill="#176b64"/>
  <path d="M28 74L78 38" fill="none" stroke="#fff6e8" stroke-width="5"/>
  <circle cx="126" cy="26" r="10" fill="#ec785e"/>
</svg>

El lienzo ancho es deliberado. Si la hoja se vuelve alta y estrecha, investiga el tratamiento de las proporciones antes de editar sus curvas. Si desaparece el círculo, comprueba los límites visibles y compara el archivo cargado con el original. Este pequeño ejemplo ofrece detalles reconocibles sin depender de recortes ni efectos.

Para entender el propio archivo, la guía del formato SVG explica la diferencia entre formas vectoriales y un contenedor SVG con un mapa de bits.

Un ejemplo mínimo de Qt 6 Widgets

Crea main.cpp:

#include <QApplication>
#include <QSvgRenderer>
#include <QSvgWidget>
 
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    if (argc != 2)
        return 1;
 
    QSvgWidget view;
    view.load(QString::fromLocal8Bit(argv[1]));
    if (!view.renderer()->isValid())
        return 2;
 
    view.renderer()->setAspectRatioMode(Qt::KeepAspectRatio);
    view.resize(400, 240);
    view.show();
    return app.exec();
}

Pasa el nombre del archivo SVG como argumento del programa, preferiblemente una ruta absoluta durante las pruebas. El código de salida 1 significa que este ejemplo no recibió un nombre de archivo; 2 significa que el renderizador no indicó un documento válido. Esos códigos son decisiones de este ejemplo, no la API de códigos de error de Qt.

isValid() comprueba el documento cargado. No es una prueba de aprobación visual. El ajuste explícito KeepAspectRatio pide al renderizador conservar las proporciones; la referencia de QSvgRenderer documenta la comprobación de validez y los modos de relación de aspecto.

Utiliza este CMakeLists.txt junto al código fuente:

cmake_minimum_required(VERSION 3.16)
project(LeafPreview LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
find_package(Qt6 REQUIRED COMPONENTS Widgets Svg SvgWidgets)
add_executable(leaf_preview main.cpp)
target_link_libraries(leaf_preview PRIVATE Qt6::Widgets Qt6::Svg Qt6::SvgWidgets)

El ejemplo enlaza Widgets para la aplicación, SvgWidgets para el widget de visualización y Svg para sus llamadas al renderizador. Qt enumera el componente Svg del renderizador por separado del componente SvgWidgets.

Configúralo y compílalo con tu kit de desarrollo Qt 6 instalado y después ejecuta leaf_preview con la ruta a leaf.svg. Este es un ejemplo de código documentado; no lo hemos compilado ni ejecutado en un entorno Qt nativo. Prueba la compilación y el diseño reales en tu sistema de destino antes de adoptarlo.

Comprueba la compatibilidad actual en lugar de asumir equivalencia con el navegador

Qt SVG moderno no se limita a las funciones estáticas de SVG Tiny. Qt documenta elementos adicionales desde Qt 6.7, interpretados por defecto, con una opción para restringir el análisis a las funciones Tiny. Su referencia de funciones ampliadas enumera las incorporaciones compatibles y sus límites.

Un límite concreto es clipPath: la misma página lo señala como no compatible. Por tanto, un archivo que dependa del recorte merece una inspección del original aunque se vea bien en un navegador. Determinadas máscaras y filtros tienen compatibilidad documentada, pero eso no establece compatibilidad con todos los efectos o ajustes de exportación.

Cuando la hoja sencilla funciona, pero una ilustración mayor difiere, crea una copia y elimina una función sospechosa cada vez. Para diseños recortados, considera producir la geometría visible prevista en un editor en lugar de depender de la operación de recorte. Compara la silueta resultante con el original antes de sustituir el archivo maestro.

El texto necesita su propia comprobación. Si cambian las letras, sigue la guía de problemas de fuentes SVG. Convertir las letras en formas es un compromiso de diseño; no debería ser la primera reparación de un nombre de archivo incorrecto o un módulo ausente.

Detecta cuándo tu proceso convierte el SVG en píxeles

Supón que tu código renderiza la hoja una vez en un QImage pequeño, crea un pixmap desde esa imagen y después amplía el pixmap. La ampliación actúa sobre el resultado rasterizado. El SVG original no ha desaparecido, pero esa operación posterior de visualización ya no le pide un renderizado nuevo.

La guía de renderizado de Qt distingue pintar en una imagen de pintar en el evento de pintura de un widget. Si cambia el tamaño de visualización, decide dónde debe volver a renderizarse el SVG. Evita tratar un mapa de bits almacenado en caché como prueba de que el propio original no puede escalarse.

La misma distinción importa al preparar un conjunto de iconos SVG. Mantén límites originales coherentes y después evalúa cada icono a su tamaño real de uso. Una hoja grande reconocible puede perder su nervadura o su círculo separado cuando se muestra pequeña.

Inspecciona el resultado antes de simplificarlo todo

Empieza por el archivo que realmente cargas, no por otra exportación con un nombre parecido. Confirma que aparece el ejemplo sencillo y después compara el diseño de producción al tamaño previsto y tras redimensionarlo.

Para la hoja, comprueba que el círculo siga separado, la nervadura permanezca visible y el lienzo ancho no estire el dibujo. Son comprobaciones de aceptación para tu propia ejecución, no resultados comunicados de la nuestra. Si toda la vista está vacía, la lista de comprobación de SVG en blanco ayuda a distinguir el diseño invisible y los límites del dibujo de la configuración de la aplicación.

Conserva fotos o ilustraciones con textura como recursos rasterizados cuando convenga al diseño. Elegir SVG debe resolver un requisito gráfico; no establece por sí solo archivos más pequeños, renderizado más rápido ni resultados idénticos entre motores.

Recupera un original cuando solo queda una imagen rasterizada

Si el icono solo se conserva como PNG o JPG, el proceso de imagen a vector de PerfectVector puede ayudar a preparar un diseño SVG editable antes de transferirlo a Qt. Inspecciona la silueta, los huecos y los detalles separados después de convertir y después prueba ese SVG con el método Qt elegido. La vectorización prepara geometría; no añade funciones al renderizador ni convierte un widget de visualización en un editor de trazados.

Si ya tienes un original vectorial limpio, ajusta ese archivo directamente. Simplifica una copia solo cuando una función concreta o un detalle a tamaño pequeño necesiten atención, y conserva el original más rico para futuras ediciones.

Preguntas frecuentes

¿Debo utilizar QSvgWidget o QSvgRenderer? Utiliza QSvgWidget para mostrar un SVG en una interfaz Widgets. Utiliza QSvgRenderer cuando necesites controlar la pintura sobre un destino elegido, como un widget personalizado o una imagen.

¿El Qt actual solo admite SVG Tiny? Qt documenta compatibilidad con SVG Tiny estático y determinadas extensiones introducidas en Qt 6.7. Comprueba la referencia actual de funciones y tus opciones configuradas en lugar de asumir que solo admite Tiny o que equivale al navegador.

¿Por qué puede verse borroso un SVG después de colocarlo en un pixmap? Si primero lo renderizaste en una imagen rasterizada de tamaño fijo, ampliar ese resultado escala píxeles. Revisa el destino de renderizado y si el SVG vuelve a renderizarse al tamaño requerido.

¿Cargar un SVG válido demuestra que cada detalle se renderizó correctamente? No. Una comprobación de validez no sustituye a la inspección visual. Compara los límites, las proporciones, los detalles pequeños y las funciones compatibles en la aplicación real de destino.

Fuentes

1. Qt — Renderizar archivos SVG — widgets de visualización, destinos de pintura y distinción entre renderizado de widget e intermediarios rasterizados.
2. Qt — Clase QSvgWidget — widget de visualización, acceso al renderizador y dependencia SvgWidgets.
3. Qt — Clase QSvgRenderer — dependencia Svg, validez del documento y ajustes de relación de aspecto.
4. Qt — Funciones ampliadas — extensiones modernas y límites explícitos, incluidos trazados de recorte no compatibles.

Empieza con un archivo pequeño e inspecciónalo mediante el método Qt elegido. Si necesitas recuperar un diseño rasterizado, prepara una alternativa SVG editable, comprueba las formas frente al original y repite las comprobaciones de la aplicación antes de sustituir el recurso.