Gambar dalam Xamarin.Forms

Gambar dapat dibagikan di seluruh platform dengan Xamarin.Forms, mereka dapat dimuat khusus untuk setiap platform, atau dapat diunduh untuk ditampilkan.

Gambar adalah bagian penting dari navigasi aplikasi, kegunaan, dan branding. Xamarin.Forms aplikasi harus dapat berbagi gambar di semua platform, tetapi juga berpotensi menampilkan gambar yang berbeda di setiap platform.

Gambar khusus platform juga diperlukan untuk ikon dan layar percikan; ini perlu dikonfigurasi berdasarkan per platform.

Menampilkan gambar

Xamarin.FormsImage menggunakan tampilan untuk menampilkan gambar pada halaman. Ini memiliki beberapa properti penting:

• Source - Instans ImageSource , baik File, Uri, atau Sumber Daya, yang mengatur gambar untuk ditampilkan.
• Aspect - Cara mengukur gambar dalam batas yang ditampilkan di dalamnya (apakah akan meregangkan, memotong, atau kotak surat).

ImageSource instans dapat diperoleh menggunakan metode statis untuk setiap jenis sumber gambar:

• FromFile - Memerlukan nama file atau jalur file yang dapat diselesaikan di setiap platform.
• FromUri - Membutuhkan objek Uri, misalnya. new Uri("http://server.com/image.jpg") .
• FromResource - Memerlukan pengidentifikasi sumber daya ke file gambar yang disematkan dalam aplikasi atau proyek pustaka .NET Standard, dengan Build Action:EmbeddedResource.
• FromStream - Memerlukan aliran yang menyediakan data gambar.

Properti Aspect menentukan bagaimana gambar akan diskalakan agar sesuai dengan area tampilan:

• Fill - Membentangkan gambar untuk mengisi area tampilan sepenuhnya dan tepat. Ini dapat mengakibatkan gambar terdistorsi.
• AspectFill - Mengklip gambar sehingga mengisi area tampilan sambil mempertahankan aspek (yaitu tidak ada distorsi).
• AspectFit - Kotak surat gambar (jika diperlukan) sehingga seluruh gambar cocok dengan area tampilan, dengan ruang kosong ditambahkan ke atas/bawah atau samping tergantung pada apakah gambar lebar atau tinggi.

Gambar dapat dimuat dari file lokal, sumber daya yang disematkan, diunduh, atau dimuat dari aliran. Selain itu, ikon font dapat ditampilkan oleh Image tampilan dengan menentukan data ikon font dalam FontImageSource objek. Untuk informasi selengkapnya, lihat Menampilkan ikon font di panduan Font .

Gambar lokal

File gambar dapat ditambahkan ke setiap proyek aplikasi dan dirujuk dari Xamarin.Forms kode bersama. Metode mendistribusikan gambar ini diperlukan ketika gambar khusus platform, seperti saat menggunakan resolusi yang berbeda pada platform yang berbeda, atau desain yang sedikit berbeda.

Untuk menggunakan satu gambar di semua aplikasi, nama file yang sama harus digunakan pada setiap platform, dan harus berupa nama sumber daya Android yang valid (yaitu hanya huruf kecil, angka, garis bawah, dan periode yang diizinkan).

• iOS - Cara yang disukai untuk mengelola dan mendukung gambar karena iOS 9 adalah dengan menggunakan Set Gambar Katalog Aset, yang harus berisi semua versi gambar yang diperlukan untuk mendukung berbagai perangkat dan faktor skala untuk aplikasi. Untuk informasi selengkapnya, lihat Menambahkan Gambar ke Kumpulan Gambar Katalog Aset.
• Android - Tempatkan gambar di direktori Resources/drawable dengan Build Action: AndroidResource. Versi gambar dengan DPI tinggi dan rendah juga dapat disediakan (dengan nama yang tepat subdirektori Sumber Daya seperti drawable-ldpi, drawable-hdpi, dan drawable-xhdpi).
• Platform Windows Universal (UWP) - Secara default, gambar harus ditempatkan di direktori akar aplikasi dengan Tindakan Build: Konten. Atau, gambar dapat ditempatkan di direktori yang berbeda yang kemudian ditentukan dengan khusus platform. Untuk informasi selengkapnya, lihat Direktori gambar default di Windows.

