En esta página

QSvgRenderer Class

La clase QSvgRenderer se utiliza para dibujar el contenido de los archivos SVG en dispositivos de dibujo. Más información...

Encabezado: #include <QSvgRenderer>
CMake: find_package(Qt6 REQUIRED COMPONENTS Svg)
target_link_libraries(mytarget PRIVATE Qt6::Svg)
qmake: QT += svg
Heredado de: QObject

Nota: Todas las funciones de esta clase son reentrantes.

Propiedades

Funciones públicas

QSvgRenderer(QObject *parent = nullptr)
QSvgRenderer(QXmlStreamReader *contents, QObject *parent = nullptr)
QSvgRenderer(const QByteArray &contents, QObject *parent = nullptr)
QSvgRenderer(const QString &filename, QObject *parent = nullptr)
virtual ~QSvgRenderer()
bool animated() const
Qt::AspectRatioMode aspectRatioMode() const
QRectF boundsOnElement(const QString &id) const
QSize defaultSize() const
bool elementExists(const QString &id) const
int framesPerSecond() const
bool isAnimationEnabled() const
bool isValid() const
QtSvg::Options options() const
void setAnimationEnabled(bool enable)
void setAspectRatioMode(Qt::AspectRatioMode mode)
void setFramesPerSecond(int num)
void setOptions(QtSvg::Options flags)
void setViewBox(const QRect &viewbox)
void setViewBox(const QRectF &viewbox)
QTransform transformForElement(const QString &id) const
QRect viewBox() const
QRectF viewBoxF() const

Ranuras públicas

bool load(QXmlStreamReader *contents)
bool load(const QByteArray &contents)
bool load(const QString &filename)
void render(QPainter *painter)
void render(QPainter *painter, const QRectF &bounds)
void render(QPainter *painter, const QString &elementId, const QRectF &bounds = QRectF())

Señales

void repaintNeeded()

Miembros públicos estáticos

(since 6.8) void setDefaultOptions(QtSvg::Options flags)

Descripción detallada

Mediante QSvgRenderer, se pueden renderizar gráficos vectoriales escalables (SVG) en cualquier subclase de ` QPaintDevice `, incluyendo ` QWidget`, ` QImage` y `QGLWidget`.

QSvgRenderer proporciona una API que admite funciones básicas de renderizado SVG, como la carga y el renderizado de dibujos estáticos, así como funciones más interactivas, como la animación. Dado que el renderizado se realiza mediante ` QPainter`, los dibujos SVG pueden renderizarse en cualquier subclase de ` QPaintDevice`.

Los dibujos SVG se cargan bien al crear un objeto `QSvgRenderer`, bien posteriormente mediante las funciones ` load()`. Los datos se proporcionan directamente como XML serializado o indirectamente mediante un nombre de archivo. Si se ha cargado un archivo válido, ya sea al crear el renderizador o en un momento posterior, ` isValid()` devuelve «true»; en caso contrario, devuelve «false». QSvgRenderer proporciona la ranura render() para renderizar el documento actual, o el fotograma actual de un documento animado, utilizando un «pintor» determinado.

La función defaultSize() proporciona información sobre la cantidad de espacio necesario para renderizar el archivo SVG cargado actualmente. Esto resulta útil para dispositivos de dibujo, como QWidget, que a menudo necesitan proporcionar una indicación de tamaño a su diseño padre. El tamaño predeterminado de un dibujo puede diferir de su área visible, que se obtiene mediante la propiedad viewBox.

Se admiten dibujos SVG animados, que pueden controlarse mediante un sencillo conjunto de funciones y propiedades:

  • La función animated() indica si un dibujo contiene información de animación.
  • La propiedad framesPerSecond contiene la velocidad a la que se reproduce la animación.

Por último, la clase `QSvgRenderer` proporciona la señal ` repaintNeeded()`, que se emite cada vez que es necesario actualizar la representación del documento.

Véase también QSvgWidget, Qt SVG C++ Classesy QPicture.

Documentación de las propiedades

[since 6.7] animationEnabled : bool

Esta propiedad determina si la animación debe ejecutarse, siempre que el SVG contenga elementos animados

Si se establece la propiedad en «false», se detiene el temporizador de la animación. Si se establece la propiedad en «true», se inicia el temporizador de la animación, siempre que el SVG contenga elementos animados.

