Immagini SVG in Flutter: risorse, dimensioni e controlli

Per visualizzare una risorsa SVG in Flutter, aggiungi flutter_svg, dichiara il file in pubspec.yaml e carica lo stesso percorso con SvgPicture.asset. Assegna dimensioni al widget o vincoli di layout adatti, poi esamina la grafica nell'app. Il costruttore delle risorse del pacchetto documenta quel percorso di caricamento.

Tieni separate due domande: l'app ha caricato il file previsto e il renderer ha riprodotto la grafica prevista? Riesportare un disegno non corregge una chiave di risorsa scritta male. Correggere la chiave non semplifica un effetto non supportato.

Questa guida usa un'illustrazione originale di colline e sole per rendere gestibili quei controlli. Il codice segue l'API documentata; non è un resoconto di un test su un'app compilata.

Parti da una piccola sorgente che puoi esaminare

Crea assets/illustrations/hills.svg nel progetto Flutter:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 48">
  <circle cx="49" cy="11" r="6" fill="#e99b30"/>
  <path d="M4 42L24 14L44 42Z" fill="#167d8d"/>
  <path d="M28 42L43 23L60 42Z" fill="#233b63"/>
</svg>

La sorgente ha due colline triangolari sovrapposte e un sole ambra staccato. Usa riempimenti espliciti, non ha testo o immagini collegate e lascia uno spazio visibile tra sole e colline. Quei dettagli offrono una breve lista di accettazione durante il controllo dell'app.

Conserva una copia di questo file semplice mentre introduci in seguito la tua grafica. Se la piccola sorgente funziona ma la sostituzione fallisce, confronta le strutture prima di cambiare tutta la configurazione di caricamento.

Una risorsa SVG Flutter è anche un percorso di consegna diverso da XML Android VectorDrawable. Se la destinazione è un drawable Android nativo, usa la guida di preparazione Android VectorDrawable anziché considerare intercambiabili i due formati.

Aggiungi il pacchetto e dichiara il file esatto

Dalla radice del progetto Flutter, usa il comando ufficiale di installazione:

flutter pub add flutter_svg

Poi aggiungi questa voce di risorsa sotto la sezione flutter: esistente di pubspec.yaml:

flutter:
  assets:
    - assets/illustrations/hills.svg

Unisci la voce alla configurazione attuale anziché creare una seconda sezione flutter:. Mantieni l'indentazione mostrata. La documentazione delle risorse Flutter definisce questi percorsi rispetto a pubspec.yaml e spiega come i file elencati entrano nel pacchetto dell'app.

Usa la stessa ortografia, maiuscole e struttura di directory nel nome del file, nella dichiarazione e nella chiamata Dart. Per questo primo controllo, una voce di file esplicita è più facile da confrontare di una voce generale di cartella. Se in seguito dichiari directory, Flutter documenta che una voce di directory copre i suoi file diretti; le directory annidate richiedono voci proprie.

Dopo aver cambiato la configurazione delle risorse, ricompila ed esegui l'app con il normale procedimento di sviluppo. Non supporre che un file visibile nell'editor sia già incluso nell'app che stai guardando.

Carica la grafica in un riquadro definito

Aggiungi queste importazioni al file Dart che contiene il widget:

import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';

Inserisci questo widget in una parte adatta dello schermo:

SvgPicture.asset(
  'assets/illustrations/hills.svg',
  width: 128,
  height: 96,
  fit: BoxFit.contain,
  semanticsLabel: 'Sun above two hills',
  errorBuilder: (context, error, stackTrace) =>
      const Text('Illustration unavailable'),
)

Il riquadro segue le proporzioni sorgente. Esamina sole staccato, entrambi i colori delle colline e margini esterni prima di provare dimensioni più piccole. Poi usa le dimensioni richieste dal componente effettivo; i numeri sopra sono un esempio, non dimensioni minime o una raccomandazione sulle prestazioni.

La documentazione del costruttore raccomanda dimensioni esplicite o vincoli stretti di layout affinché il caricamento non cambi inaspettatamente il layout. Se la grafica appare troppo piccola nel riquadro, esamina lo spazio vuoto del viewBox oltre alle dimensioni del widget.

L'etichetta descrive lo scopo di questa immagine autonoma. L'API semanticsLabel la collega all'etichetta semantica dell'immagine. Per un'immagine decorativa accanto a testo che comunica già il significato, considera invece di escluderla dalla semantica. L'opzione excludeFromSemantics del costruttore ha precedenza sull'etichetta. Esamina il significato pronunciato dell'intero componente anziché etichettare ogni forma separatamente.

Distingui un segnaposto di caricamento da un errore

Un indicatore di caricamento non dimostra che un SVG sia stato accettato. Il pacchetto fornisce placeholderBuilder per il periodo di acquisizione o decodifica, mentre l'attuale API errorBuilder fornisce un widget quando il caricamento dell'immagine fallisce.

L'esempio sopra usa un breve testo alternativo. Durante lo sviluppo, cambia deliberatamente il percorso Dart in un nome di file inesistente e controlla di poter riconoscere l'errore. Ripristina il percorso corretto prima di continuare. Questo testa la presentazione dell'errore senza cambiare il disegno stesso.

Poi testa la sorgente reale. Se fallisce ancora, esamina l'output diagnostico e confronta prima il percorso dichiarato. Un esempio di rete che riesce a visualizzare un altro SVG non dimostra che il tuo file locale sia nel pacchetto o che le sue funzionalità siano supportate.