Penting

Sebelum iOS 9, gambar biasanya ditempatkan di folder Sumber Daya dengan Build Action: BundleResource. Namun, metode bekerja dengan gambar di aplikasi iOS ini telah ditolak oleh Apple. Untuk informasi selengkapnya, lihat Ukuran Gambar dan Nama File.

Mematuhi aturan ini untuk penamaan dan penempatan file memungkinkan XAML berikut untuk memuat dan menampilkan gambar di semua platform:

<Image Source="waterfront.jpg" />

Kode C# yang setara adalah sebagai berikut:

var image = new Image { Source = "waterfront.jpg" };

Cuplikan layar berikut menunjukkan hasil menampilkan gambar lokal di setiap platform:

Untuk fleksibilitas lebih lanjut Device.RuntimePlatform , properti dapat digunakan untuk memilih file gambar atau jalur yang berbeda untuk beberapa atau semua platform, seperti yang ditunjukkan dalam contoh kode ini:

image.Source = Device.RuntimePlatform == Device.Android
                ? ImageSource.FromFile("waterfront.jpg")
                : ImageSource.FromFile("Images/waterfront.jpg");

Penting

Untuk menggunakan nama file gambar yang sama di semua platform, nama harus valid di semua platform. Android drawable memiliki batasan penamaan - hanya huruf kecil, angka, garis bawah, dan periode yang diizinkan - dan untuk kompatibilitas lintas platform ini harus diikuti pada semua platform lain juga. Contoh nama file waterfront.png mengikuti aturan, tetapi contoh nama file yang tidak valid termasuk "front.png air", "WaterFront.png", "water-front.png", dan "wåterfront.png".

Resolusi asli (retina dan DPI tinggi)

iOS, Android, dan UWP mencakup dukungan untuk resolusi gambar yang berbeda, di mana sistem operasi memilih gambar yang sesuai saat runtime berdasarkan kemampuan perangkat. Xamarin.Forms menggunakan API platform asli untuk memuat gambar lokal, sehingga secara otomatis mendukung resolusi alternatif jika file dinamai dengan benar dan terletak di proyek.

Cara yang disukai untuk mengelola gambar karena iOS 9 adalah dengan menyeret gambar untuk setiap resolusi yang diperlukan ke kumpulan gambar katalog aset yang sesuai. Untuk informasi selengkapnya, lihat Menambahkan Gambar ke Kumpulan Gambar Katalog Aset.

Sebelum iOS 9, versi retina gambar dapat ditempatkan di folder Sumber Daya - dua dan tiga kali resolusi dengan akhiran @2x atau @3x pada nama file sebelum ekstensi file (misalnya. myimage@2x.png). Namun, metode bekerja dengan gambar di aplikasi iOS ini telah ditolak oleh Apple. Untuk informasi selengkapnya, lihat Ukuran Gambar dan Nama File.

Gambar resolusi alternatif Android harus ditempatkan di direktori bernama khusus di proyek Android, seperti yang ditunjukkan pada cuplikan layar berikut:

Nama file gambar UWP dapat diakhiri dengan .scale-xxx sebelum ekstensi file, di mana xxx persentase penskalaan diterapkan ke aset, misalnya myimage.scale-200.png. Gambar kemudian dapat dirujuk dalam kode atau XAML tanpa pengubah skala, misalnya hanya myimage.png. Platform akan memilih skala aset terdekat yang sesuai berdasarkan DPI tampilan saat ini.

Kontrol tambahan yang menampilkan gambar

Beberapa kontrol memiliki properti yang menampilkan gambar, seperti:

• Button memiliki ImageSource properti yang dapat diatur ke gambar bitmap untuk ditampilkan pada Button. Untuk informasi selengkapnya, lihat Menggunakan bitmap dengan tombol.

• ImageButton memiliki Source properti yang dapat diatur ke gambar untuk ditampilkan di ImageButton. Untuk informasi selengkapnya, lihat Mengatur sumber gambar.

• ToolbarItem memiliki IconImageSource properti yang dapat diatur ke gambar yang dimuat dari file, sumber daya tersemat, URI, atau aliran.

