SVG dalam .NET MAUI: Simpan SVG, Rujuk PNG

Untuk menggunakan SVG dalam alur kerja gambar terbundel .NET MAUI, simpan SVG dalam proyek dan rujuk nama PNG yang dihasilkannya dari XAML atau C#. MAUI memproses sumber vektor selama build. Karena itu, Image yang menunjuk ke compass.png dapat benar meskipun file yang Anda tambahkan adalah compass.svg. Panduan gambar proyek Microsoft mendokumentasikan konversi ini.

Itu menjelaskan nama file, tetapi masih menyisakan pertanyaan desain: ukuran apa yang harus dihasilkan MAUI, dan apa yang harus Anda periksa setelahnya? Ikuti satu lambang kompas kecil melalui sumber, metadata proyek, dan deklarasi tampilan.

Ikuti sumber melalui build

SVG yang dapat diedit dan gambar yang dikemas memiliki tugas berbeda. Simpan sumber agar Anda dapat menyesuaikan bentuk, ruang kosong, atau warnanya nanti. Gunakan nama yang dihasilkan dalam view yang menampilkannya.

Dokumentasi kontrol Image menjelaskan gambar kepadatan target yang masuk ke paket aplikasi dan sistem operasi yang memilih resolusi sesuai. Mempertahankan master SVG tidak berarti alur kerja khusus ini menyerahkan dokumen SVG aktif ke view.

Tambahkan SVG kecil dengan batas jelas

Simpan contoh orisinal ini sebagai Resources/Images/compass.svg:

<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96">
  <circle cx="48" cy="48" r="34" fill="none" stroke="#173e52" stroke-width="8"/>
  <path d="M58 28L52 52L28 58Z" fill="#ed765e"/>
</svg>

Cincin menyisakan pusat transparan, dan jarum koral merupakan bentuk terpisah. Detail tersebut memberi Anda hal khusus untuk diperiksa setelah impor. Dimensi yang dideklarasikan dan viewBox persegi juga memperjelas pembingkaian yang dimaksudkan. Lihat panduan file SVG untuk perbedaan antara geometri vektor dan bitmap yang ditanamkan dalam pembungkus SVG.

Dalam proyek Anda, pastikan file memiliki build action MauiImage. Microsoft mendokumentasikan folder Resources/Images sebagai lokasi normal. Sebelum menambahkan XML, periksa item proyek yang sudah ada: proyek Anda mungkin sudah menyertakan folder itu dengan wildcard. Penyiapan gambar proyek menjelaskan penempatan dan build action.

Perbarui item yang sudah ada sekali

Jika wildcard MauiImage yang ada sudah menyertakan file kompas, letakkan pembaruan metadata ini setelah penyertaan tersebut:

<ItemGroup>
  <MauiImage Update="Resources\Images\compass.svg" BaseSize="48,48" />
</ItemGroup>

Update mengubah metadata pada item yang sudah ada. Operasi ini tidak menambahkan file yang belum ada ke daftar item. Jika proyek Anda tidak memiliki penyertaan yang cocok, tambahkan file sekali dengan build action MauiImage atau Include eksplisit. Referensi Item MSBuild Microsoft membedakan operasi tersebut.

Ini menghindari perbaikan yang menggoda: menambahkan entri Include berulang kali saat men-debug gambar hilang. Pastikan dahulu apakah file disertakan, lalu ubah metadata-nya.

Rujuk PNG dan atur area tampilan

Letakkan deklarasi ini dalam halaman atau tata letak MAUI yang sudah ada:

<Image Source="compass.png"
       WidthRequest="48"
       HeightRequest="48"
       Aspect="AspectFit"
       SemanticProperties.Description="Compass" />

Ekstensi .png disengaja. Lebar dan tinggi meminta area tampilan persegi; AspectFit menjaga seluruh gambar terlihat di dalamnya. Jika ilustrasi Anda persegi panjang, gunakan area tampilan yang sesuai alih-alih meregangkannya untuk mengisi persegi. Referensi penskalaan Image Microsoft membedakan penyesuaian, pemotongan, dan peregangan.

Kode kompas adalah contoh penyiapan orisinal, bukan pengujian rendering perangkat yang direkam. Build dalam proyek target Anda sendiri dan periksa view yang dihasilkan. Nama file yang benar saja tidak dapat membuktikan bahwa artwork khusus Anda dirender sesuai tujuan.

BaseSize dan ukuran tata letak menyelesaikan masalah berbeda

BaseSize="48,48" menyediakan dimensi dasar yang digunakan MAUI untuk menghasilkan gambar khusus kepadatan. Tanpa ukuran dasar eksplisit, MAUI menggunakan dimensi SVG sendiri. Microsoft mendokumentasikan kedua aturan dalam Mengubah ukuran gambar.

Dalam contoh ini, gambar sumber menggunakan ruang koordinat 96 kali 96, sedangkan ukuran dasar dan view yang diminta adalah 48 kali 48. Angka tersebut merupakan pilihan penulisan yang disengaja, bukan dimensi output terukur dari build. Cincin seharusnya mempertahankan proporsinya ketika diskalakan.

Jika Anda kemudian menggunakan lambang yang sama dalam view jauh lebih besar, tinjau kembali ukuran build dan periksa penggunaan itu juga. Mengubah WidthRequest tidak mengedit artwork sumber atau metadata build-nya. Sebaliknya, mengubah BaseSize tidak menghapus margin kosong di dalam SVG. Rapatkan batas gambar dalam sumber jika lambangnya sendiri terlihat terlalu kecil dalam view yang ukurannya sudah benar.

