SVG in Qt: scegli il renderer e controlla il file

Per SVG in un'app Qt Widgets, parti da QSvgWidget quando vuoi visualizzare un disegno. Usa QSvgRenderer quando devi disegnarlo su una destinazione scelta. La distinzione conta: disegnare una sola volta in una QImage di dimensioni fisse lascia pixel da visualizzare, mentre conservare l'SVG permette di renderizzarlo di nuovo a un'altra dimensione. La guida Qt al rendering descrive entrambe le modalità.

Scegli prima la modalità, poi controlla la grafica. Un'anteprima nel browser può mostrare il progetto desiderato, ma non può dimostrare che Qt supporti ogni funzionalità usata dal file.

Scegli una modalità di visualizzazione prima di modificare l'SVG

Qt documenta QSvgWidget come widget di visualizzazione SVG ed espone il suo renderer tramite renderer(). Il widget appartiene a SvgWidgets; la sua dipendenza CMake è Qt6::SvgWidgets. Il riferimento della classe è più utile qui di un vecchio esempio che aggiunge soltanto il modulo SVG generale.

Visualizzare un SVG non crea un editor di illustrazioni. Conserva un originale sorgente separato se qualcuno dovrà spostare una foglia, rimodellare un angolo o ricolorare un dettaglio staccato.

Prova una piccola sorgente prima dell'illustrazione completa

Salva questo disegno originale come leaf.svg. Usa una foglia riempita, una nervatura chiara e un cerchio corallo separato:

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

La tela larga è intenzionale. Se la foglia diventa alta e stretta, indaga sulla gestione delle proporzioni prima di modificarne le curve. Se il cerchio scompare, controlla i limiti visibili e confronta il file caricato con la sorgente. Questo piccolo esempio offre dettagli riconoscibili senza dipendere da ritagli o effetti.

Per informazioni sul file stesso, la guida al formato SVG spiega la differenza fra forme vettoriali e un contenitore SVG che racchiude una bitmap.

Un esempio minimo con 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();
}

Passa il nome del file SVG come argomento del programma, preferibilmente un percorso assoluto durante i test. Il codice di uscita 1 indica che questo esempio non ha ricevuto esattamente un nome di file; 2 indica che il renderer non ha segnalato un documento valido. Sono codici scelti per questo esempio, non l'API dei codici di errore di Qt.

isValid() verifica il documento caricato. Non è un test di approvazione visiva. L'impostazione esplicita KeepAspectRatio chiede al renderer di preservare le proporzioni; il riferimento QSvgRenderer documenta il controllo di validità e le modalità del rapporto d'aspetto.

Usa questo CMakeLists.txt accanto alla sorgente:

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)

L'esempio collega Widgets per l'applicazione, SvgWidgets per il widget di visualizzazione e Svg per le chiamate al renderer. Qt elenca il componente Svg del renderer separatamente dal componente SvgWidgets.

Configura e compila con il kit di sviluppo Qt 6 installato, poi esegui leaf_preview con il percorso di leaf.svg. Questo è un esempio di sorgente documentato; non lo abbiamo compilato né eseguito in un ambiente Qt nativo. Verifica la build effettiva e la grafica sul sistema di destinazione prima di adottarlo.

Controlla il supporto attuale invece di presumere la parità con il browser

Il moderno Qt SVG non è limitato soltanto alle funzionalità statiche di SVG Tiny. Qt documenta elementi aggiuntivi a partire da Qt 6.7, analizzati per impostazione predefinita, con un'opzione per limitare l'analisi alle funzionalità Tiny. Il suo riferimento alle funzionalità estese elenca le aggiunte supportate e i loro limiti.

Un limite concreto è clipPath: la stessa pagina lo indica come non supportato. Un file che dipende dal ritaglio merita quindi un esame della sorgente anche se appare corretto nel browser. Alcuni tipi di maschere e filtri hanno un supporto documentato, ma ciò non dimostra il supporto di ogni effetto o impostazione di esportazione.

Quando la foglia semplice funziona ma un'illustrazione più grande differisce, crea una copia e rimuovi una funzionalità sospetta alla volta. Per grafica ritagliata, considera di produrre la geometria visibile desiderata in un editor invece di dipendere dall'operazione di ritaglio. Confronta la sagoma risultante con l'originale prima di sostituirlo.

Il testo richiede un controllo proprio. Se le lettere cambiano, segui la guida ai problemi dei caratteri SVG. Convertire le lettere in forme è una scelta di progettazione; non dovrebbe essere la prima correzione per un nome di file errato o un modulo mancante.