• ImageCell memiliki ImageSource properti yang dapat diatur ke gambar yang diambil dari file, sumber daya, URI, atau aliran yang disematkan.

• Page. Jenis halaman apa pun yang berasal dari Page memiliki IconImageSource dan BackgroundImageSource properti, yang dapat ditetapkan file, sumber daya tersemat, URI, atau aliran. Dalam keadaan tertentu, seperti ketika menampilkan NavigationPageContentPage, ikon akan ditampilkan jika didukung oleh platform.

  Penting

  Di iOS, Page.IconImageSource properti tidak dapat diisi dari gambar dalam kumpulan gambar katalog aset. Sebagai gantinya Page.IconImageSource , muat gambar ikon untuk properti dari file, sumber daya tersemat, URI, atau streaming.

Gambar yang disematkan

Gambar yang disematkan juga dikirim dengan aplikasi (seperti gambar lokal) tetapi alih-alih memiliki salinan gambar dalam struktur file setiap aplikasi, file gambar disematkan dalam rakitan sebagai sumber daya. Metode mendistribusikan gambar ini direkomendasikan ketika gambar identik digunakan pada setiap platform, dan sangat cocok untuk membuat komponen, karena gambar dibundel dengan kode.

Untuk menyematkan gambar dalam proyek, klik kanan untuk menambahkan item baru dan pilih gambar yang ingin Anda tambahkan. Secara default gambar akan memiliki Tindakan Build: Tidak Ada; ini perlu diatur ke Build Action: EmbeddedResource.

Visual Studio

Tindakan Build dapat dilihat dan diubah di jendela Properti untuk file.

Dalam contoh ini ID sumber daya WorkingWithImages.beach.jpg. IDE telah menghasilkan default ini dengan menggabungkan Namespace Default untuk proyek ini dengan nama file, menggunakan titik (.) di antara setiap nilai.

Visual Studio untuk Mac

Tindakan Build juga dapat dilihat dan diubah di pad Properti untuk file. Pad ini menunjukkan ID Sumber Daya yang digunakan untuk mereferensikan sumber daya dalam kode. Pada cuplikan layar di bawah ini, ID Sumber Daya WorkingWithImages.beach.jpg. IDE telah menghasilkan default ini dengan menggabungkan Namespace Default untuk proyek ini dengan nama file, menggunakan titik (.) di antara setiap nilai. ID ini dapat diedit di pad Properti , tetapi untuk contoh ini nilai WorkingWithImages.beach.jpg akan digunakan.

Jika Anda menempatkan gambar yang disematkan ke dalam folder dalam proyek Anda, nama folder juga dipisahkan oleh titik (.) dalam ID sumber daya. Memindahkan gambar beach.jpg ke dalam folder bernama MyImages akan menghasilkan ID sumber daya WorkingWithImages.MyImages.beach.jpg

Kode untuk memuat gambar yang disematkan hanya meneruskan ID Sumber Daya ke metode seperti yang ditunjukkan ImageSource.FromResource di bawah ini:

Image embeddedImage = new Image
{
    Source = ImageSource.FromResource("WorkingWithImages.beach.jpg", typeof(MyClass).GetTypeInfo().Assembly)
};

Catatan

Untuk mendukung menampilkan gambar yang disematkan dalam mode rilis pada Platform Windows Universal, perlu menggunakan kelebihan beban ImageSource.FromResource yang menentukan assembly sumber untuk mencari gambar.

Saat ini tidak ada konversi implisit untuk pengidentifikasi sumber daya. Sebagai gantinya, Anda harus menggunakan ImageSource.FromResource atau new ResourceImageSource() memuat gambar yang disematkan.

Cuplikan layar berikut menunjukkan hasil menampilkan gambar yang disematkan di setiap platform:

XAML

Karena tidak ada pengonversi jenis bawaan dari string ke ResourceImageSource, jenis gambar ini tidak dapat dimuat secara asli oleh XAML. Sebagai gantinya, ekstensi markup XAML kustom sederhana dapat ditulis untuk memuat gambar menggunakan ID Sumber Daya yang ditentukan dalam XAML:

[ContentProperty (nameof(Source))]
public class ImageResourceExtension : IMarkupExtension
{
 public string Source { get; set; }

 public object ProvideValue (IServiceProvider serviceProvider)
 {
   if (Source == null)
   {
     return null;
   }

   // Do your translation lookup here, using whatever method you require
   var imageSource = ImageSource.FromResource(Source, typeof(ImageResourceExtension).GetTypeInfo().Assembly);

   return imageSource;
 }
}

Catatan

Untuk mendukung menampilkan gambar yang disematkan dalam mode rilis pada Platform Windows Universal, perlu menggunakan kelebihan beban ImageSource.FromResource yang menentukan assembly sumber untuk mencari gambar.

Untuk menggunakan ekstensi ini, tambahkan kustom xmlns ke XAML, menggunakan namespace dan nilai assembly yang benar untuk proyek. Sumber gambar kemudian dapat diatur menggunakan sintaks ini: {local:ImageResource WorkingWithImages.beach.jpg}. Contoh XAML lengkap ditunjukkan di bawah ini:

<?xml version="1.0" encoding="UTF-8" ?>
<ContentPage
   xmlns="http://xamarin.com/schemas/2014/forms"
   xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
   xmlns:local="clr-namespace:WorkingWithImages;assembly=WorkingWithImages"
   x:Class="WorkingWithImages.EmbeddedImagesXaml">
 <StackLayout VerticalOptions="Center" HorizontalOptions="Center">
   <!-- use a custom Markup Extension -->
   <Image Source="{local:ImageResource WorkingWithImages.beach.jpg}" />
 </StackLayout>
</ContentPage>

Memecahkan masalah gambar yang disematkan

Men-debug kode

Karena terkadang sulit untuk memahami mengapa sumber daya gambar tertentu tidak dimuat, kode debug berikut dapat ditambahkan sementara ke aplikasi untuk membantu mengonfirmasi bahwa sumber daya dikonfigurasi dengan benar. Ini akan menghasilkan semua sumber daya yang diketahui yang disematkan dalam rakitan yang diberikan ke Konsol untuk membantu men-debug masalah pemuatan sumber daya.

using System.Reflection;
// ...
// NOTE: use for debugging, not in released app code!
var assembly = typeof(MyClass).GetTypeInfo().Assembly;
foreach (var res in assembly.GetManifestResourceNames())
{
    System.Diagnostics.Debug.WriteLine("found resource: " + res);
}

Gambar yang disematkan dalam proyek lain

Secara default, ImageSource.FromResource metode ini hanya mencari gambar dalam rakitan yang sama dengan kode yang memanggil ImageSource.FromResource metode . Dengan menggunakan kode debug di atas, Anda dapat menentukan rakitan mana yang berisi sumber daya tertentu dengan mengubah typeof() pernyataan menjadi yang Type diketahui berada di setiap rakitan.

Namun, rakitan sumber yang sedang dicari untuk gambar yang disematkan dapat ditentukan sebagai argumen ke ImageSource.FromResource metode :

var imageSource = ImageSource.FromResource("filename.png",
            typeof(MyClass).GetTypeInfo().Assembly);

Unduh gambar

Gambar dapat diunduh secara otomatis untuk ditampilkan, seperti yang ditunjukkan pada XAML berikut:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       x:Class="WorkingWithImages.DownloadImagesXaml">
  <StackLayout VerticalOptions="Center" HorizontalOptions="Center">
    <Label Text="Image UriSource Xaml" />
    <Image Source="https://aka.ms/campus.jpg" />
    <Label Text="campus.jpg gets downloaded from microsoft.com" />
  </StackLayout>
</ContentPage>

Kode C# yang setara adalah sebagai berikut:

var webImage = new Image {
     Source = ImageSource.FromUri(
        new Uri("https://aka.ms/campus.jpg")
     ) };

Metode ini ImageSource.FromUri memerlukan Uri objek, dan mengembalikan baru UriImageSource yang berbunyi dari Uri.

Ada juga konversi implisit untuk string URI, sehingga contoh berikut juga akan berfungsi:

webImage.Source = "https://aka.ms/campus.jpg";

Cuplikan layar berikut menunjukkan hasil menampilkan gambar jarak jauh di setiap platform:

Penembolokan gambar yang diunduh

A UriImageSource juga mendukung penembolokan gambar yang diunduh, dikonfigurasi melalui properti berikut:

• CachingEnabled - Apakah penembolokan diaktifkan (true secara default).
• CacheValidity - Yang TimeSpan mendefinisikan berapa lama gambar akan disimpan secara lokal.

Penembolokan diaktifkan secara default dan akan menyimpan gambar secara lokal selama 24 jam. Untuk menonaktifkan penembolokan untuk gambar tertentu, buat instans sumber gambar sebagai berikut:

image.Source = new UriImageSource { CachingEnabled = false, Uri = new Uri("https://server.com/image") };

Untuk mengatur periode cache tertentu (misalnya, 5 hari) buat sumber gambar sebagai berikut:

webImage.Source = new UriImageSource
{
    Uri = new Uri("https://aka.ms/campus.jpg"),
    CachingEnabled = true,
    CacheValidity = new TimeSpan(5,0,0,0)
};

Penembolokan bawaan membuatnya sangat mudah untuk mendukung skenario seperti menggulir daftar gambar, di mana Anda dapat mengatur (atau mengikat) gambar di setiap sel dan membiarkan cache bawaan mengurus pemuatan ulang gambar saat sel digulir kembali ke tampilan.

GIF animasi

Xamarin.Forms termasuk dukungan untuk menampilkan GIF kecil dan animasi. Ini dicapai dengan mengatur Image.Source properti ke file GIF animasi:

<Image Source="demo.gif" />

Penting

Meskipun dukungan GIF animasi termasuk Xamarin.Forms kemampuan untuk mengunduh file, itu tidak mendukung penembolokan atau streaming ANIMASI GIF.

Secara default, ketika GIF animasi dimuat, GIF tidak akan diputar. Ini karena IsAnimationPlaying properti , yang mengontrol apakah GIF animasi diputar atau dihentikan, memiliki nilai falsedefault . Properti ini, dari jenis bool, didukung oleh BindableProperty objek, yang berarti bahwa itu bisa menjadi target pengikatan data, dan ditata.

Oleh karena itu, ketika GIF animasi dimuat, GIF tidak akan diputar sampai IsAnimationPlaying properti diatur ke true. Pemutaran kemudian dapat dihentikan dengan mengatur properti ke IsAnimationPlayingfalse. Perhatikan bahwa properti ini tidak berpengaruh saat menampilkan sumber gambar non-GIF.

Catatan

Di Android, dukungan GIF animasi mengharuskan aplikasi Anda menggunakan perender cepat, dan tidak akan berfungsi jika Anda memilih menggunakan perender warisan. Pada UWP, dukungan GIF animasi memerlukan rilis minimum Windows 10 Anniversary Update (versi 1607).

Ikon dan layar percikan

Meskipun tidak terkait dengan Image tampilan, ikon aplikasi dan layar percikan juga merupakan penggunaan gambar yang penting dalam Xamarin.Forms proyek.

Mengatur ikon dan layar splash untuk Xamarin.Forms aplikasi dilakukan di setiap proyek aplikasi. Ini berarti menghasilkan gambar berukuran benar untuk iOS, Android, dan UWP. Gambar-gambar ini harus diberi nama dan terletak sesuai dengan persyaratan setiap platform.

Ikon

Lihat Panduan iOS Bekerja dengan Gambar, Ikonografi Google, dan UWP untuk petak peta dan aset ikon untuk informasi selengkapnya tentang membuat sumber daya aplikasi ini.

Selain itu, ikon font dapat ditampilkan oleh Image tampilan dengan menentukan data ikon font dalam FontImageSource objek. Untuk informasi selengkapnya, lihat Menampilkan ikon font di panduan Font .

Layar splash

Hanya aplikasi iOS dan UWP yang memerlukan layar percikan (juga disebut layar startup atau gambar default).

Lihat dokumentasi untuk iOS Bekerja dengan gambar dan layar Splash di Windows Dev Center.

Tautan terkait

• iOS Bekerja dengan Gambar
• Ikonografi Android
• Panduan untuk petak peta dan aset ikon