Menambahkan ikon aplikasi ke proyek aplikasi .NET MAUI

Artikel
06/19/2024

Setiap aplikasi memiliki ikon logo yang mewakilinya, dan ikon tersebut biasanya muncul di beberapa tempat. Misalnya, pada iOS ikon aplikasi muncul di layar Beranda dan di seluruh sistem, seperti di Pengaturan, pemberitahuan, dan hasil pencarian, dan di App Store. Di Android, ikon aplikasi muncul sebagai ikon peluncur dan di seluruh sistem, seperti di bilah tindakan, pemberitahuan, dan di Google Play Store. Di Windows, ikon aplikasi muncul di daftar aplikasi di menu mulai, taskbar, petak peta aplikasi, dan di Microsoft Store.

Dalam proyek aplikasi .NET Multi-platform App UI (.NET MAUI), ikon aplikasi dapat ditentukan dalam satu lokasi di proyek aplikasi Anda. Pada waktu build, ikon ini dapat secara otomatis diubah ukurannya menjadi resolusi yang benar untuk platform dan perangkat target, dan ditambahkan ke paket aplikasi Anda. Ini menghindari harus menduplikasi dan memberi nama ikon aplikasi secara manual per platform. Secara default, format gambar bitmap (non-vektor) tidak secara otomatis diubah ukurannya oleh .NET MAUI.

Ikon aplikasi .NET MAUI dapat menggunakan salah satu format gambar platform standar, termasuk file Scalable Vector Graphics (SVG).

Penting

.NET MAUI mengonversi file SVG ke file Portable Network Graphic (PNG). Oleh karena itu, saat menambahkan file SVG ke proyek aplikasi .NET MAUI Anda, file tersebut harus dirujuk dari XAML atau C# dengan ekstensi .png . Satu-satunya referensi ke file SVG harus ada di file proyek Anda.

Ubah ikon

Dalam proyek .NET MAUI Anda, gambar dengan MauiIcon tindakan build menunjuk ikon yang akan digunakan untuk aplikasi Anda. Ini diwakili dalam file proyek Anda sebagai <MauiIcon> item . Anda mungkin hanya memiliki satu ikon yang ditentukan untuk aplikasi Anda. Item berikutnya <MauiIcon> diabaikan.

Ikon yang ditentukan oleh aplikasi Anda dapat terdiri dari satu gambar, dengan menentukan file sebagai Include atribut :

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" />
</ItemGroup>

Hanya item pertama <MauiIcon> yang ditentukan dalam file proyek yang diproses oleh .NET MAUI. Jika Anda ingin menggunakan file lain sebagai ikon, pertama-tama hapus ikon yang ada dari proyek Anda, lalu tambahkan ikon baru dengan menyeretnya ke folder Resources\AppIcon proyek Anda. Visual Studio akan secara otomatis mengatur tindakan build-nya ke MauiIcon dan akan membuat item yang <MauiIcon> sesuai dalam file proyek Anda.

Catatan

Ikon aplikasi juga dapat ditambahkan ke folder lain dari proyek aplikasi Anda. Namun, dalam skenario ini tindakan build-nya harus diatur secara manual ke MauiIcon di jendela Properti .

Untuk mematuhi aturan penamaan sumber daya Android, nama file ikon aplikasi harus huruf kecil, dimulai dan diakhapi dengan karakter huruf, dan hanya berisi karakter alfanumerik atau garis bawah. Untuk informasi selengkapnya, lihat Gambaran umum sumber daya aplikasi di developer.android.com.

Setelah mengubah file ikon, Anda mungkin perlu membersihkan proyek di Visual Studio. Untuk membersihkan proyek, klik kanan pada file proyek di panel Penjelajah Solusi, dan pilih Bersihkan. Anda mungkin juga perlu menghapus instalan aplikasi dari platform target yang sedang Anda uji.

Perhatian

Jika Anda tidak membersihkan proyek dan menghapus instalan aplikasi dari platform target, Anda mungkin tidak melihat ikon baru Anda.

Setelah mengubah ikon, tinjau informasi konfigurasi khusus Platform.

Ikon yang disusam

Atau, ikon aplikasi dapat terdiri dari dua gambar, satu gambar yang mewakili latar belakang dan yang lain mewakili latar depan. Karena ikon diubah menjadi file PNG, ikon aplikasi yang disusam akan terlebih dahulu dilapisi dengan gambar latar belakang, biasanya gambar pola atau warna solid, diikuti oleh gambar latar depan. Dalam hal ini, Include atribut mewakili gambar latar belakang ikon, dan Foreground atribut mewakili gambar latar depan:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" ForegroundFile="Resources\AppIcon\appiconfg.svg" />
</ItemGroup>

Di Android, ForegroundScale atribut dapat ditentukan secara opsional untuk menskalakan ulang gambar latar depan sehingga sesuai dengan ikon aplikasi. Untuk informasi selengkapnya, lihat Peluncur adaptif.