Decidi se conservare la palette o applicare una tinta

Lascia colorFilter non impostato quando le colline devono restare verde petrolio e blu scuro con sole ambra. Per un trattamento volutamente monocromatico, aggiungi un filtro come:

colorFilter: const ColorFilter.mode(
  Color(0xFF175CD3),
  BlendMode.srcIn,
),

Il pacchetto documenta questo schema di colorazione. La documentazione Flutter di BlendMode spiega che srcIn usa l'opacità della destinazione ignorandone i canali di colore. Una tinta uniforme elimina quindi la distinzione della palette sorgente; è una scelta di disegno, non una correzione per conservare i colori.

Per le colline, controlla se perdere il contrasto tra i due triangoli sovrapposti rende meno leggibile l'illustrazione. Conserva la palette originale se quelle regioni devono restare distinte. Il pacchetto documenta anche ColorMapper per sostituzioni selettive, ma parti dal caso più semplice senza filtro durante la diagnosi di una differenza.

Semplifica le funzionalità soltanto dopo il caricamento del file

La documentazione flutter_svg raccomanda attributi di presentazione durante l'esportazione da Illustrator perché il supporto CSS è incompleto e immagini incorporate anziché collegate esternamente. Fornisce anche un controllo di compatibilità basato sul compilatore. Segui quel controllo nel tuo ambiente Flutter/Dart quando devi indagare una risorsa complessa.

Un'anteprima nel browser è un riferimento utile per l'aspetto previsto; non dimostra che ogni funzionalità SVG venga renderizzata in modo identico attraverso il pacchetto. Conserva la grafica originale e semplifica una copia un cambiamento alla volta.

Se la sorgente contiene scritte, decidi se devono restare testo dell'app o grafica fissa. La guida ai cambiamenti di font SVG spiega perché l'aspetto può dipendere dalla gestione di testo e font. Non ricalcare un'etichetta soltanto per risolvere un problema di percorso della risorsa.

Per una famiglia di risorse UI, confronta insieme dimensioni visive e spaziatura. La guida alla preparazione di icone per kit UI aiuta con quel controllo di coerenza.

Usa la vettorializzazione quando la sorgente richiede recupero

Conserva un SVG esistente pulito. Una fotografia o uno sfondo con texture possono essere consegnati meglio come risorsa raster appropriata; cambiare l'estensione non li rende geometria vettoriale utile.

Se una semplice illustrazione esiste soltanto come PNG grezzo, il procedimento da PNG a SVG di PerfectVector può aiutare a preparare un candidato modificabile. Ritaglia sulla grafica, esamina l'anteprima per forme mancanti e regioni di sfondo indesiderate e scarica l'SVG. Aggiungi quel file al pacchetto dell'app e ripeti i controlli di caricamento, palette, dimensioni e semantica.

Per l'esempio delle colline, cerca il sole staccato e la separazione tra i due pendii colorati. Conferma che il file contenga la struttura prevista; la guida al raster incorporato spiega perché un contenitore SVG può ancora contenere pixel.

Giudica la risorsa nell'app prima di scegliere una strategia di ottimizzazione. Questo procedimento non promette in generale che un SVG sia più piccolo o più veloce di un PNG.

Se riutilizzi la grafica in un'app .NET MAUI, segui il procedimento MAUI dalla sorgente al PNG. Il progetto conserva l'originale SVG mentre la vista referenzia un PNG preparato durante la build.

FAQ

Come aggiungo un'immagine SVG a Flutter? Aggiungi flutter_svg, dichiara la risorsa SVG in pubspec.yaml e carica il percorso corrispondente con SvgPicture.asset. Imposta dimensioni o vincoli appropriati ed esamina il risultato.

Perché il mio SVG locale non appare? Controlla prima dichiarazione della risorsa, percorso esatto, errore di caricamento e layout. Se una sorgente semplice funziona, confronta struttura e funzionalità supportate della grafica che fallisce.

Perché tutti i colori sono diventati uguali? Un filtro colore srcIn uniforme sostituisce la palette visibile con la propria tinta. Rimuovi quel filtro quando i colori originali devono restare distinti.

Devo trasformare un PNG in SVG per Flutter? No. Usa una risorsa raster adatta quando corrisponde alla grafica. La vettorializzazione è facoltativa per recuperare forme modificabili da una sorgente raster semplice.

Fonti

1. flutter_svg — Installazione — Installazione del pacchetto e importazione Dart.
2. Flutter — Aggiungere risorse e immagini — Dichiarazioni di risorse, percorsi e inclusione nel pacchetto.
3. flutter_svg — SvgPicture.asset — Caricamento delle risorse, dimensioni, adattamento e controlli di semantica.
4. flutter_svg — errorBuilder — Presentazione dell'errore distinta dai segnaposto di caricamento.
5. flutter_svg — semanticsLabel — Scopo semantico dell'immagine.
6. Flutter — BlendMode — Trattamento colore srcIn basato sull'opacità.
7. flutter_svg — Documentazione del pacchetto — Tinte, mappatura selettiva dei colori, indicazioni di esportazione e controlli di compatibilità.

Parti da una risorsa dichiarata e controlla percorso, palette, dimensioni e significato nell'app. Se un'illustrazione raster richiede recupero, prepara un candidato SVG, esamina le forme ed esegui gli stessi controlli prima di aggiungerlo alla famiglia di risorse.