Riconosci quando la pipeline trasforma l'SVG in pixel

Supponiamo che il codice renderizzi la foglia una sola volta in una piccola QImage, crei una pixmap da quell'immagine e poi ingrandisca la pixmap. L'ingrandimento agisce sul risultato raster. La sorgente SVG non è scomparsa, ma quell'operazione di visualizzazione successiva non le richiede più un nuovo rendering.

La guida Qt al rendering distingue il disegno in un'immagine da quello nell'evento paint di un widget. Se la visualizzazione cambia dimensione, decidi dove l'SVG debba essere renderizzato di nuovo. Evita di interpretare una bitmap memorizzata nella cache come prova che la sorgente stessa non possa scalare.

La stessa distinzione conta nella preparazione di un set di icone SVG. Mantieni limiti sorgente coerenti, poi giudica ogni icona alla dimensione d'uso effettiva. Una grande foglia riconoscibile può comunque perdere la nervatura o il cerchio staccato quando la visualizzazione è piccola.

Esamina il risultato prima di semplificare tutto

Parti dal file che carichi effettivamente, non da un'altra esportazione con un nome simile. Conferma che l'esempio semplice appaia, poi confronta la grafica di produzione alla dimensione prevista e dopo un ridimensionamento.

Per la foglia, verifica che il cerchio resti separato, la nervatura rimanga visibile e la tela larga non deformi il disegno. Sono controlli di accettazione per la tua esecuzione, non risultati segnalati dalla nostra. Se l'intera vista è vuota, la lista di controllo per SVG vuoti aiuta a distinguere grafica invisibile e limiti del disegno dalla configurazione dell'applicazione.

Mantieni fotografie o illustrazioni con texture come risorse raster quando è adatto al progetto. Scegliere SVG dovrebbe risolvere un'esigenza grafica; non dimostra di per sé file più piccoli, rendering più veloce o output identico fra motori.

Ricostruisci un originale sorgente quando resta soltanto un raster

Se l'icona sopravvive soltanto come PNG o JPG, il flusso da immagine a vettore di PerfectVector può aiutare a preparare grafica SVG modificabile prima del passaggio a Qt. Controlla sagoma, spazi e dettagli staccati dopo la conversione, poi verifica quell'SVG con la modalità Qt scelta. La vettorializzazione prepara geometria; non aggiunge funzionalità al renderer e non trasforma un widget di visualizzazione in un editor di tracciati.

Se hai già un originale vettoriale pulito, modifica direttamente quel file. Semplifica una copia soltanto quando una funzionalità specifica o un dettaglio a piccole dimensioni richiede attenzione e conserva la sorgente più ricca per modifiche future.

FAQ

Dovrei usare QSvgWidget o QSvgRenderer? Usa QSvgWidget per visualizzare un SVG in un'interfaccia Widgets. Usa QSvgRenderer quando devi controllare il disegno su una destinazione scelta, come un widget personalizzato o un'immagine.

Qt attuale supporta soltanto SVG Tiny? Qt documenta il supporto statico SVG Tiny più alcune estensioni introdotte in Qt 6.7. Controlla il riferimento attuale delle funzionalità e le opzioni configurate invece di presumere il solo supporto Tiny o la parità con il browser.

Perché un SVG può apparire sfocato dopo averlo messo in una pixmap? Se lo hai prima renderizzato in un'immagine raster di dimensioni fisse, ingrandire quel risultato ridimensiona i pixel. Rivedi la destinazione del rendering e se l'SVG viene renderizzato di nuovo alla dimensione necessaria.

Un caricamento SVG valido dimostra che ogni dettaglio è stato renderizzato correttamente? No. Un controllo di validità non sostituisce l'esame visivo. Confronta limiti, proporzioni, piccoli dettagli e funzionalità supportate nell'applicazione di destinazione effettiva.

Fonti

1. Qt — Rendering di file SVG — Widget di visualizzazione, destinazioni del painter e distinzione fra rendering nei widget e intermedi raster.
2. Qt — Classe QSvgWidget — Widget di visualizzazione, accesso al renderer e dipendenza SvgWidgets.
3. Qt — Classe QSvgRenderer — Dipendenza Svg, validità del documento e impostazioni del rapporto d'aspetto.
4. Qt — Funzionalità estese — Estensioni moderne e limiti espliciti, inclusi tracciati di ritaglio non supportati.

Parti da un piccolo file e controllalo nella modalità Qt scelta. Se devi ricostruire grafica raster, prepara un candidato SVG modificabile, confronta le forme con la sorgente e ripeti i controlli nell'applicazione prima di sostituire la risorsa.