Penting

Gambar latar belakang (Include atribut) harus ditentukan untuk <MauiIcon> item. Gambar latar depan (ForegroundFile atribut) bersifat opsional.

Mengatur ukuran dasar

.NET MAUI menggunakan ikon Anda di beberapa platform dan perangkat, dan mencoba mengubah ukuran ikon sesuai untuk setiap platform dan perangkat. Ikon aplikasi juga digunakan untuk tujuan yang berbeda, seperti entri toko untuk aplikasi Anda atau ikon yang digunakan untuk mewakili aplikasi setelah diinstal di perangkat.

Ukuran dasar ikon Anda mewakili kepadatan garis besar gambar, dan secara efektif merupakan faktor skala 1.0 yang berasal dari semua ukuran lainnya. Jika Anda tidak menentukan ukuran dasar untuk ikon aplikasi berbasis bitmap, seperti file PNG, gambar tidak diubah ukurannya. Jika Anda tidak menentukan ukuran dasar untuk ikon aplikasi berbasis vektor, seperti file SVG, dimensi yang ditentukan dalam gambar digunakan sebagai ukuran dasar. Untuk menghentikan perubahan ukuran gambar vektor, atur Resize atribut ke false.

Gambar berikut mengilustrasikan bagaimana ukuran dasar memengaruhi gambar:

Bagaimana ukuran dasar memengaruhi ikon aplikasi untuk .NET MAUI.

Proses yang ditunjukkan pada gambar sebelumnya mengikuti langkah-langkah berikut:

A: Gambar ditambahkan sebagai ikon MAUI .NET dan memiliki dimensi 210x260, dan ukuran dasar diatur ke 424x520.
B: .NET MAUI secara otomatis menskalakan gambar agar sesuai dengan ukuran dasar 424x520.
C: Karena platform target yang berbeda memerlukan ukuran gambar yang berbeda, .NET MAUI secara otomatis menskalakan gambar dari ukuran dasar ke ukuran yang berbeda.

Tip

Gunakan gambar SVG sebagai ikon Anda. Gambar SVG dapat meningkatkan skala ke ukuran yang lebih besar dan masih terlihat renyah dan bersih. Gambar berbasis bitmap, seperti gambar PNG atau JPG, terlihat buram saat ditingkatkan skalanya.

Ukuran dasar ditentukan dengan BaseSize="W,H" atribut , di mana W adalah lebar ikon dan H merupakan tinggi ikon. Contoh berikut mengatur ukuran dasar:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.png" BaseSize="128,128" />
</ItemGroup>

Dan contoh berikut menghentikan pengubahan ukuran otomatis gambar berbasis vektor:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" Resize="false" />
</ItemGroup>

Mewarnai ulang latar belakang

Jika gambar latar belakang yang digunakan dalam menyusun ikon aplikasi menggunakan transparansi, gambar tersebut dapat diwarnai ulang dengan menentukan Color atribut pada <MauiIcon>. Contoh berikut mengatur warna latar belakang ikon aplikasi menjadi merah:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" Color="#FF0000" />
</ItemGroup>

Nilai warna dapat ditentukan dalam heksadesimal, menggunakan format: #RRGGBB atau #AARRGGBB. Nilai RR mewakili saluran merah, GG saluran hijau, BB saluran biru, dan AA saluran alfa. Alih-alih nilai heksadesimal, Anda dapat menggunakan warna MAUI .NET bernama, seperti Red atau PaleVioletRed.

Perhatian

Jika Anda tidak menentukan warna latar belakang untuk ikon aplikasi, latar belakang dianggap tranparent di iOS dan Mac Catalyst. Ini akan menyebabkan kesalahan selama verifikasi App Store Connect dan Anda tidak akan dapat mengunggah aplikasi Anda.

Mewarnai ulang latar depan

Jika ikon aplikasi terdiri dari gambar latar belakang (Include) dan gambar latar depan (ForegroundFile), gambar latar depan dapat dicat. Untuk mewarnai gambar latar depan, tentukan warna dengan TintColor atribut . Contoh berikut membubuhkan gambar latar depan berwarna kuning:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="Yellow" />
</ItemGroup>

Menggunakan ikon yang berbeda per platform

Jika Anda ingin menggunakan sumber daya atau pengaturan ikon yang berbeda per platform, tambahkan Condition atribut ke <MauiIcon> item, dan kueri untuk platform tertentu. Jika kondisi terpenuhi, <MauiIcon> item akan diproses. Hanya item pertama yang valid <MauiIcon> yang digunakan oleh .NET MAUI, sehingga semua item bersyarat harus dideklarasikan terlebih dahulu, diikuti oleh item default <MauiIcon> tanpa kondisi. XML berikut menunjukkan deklarasikan ikon tertentu untuk Windows dan ikon fallback untuk semua platform lain:

<ItemGroup>
    <!-- App icon for Windows -->
    <MauiIcon Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'"
              Include="Resources\AppIcon\backicon.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="#40FF00FF" />

    <!-- App icon for all other platforms -->
    <MauiIcon Include="Resources\AppIcon\appicon.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="Yellow" />
</ItemGroup>

Anda dapat mengatur platform target dengan mengubah nilai dibandingkan dalam kondisi ke salah satu nilai berikut:

'ios'
'maccatalyst'
'android'
'windows'

Misalnya, kondisi yang menargetkan Android adalah Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'".

Konfigurasi khusus platform

Meskipun file proyek mendeklarasikan sumber daya mana tempat ikon aplikasi disusun, Anda masih diharuskan memperbarui konfigurasi platform individual dengan referensi ke ikon aplikasi tersebut. Informasi berikut menjelaskan pengaturan khusus platform ini.

Ikon yang digunakan Android ditentukan dalam manifes Android, yang terletak di Platforms\Android\AndroidManifest.xml. Simpul manifest/application berisi dua atribut untuk menentukan ikon: android:icon dan android:roundIcon. Nilai kedua atribut ini mengikuti format ini: @mipmap/{name} dan @mipmap/{name}_round, masing-masing. Nilai untuk {name} berasal dari item file <MauiIcon> proyek .NET MAUI, khususnya nama file yang ditentukan oleh Include atribut, tanpa jalur atau ekstensinya.

Pertimbangkan contoh berikut, yang mendefinisikan sumber daya Resources\AppIcon\healthapp.png sebagai ikon:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\healthapp.png" ForegroundFile="Resources\AppIcon\appiconfg.svg" TintColor="Yellow" />
</ItemGroup>

Nama yang diubah, sumber daya tanpa jalur atau ekstensi, adalah healthapp. Nilai untuk android:icon dan android:roundIcon akan dan @mipmap/healthapp@mipmap/healthapp_round, masing-masing. Manifes android harus diperbarui agar sesuai healthapp dengan ikon:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application android:allowBackup="true" android:icon="@mipmap/healthapp" android:roundIcon="@mipmap/healthapp_round" android:supportsRtl="true"></application>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Tip

Alih-alih membuat file gambar baru untuk ikon, cukup ganti dua file gambar yang disediakan oleh templat .NET MAUI: Resources\AppIcon\appicon.svg untuk latar belakang dan Resources\AppIcon\appiconfg.svg untuk latar depan.

Peluncur adaptif

.NET MAUI mendukung pembuatan ikon peluncur adaptif di Android 8.0 dan yang lebih tinggi, dari ikon aplikasi. Ikon peluncur adaptif dapat ditampilkan sebagai berbagai bentuk di berbagai model perangkat, termasuk melingkar dan persegi. Untuk informasi selengkapnya tentang ikon adaptif, lihat panduan pengembang Android: Ikon adaptif.

Ikon peluncur adaptif adalah ikon yang terdiri, menggunakan lapisan latar belakang dan lapisan latar depan, dan nilai penskalaan opsional. Untuk informasi selengkapnya, lihat bagian Ikon yang disusam. Jika ikon yang disusun ditentukan, dengan menentukan ForegroundFile atribut , ikon peluncur adaptif akan dihasilkan. XML berikut menunjukkan mendefinisikan ikon yang digunakan sebagai ikon peluncur adaptif:

<ItemGroup>
    <MauiIcon Include="Resources\AppIcon\appicon.svg" ForegroundFile="Resources\AppIcon\appiconfg.svg" ForegroundScale="0.65" Color="#512BD4" />
</ItemGroup>

Atribut ForegroundScale dapat ditentukan secara opsional untuk menskalakan ulang gambar latar depan sehingga sesuai dengan ikon aplikasi. Ini adalah nilai persentase sehingga 0,65 akan diterjemahkan sebagai 65%.

Ikon aplikasi yang ditentukan oleh aplikasi .NET MAUI Anda digunakan untuk menghasilkan ikon katalog aset yang diatur untuk platform iOS dan macOS. Nama set ikon ditentukan dalam file Info.plist , yang di iOS terletak di Platforms\iOS\Info.plist. Untuk macOS, file Info.plist terletak di Platforms\MacCatalyst\Info.plist.

Tip

Untuk mengedit file Info.plist secara manual di Visual Studio, klik kanan file di panel Penjelajah Solusi, dan pilih Buka Dengan.... Selanjutnya, pilih Editor XML (Teks) dan pilih OK. Jika tidak, klik dua kali file untuk membukanya di Editor Visual plist.

File Info.plist berisi <key>XSAppIconAssets</key> entri, dengan simpul yang <string> sesuai yang ditentukan setelahnya. Nilai simpul ini <string> mengikuti format ini: Assets.xcassets/{name}.appiconset Nilai untuk {name} berasal dari item file <MauiIcon> proyek .NET MAUI, khususnya nama file yang ditentukan oleh Include atribut, tanpa jalur atau ekstensinya.