Hindari menggunakan Resize="false" sebagai perbaikan ketajaman umum. Pengaturan ini menonaktifkan perubahan ukuran gambar vektor dalam pipeline ini. Pilih hanya ketika perilaku itu yang Anda maksudkan, mengikuti opsi resize yang didokumentasikan.

Periksa gambar yang hilang atau tak terduga secara berurutan

1. Konfirmasi nama file dan item proyek. Gunakan nama huruf kecil seperti compass.svg, dan periksa gambar lain dengan nama yang sama. Aturan penamaan Microsoft mewajibkan nama gambar unik dan karakter yang kompatibel dengan Android.
2. Periksa sumber view. Untuk alur kerja SVG terbundel, gunakan compass.png dalam XAML atau C#.
3. Bandingkan area tampilan yang dimaksudkan dengan ukuran dasar. Perubahan ukuran view dan perubahan ukuran build dilakukan di tempat berbeda.
4. Periksa artwork itu sendiri. Apakah pusat cincin masih terbuka? Apakah jarum koral terlihat jelas sebagai bentuk tersendiri? Apakah lambang terpusat, atau ruang kosong sumber yang tidak terlihat menggesernya ke samping?

Periksa juga metadata gambar yang mengubah pewarnaan. Panduan gambar proyek mendokumentasikan TintColor dan Color untuk warna tint dan latar belakang. Biarkan keduanya tidak diatur untuk contoh dua warna ini kecuali Anda bermaksud mengubah tampilannya. Periksa gambar di atas latar belakang halaman sebenarnya, tempat hilangnya bukaan transparan lebih mudah ditemukan.

Ketika Anda membutuhkan perilaku SVG saat runtime

Konten SVG yang diunduh, path interaktif, atau pengeditan saat runtime membutuhkan keputusan implementasi terpisah. Instruksi gambar terbundel di atas tidak membuktikan dukungan untuk pekerjaan tersebut.

Sebagai contoh, proyek sampel SVG Vapolia mendokumentasikan kontrol SvgImage dan SvgImageSource-nya sendiri serta penyiapan sumber daya tertanam. Itu merupakan kontrak pemuatan berbeda. Evaluasi fitur dan platform target yang didukung renderer menggunakan file Anda sebenarnya sebelum memperkenalkannya; menukar ekstensi nama file dalam deklarasi Image normal tidak menginstal renderer.

Artwork yang sama juga membutuhkan penyiapan berbeda dalam alur kerja gambar SVG Flutter, katalog aset SwiftUI, dan impor VectorDrawable Android. Gunakan ulang master sumber, lalu ikuti aturan masing-masing tujuan.

Siapkan master vektor ketika hanya PNG tersisa

Jika kompas atau logo hanya tersedia sebagai PNG, PerfectVector dapat membantu membuat artwork SVG yang dapat diedit sebelum Anda menambahkannya ke proyek MAUI. Konversikan PNG menjadi SVG, lalu periksa bukaan cincin, bagian kecil terpisah, dan jarak dalam editor. Simpan master bersih untuk perubahan ukuran atau warna di kemudian hari.

Vektorisasi tidak memperbaiki deklarasi MauiImage atau mengubah pipeline gambar terbundel menjadi parser SVG runtime. Jika sumber sudah berupa SVG yang dapat diedit, kerjakan konfigurasi proyek atau gambarnya langsung. Foto dan artwork bertekstur mungkin lebih berguna sebagai gambar raster; menelusurinya hanya karena aplikasi menerima sumber SVG menambahkan keputusan artwork terpisah.

FAQ

Mengapa saya merujuk PNG ketika saya menambahkan SVG? .NET MAUI mengonversi sumber gambar SVG terbundel menjadi PNG selama build. Simpan SVG dalam proyek dan rujuk nama file PNG dari XAML atau C#.

Apakah BaseSize menetapkan ukuran kontrol Image? BaseSize menetapkan dimensi dasar yang digunakan untuk menghasilkan gambar build khusus kepadatan. Tata letak view dan permintaan ukuran mengendalikan area tampilannya.

Haruskah saya menambahkan MauiImage Include lain untuk mengubah BaseSize? Periksa apakah file sudah disertakan, termasuk melalui wildcard. Gunakan Update untuk mengubah metadata item yang sudah ada; gunakan Include hanya ketika item perlu ditambahkan.

Apakah ini memuat SVG yang diunduh setelah aplikasi di-build? Alur kerja gambar terbundel tidak mencakup pengunduhan dan penguraian SVG saat runtime. Pilih dan uji pendekatan rendering runtime untuk kebutuhan tersebut.

Sources

1. Microsoft — Tambahkan gambar ke proyek aplikasi .NET MAUI — Pemrosesan SVG-ke-PNG, item gambar, nama file, ukuran dasar, dan metadata build.
2. Microsoft — Image — Referensi gambar lokal, pemilihan kepadatan target, ukuran view, dan perilaku penskalaan.
3. Microsoft — Elemen Item (MSBuild) — Perbedaan antara menambahkan item dengan Include dan mengubah metadata yang sudah ada dengan Update.
4. Vapolia — Sampel SVG — Kontrol SVG runtime dan alur kerja pemuatan sumber daya yang terpisah.

Bekerja dari lambang aplikasi yang hanya tersedia sebagai raster? Ubah PNG Anda menjadi SVG yang dapat diedit, periksa bukaan dan jaraknya, lalu tambahkan master tersebut ke MAUI dan lihat gambar yang dihasilkan dalam aplikasi target Anda.