SVG no Qt: escolha o renderizador e confira o arquivo

Para SVG em um aplicativo Qt Widgets, comece com QSvgWidget quando quiser exibir um desenho. Use QSvgRenderer quando precisar pintar o desenho em um destino escolhido. A distinção importa: pintar uma vez em um QImage de tamanho fixo deixa você com pixels para exibir, enquanto manter o SVG permite renderizá-lo novamente em outro tamanho. O guia de renderização do Qt descreve as duas opções.

Escolha primeiro a opção e confira a arte. Uma prévia no navegador pode mostrar o desenho pretendido, mas não comprova que o Qt oferece suporte a todos os recursos usados pelo arquivo.

Escolha uma opção de exibição antes de editar o SVG

O Qt documenta QSvgWidget como um widget de exibição SVG e expõe seu renderizador por renderer(). O widget pertence a SvgWidgets; sua dependência CMake é Qt6::SvgWidgets. A referência da classe é mais útil aqui que um exemplo antigo que só adiciona o módulo SVG geral.

Exibir um SVG não cria um editor de ilustrações. Mantenha um mestre de origem separado se alguém precisará mover uma folha, remodelar um canto ou recolorir um detalhe separado.

Experimente um arquivo original pequeno antes da ilustração completa

Salve este desenho original como leaf.svg. Ele usa uma folha preenchida, uma nervura clara e um 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>

A tela larga é deliberada. Se a folha fica alta e estreita, investigue o tratamento da proporção antes de editar suas curvas. Se o círculo desaparece, confira os limites visíveis e compare o arquivo carregado com o original. Este pequeno exemplo oferece detalhes reconhecíveis sem depender de recortes ou efeitos.

Para informações sobre o próprio arquivo, o guia do formato SVG explica a diferença entre formas vetoriais e um invólucro SVG que contém um bitmap.

Um exemplo mínimo de Qt 6 Widgets

Crie 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();
}

Passe o nome do arquivo SVG como argumento do programa, de preferência um caminho absoluto durante o teste. O código de saída 1 significa que este exemplo não recebeu um nome de arquivo; 2 significa que o renderizador não informou um documento válido. Esses códigos são escolhas desta amostra, não a API de códigos de erro do próprio Qt.

isValid() verifica o documento carregado. Ele não é um teste de aprovação visual. A configuração explícita KeepAspectRatio solicita ao renderizador que preserve as proporções; a referência de QSvgRenderer documenta a verificação de validade e os modos de proporção.

Use este CMakeLists.txt ao lado do código-fonte:

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)

O exemplo vincula Widgets para o aplicativo, SvgWidgets para o widget de exibição e Svg para as chamadas ao renderizador. O Qt lista o componente Svg do renderizador separadamente do componente SvgWidgets.

Configure e compile com seu kit de desenvolvimento Qt 6 instalado e execute leaf_preview com o caminho de leaf.svg. Este é um exemplo de código baseado na documentação; nós não o compilamos nem executamos em um ambiente Qt nativo. Teste o build real e a arte no sistema de destino antes de adotá-lo.

Confira o suporte atual em vez de supor equivalência com o navegador

O Qt SVG moderno não se restringe apenas aos recursos estáticos de SVG Tiny. O Qt documenta elementos adicionais a partir do Qt 6.7, interpretados por padrão, com uma opção para restringir a interpretação aos recursos Tiny. Sua referência de recursos estendidos lista as adições compatíveis e seus limites.

Um limite concreto é clipPath: a mesma página o marca como incompatível. Um arquivo que depende de recorte, portanto, merece inspeção do arquivo original mesmo se parece correto no navegador. Máscaras e filtros selecionados têm suporte documentado, mas isso não demonstra suporte a todos os efeitos ou configurações de exportação.

Quando a folha simples funciona, mas uma ilustração maior difere, faça uma cópia e remova um recurso suspeito por vez. Para uma arte recortada, considere produzir a geometria visível pretendida em um editor, em vez de depender da operação de recorte. Compare a silhueta resultante com o original antes de substituir seu mestre.

Texto precisa de sua própria verificação. Se as letras mudam, siga o guia de solução de problemas de fontes SVG. Transformar letras em formas é uma escolha de desenho; não deve ser o primeiro reparo para um nome de arquivo incorreto ou módulo ausente.