Si el SVG no está animado, la propiedad no tendrá ningún efecto. En caso contrario, el valor por defecto de la propiedad es «true».

Esta enumeración se introdujo en Qt 6.7.

Funciones de acceso:

bool isAnimationEnabled() const
void setAnimationEnabled(bool enable)

Véase también animated().

aspectRatioMode : Qt::AspectRatioMode

Cómo se adapta la representación a la relación de aspecto del cuadro de visualización SVG

Los modos admitidos son:

  • Qt::IgnoreAspectRatio (el predeterminado): se ignora la relación de aspecto y la representación se estira hasta los límites de destino.
  • Qt::KeepAspectRatio: la representación se centra y se escala al máximo posible dentro de los límites de destino, conservando la relación de aspecto.

Funciones de acceso:

Qt::AspectRatioMode aspectRatioMode() const
void setAspectRatioMode(Qt::AspectRatioMode mode)

framesPerSecond : int

Esta propiedad contiene el número de fotogramas por segundo que se van a mostrar

El número de fotogramas por segundo es 0 si el documento actual no está animado.

Funciones de acceso:

int framesPerSecond() const
void setFramesPerSecond(int num)

Véase también animated().

[since 6.7] options : QtSvg::Options

Esta propiedad contiene un conjunto de indicadores de QtSvg::Option que pueden utilizarse para activar o desactivar diversas funciones relacionadas con el análisis y la representación de archivos SVG.

Para que surta efecto, esta propiedad debe establecerse antes de que se ejecute ` load()` ( before ). Ten en cuenta que los constructores que aceptan un parámetro de fuente SVG realizarán la carga durante la construcción.

Esta enumeración se introdujo en Qt 6.7.

Funciones de acceso:

QtSvg::Options options() const
void setOptions(QtSvg::Options flags)

Véase también setDefaultOptions.

viewBox : QRectF

Esta propiedad contiene el rectángulo que especifica el área visible del documento en coordenadas lógicas

Funciones de Access:

QRectF viewBoxF() const
void setViewBox(const QRect &viewbox)
void setViewBox(const QRectF &viewbox)

Documentación de las funciones de miembro

QSvgRenderer::QSvgRenderer(QObject *parent = nullptr)

Crea un nuevo renderizador con el ` parent` indicado.

QSvgRenderer::QSvgRenderer(QXmlStreamReader *contents, QObject *parent = nullptr)

Crea un nuevo renderizador con el ` parent ` indicado y carga los datos SVG utilizando el lector de flujo especificado por ` contents`.

QSvgRenderer::QSvgRenderer(const QByteArray &contents, QObject *parent = nullptr)

Crea un nuevo renderizador con el ` parent ` indicado y carga los datos SVG desde la matriz de bytes especificada por ` contents`.

QSvgRenderer::QSvgRenderer(const QString &filename, QObject *parent = nullptr)

Crea un nuevo renderizador con el ` parent ` indicado y carga el contenido del archivo SVG con el ` filename` especificado.

[virtual noexcept] QSvgRenderer::~QSvgRenderer()

Destruye el renderizador.

bool QSvgRenderer::animated() const

Devuelve «true» si el documento actual contiene elementos animados; en caso contrario, devuelve «false».

Véase también framesPerSecond().

QRectF QSvgRenderer::boundsOnElement(const QString &id) const

Devuelve el rectángulo delimitador del elemento con el id dado. La matriz de transformación de los elementos padres no afecta a los límites del elemento.

Véase también transformForElement().

QSize QSvgRenderer::defaultSize() const

Devuelve el tamaño predeterminado del contenido del documento.

bool QSvgRenderer::elementExists(const QString &id) const

Devuelve «true» si el elemento con el « id » indicado existe en el archivo SVG que se está analizando y es un elemento renderizable.

Nota: este método devuelve «true» únicamente para los elementos que se pueden renderizar. Esto implica que los elementos que se consideran parte de las propiedades de estilo de relleno/trazo, por ejemplo, los gradientes radiales (radialGradients), aunque estén marcados con atributos «id», no serán detectados por este método.

bool QSvgRenderer::isValid() const

Devuelve «true» si hay un documento válido actualmente; en caso contrario, devuelve «false».

[slot] bool QSvgRenderer::load(QXmlStreamReader *contents)

Carga el archivo SVG especificado en contents y devuelve «true» si el contenido se ha analizado correctamente; en caso contrario, devuelve «false».