Perceba quando seu fluxo transforma o SVG em pixels

Suponha que seu código renderiza a folha uma vez em um QImage pequeno, cria um pixmap a partir dessa imagem e depois amplia o pixmap. A ampliação age sobre o resultado raster. O SVG original não desapareceu, mas essa operação posterior de exibição já não solicita uma nova renderização dele.

O guia de renderização do Qt distingue pintar em uma imagem de pintar no evento de pintura de um widget. Se sua exibição muda de tamanho, decida onde o SVG deve ser renderizado novamente. Evite tratar um bitmap em cache como evidência de que o próprio SVG original não consegue escalar.

A mesma distinção importa ao preparar um conjunto de ícones SVG. Mantenha limites consistentes no arquivo original e avalie cada ícone em seu tamanho real de uso. Uma folha grande reconhecível ainda pode perder sua nervura ou círculo separado quando a exibição é pequena.

Inspecione o resultado antes de simplificar tudo

Comece com o arquivo que você realmente carrega, não com outra exportação de nome semelhante. Confirme que o exemplo simples aparece e compare a arte de produção no tamanho pretendido e depois de um redimensionamento.

Para a folha, confira se o círculo continua separado, se a nervura permanece visível e se a tela larga não estica o desenho. São verificações de aceitação para sua própria execução, não resultados relatados da nossa. Se toda a visualização está vazia, a lista de verificação de SVG em branco ajuda a separar arte invisível e limites do desenho da configuração do aplicativo.

Mantenha fotos ou ilustrações texturizadas como recursos raster quando isso atende ao desenho. Escolher SVG deve resolver uma necessidade da arte; isso, por si só, não comprova arquivos menores, renderização mais rápida ou saída idêntica entre motores.

Recupere um mestre de origem quando resta apenas um raster

Se o ícone existe apenas como PNG ou JPG, o fluxo de imagem para vetor do PerfectVector pode ajudar a preparar uma arte SVG editável antes da entrega ao Qt. Inspecione a silhueta, os espaços e os detalhes separados após a conversão e teste esse SVG pela opção Qt escolhida. A vetorização prepara geometria; ela não adiciona recursos ao renderizador nem transforma um widget de exibição em editor de traçados.

Se você já tem um mestre vetorial limpo, ajuste esse arquivo diretamente. Simplifique uma cópia apenas quando um recurso específico ou um detalhe em tamanho pequeno precisar de atenção e preserve o arquivo original mais completo para futuras edições.

Perguntas frequentes

Devo usar QSvgWidget ou QSvgRenderer? Use QSvgWidget para exibir um SVG em uma interface Widgets. Use QSvgRenderer quando precisar controlar a pintura em um destino escolhido, como um widget personalizado ou uma imagem.

O Qt atual oferece suporte apenas a SVG Tiny? O Qt documenta suporte a SVG Tiny estático e extensões selecionadas introduzidas no Qt 6.7. Confira a referência atual de recursos e suas opções configuradas, em vez de supor suporte exclusivo a Tiny ou equivalência com o navegador.

Por que um SVG pode parecer borrado depois que o coloco em um pixmap? Se você primeiro o renderizou em uma imagem raster de tamanho fixo, ampliar esse resultado escala pixels. Reveja o destino de renderização e se o SVG é renderizado novamente no tamanho necessário.

Carregar um SVG válido comprova que todos os detalhes foram renderizados corretamente? Não. Uma verificação de validade não substitui a inspeção visual. Compare limites, proporções, pequenos detalhes e recursos compatíveis no aplicativo real de destino.

Fontes

1. Qt — renderização de arquivos SVG — Widgets de exibição, destinos de pintura e distinção entre renderização em widget e intermediários raster.
2. Qt — classe QSvgWidget — Widget de exibição, acesso ao renderizador e dependência SvgWidgets.
3. Qt — classe QSvgRenderer — Dependência Svg, validade do documento e configurações de proporção.
4. Qt — recursos estendidos — Extensões modernas e limites explícitos de recursos, incluindo traçados de recorte incompatíveis.

Comece com um arquivo pequeno e inspecione-o na opção Qt escolhida. Se uma arte raster precisa de recuperação, prepare uma versão candidata em SVG editável, confira as formas em relação à imagem original e repita as verificações no aplicativo antes de substituir seu recurso.