El lector se utilizará desde la posición en la que se encuentre actualmente. Si contents es null, el comportamiento es indefinido.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        svgRenderer, qOverload(&QSvgRenderer::load));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        svgRenderer, [receiver = svgRenderer](QXmlStreamReader *contents) { receiver->load(contents); });
Para ver más ejemplos y enfoques, consulta «Conexión a ranuras sobrecargadas».

[slot] bool QSvgRenderer::load(const QByteArray &contents)

Carga el archivo en formato SVG especificado contents y devuelve «true» si el contenido se ha analizado correctamente; en caso contrario, devuelve «false».

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        svgRenderer, qOverload(&QSvgRenderer::load));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        svgRenderer, [receiver = svgRenderer](const QByteArray &contents) { receiver->load(contents); });
Para ver más ejemplos y métodos, consulta la sección sobre cómo conectarse a ranuras sobrecargadas.

[slot] bool QSvgRenderer::load(const QString &filename)

Carga el archivo SVG especificado en ` filename` y devuelve «true» si el contenido se ha analizado correctamente; en caso contrario, devuelve «false».

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        svgRenderer, qOverload(&QSvgRenderer::load));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        svgRenderer, [receiver = svgRenderer](const QString &filename) { receiver->load(filename); });
Para ver más ejemplos y métodos, consulta «Conexión a ranuras sobrecargadas».

[slot] void QSvgRenderer::render(QPainter *painter)

Representa el documento actual, o el fotograma actual de un documento animado, utilizando el ` painter` especificado.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        svgRenderer, qOverload(&QSvgRenderer::render));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        svgRenderer, [receiver = svgRenderer](QPainter *painter) { receiver->render(painter); });
Para ver más ejemplos y métodos, consulta la sección «Conexión a ranuras sobrecargadas».

[slot] void QSvgRenderer::render(QPainter *painter, const QRectF &bounds)

Representa el documento actual, o el fotograma actual de un documento animado, utilizando el « painter » proporcionado en el « bounds » especificado dentro del «painter». Si el « bounds » no está vacío, la salida se escalará para llenarlo, ignorando cualquier relación de aspecto implícita en el SVG.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        svgRenderer, qOverload(&QSvgRenderer::render));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        svgRenderer, [receiver = svgRenderer](QPainter *painter, const QRectF &bounds) { receiver->render(painter, bounds); });
Para ver más ejemplos y enfoques, consulta la sección sobre cómo conectarse a ranuras sobrecargadas.

[slot] void QSvgRenderer::render(QPainter *painter, const QString &elementId, const QRectF &bounds = QRectF())

Representa el elemento dado con un ` elementId ` utilizando el ` painter ` indicado en el ` bounds` especificado. Si no se especifica el rectángulo delimitador, el elemento SVG se asigna a todo el dispositivo de pintura.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        svgRenderer, qOverload(&QSvgRenderer::render));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        svgRenderer, [receiver = svgRenderer](QPainter *painter, const QString &elementId, const QRectF &bounds) { receiver->render(painter, elementId, bounds); });
Para ver más ejemplos y métodos, consulta la sección sobre cómo conectarse a ranuras sobrecargadas.

[signal] void QSvgRenderer::repaintNeeded()

Esta señal se emite cada vez que es necesario actualizar la representación del documento, normalmente con fines de animación.

[static, since 6.8] void QSvgRenderer::setDefaultOptions(QtSvg::Options flags)

Establece los indicadores de opción con los que se crearán los renderizadores en flags. Por defecto, no se establece ningún indicador.

En tiempo de ejecución, esto se puede anular mediante la variable de entorno QT_SVG_DEFAULT_OPTIONS.

Esta función se introdujo en Qt 6.8.

QTransform QSvgRenderer::transformForElement(const QString &id) const

Devuelve la matriz de transformación del elemento con el id dado. La matriz es el producto de las transformaciones de los elementos padres de dicho elemento. No se incluye la transformación del propio elemento.

Para hallar el rectángulo delimitador del elemento en coordenadas lógicas, puedes aplicar la matriz al rectángulo devuelto por boundsOnElement().

Véase también boundsOnElement().

QRect QSvgRenderer::viewBox() const

Devuelve viewBoxF().toRect().

Véase también setViewBox() y viewBoxF().

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