Ringkasan sumber daya aplikasi

Resource adalah file tambahan dan konten statis yang digunakan kode Anda, seperti bitmap, string antarmuka pengguna, instruksi animasi, dan banyak lagi.

Selalu eksternalkan resource aplikasi seperti gambar dan string dari kode agar Anda dapat mengelolanya secara independen. Selain itu, sediakan resource alternatif untuk konfigurasi perangkat tertentu dengan mengelompokkannya dalam direktori resource yang diberi nama khusus. Saat runtime, Android menggunakan resource yang sesuai berdasarkan konfigurasi saat ini. Misalnya, Anda mungkin ingin memberikan string yang berbeda bergantung pada setelan bahasa.

Setelah mengeksternalkan resource aplikasi, Anda dapat mengaksesnya menggunakan ID resource yang dibuat dalam class R project Anda. Dokumen ini menunjukkan cara mengelompokkan resource dalam project Android Anda. Bagian ini juga menunjukkan cara menyediakan resource alternatif untuk konfigurasi perangkat tertentu, lalu mengaksesnya dari kode aplikasi Anda atau file XML lainnya.

Jenis resource grup

Tempatkan setiap jenis resource di subdirektori tertentu dari direktori res/ project Anda. Misalnya, berikut hierarki file untuk project sederhana:

MyProject/
    src/
        MyActivity.kt
    res/
        drawable/
            graphic.png
        mipmap/
            icon.png
        values/
            strings.xml

Direktori res/ berisi semua resource dalam subdirektorinya: resource gambar, direktori mipmap/ untuk ikon peluncur, dan file resource string. Nama direktori resource penting dan dijelaskan dalam Tabel 1.

Catatan: Untuk informasi selengkapnya tentang penggunaan folder mipmap, lihat Menempatkan ikon aplikasi di direktori mipmap.

Tabel 1. Direktori resource didukung dalam direktori res/ proyek.

Perhatian: Jangan pernah menyimpan file resource langsung di dalam direktori res/ karena akan menyebabkan error compiler.

Resource yang Anda simpan di subdirektori yang ditentukan dalam Tabel 1 adalah resource default Anda. Artinya, resource ini menentukan desain dan konten default untuk aplikasi Anda. Namun, berbagai jenis perangkat Android mungkin memerlukan jenis resource yang berbeda.

Misalnya, Anda dapat menyediakan berbagai resource string yang menerjemahkan teks di antarmuka pengguna berdasarkan setelan bahasa perangkat.

Catatan: Di Compose, UI, animasi, dan warna yang didorong status dideklarasikan di Kotlin, sehingga direktori layout/, menu/, anim/, animator/, dan color/ tidak digunakan lagi untuk aplikasi modern. Untuk mengetahui informasi selengkapnya, lihat Animasi di Compose dan Anatomi tema di Compose.

Menyediakan resource alternatif

Sebagian besar aplikasi menyediakan resource alternatif untuk mendukung konfigurasi perangkat tertentu. Misalnya, sertakan resource drawable alternatif untuk kepadatan layar yang berbeda dan resource string alternatif untuk bahasa yang berbeda. Saat runtime, Android akan mendeteksi konfigurasi perangkat aktif dan memuat resource yang sesuai untuk aplikasi Anda.

Agar dapat menyebutkan alternatif konfigurasi tertentu untuk satu set resource, lakukan langkah berikut:

1. Buat direktori baru dalam res/ yang dinamai dalam formulir <resources_name>-<qualifier>.
   • <resources_name> adalah nama direktori resource default terkait (yang didefinisikan dalam Tabel 1).
   • <qualifier> adalah nama yang menentukan setiap konfigurasi yang akan digunakan resource ini (didefinisikan dalam Tabel 2).

   Anda bisa menambahkan lebih dari satu <qualifier>. Pisahkan masing-masing dengan tanda hubung.

   Perhatian: Saat menambahkan beberapa penentu, Anda harus menempatkannya dalam urutan yang sama dengan yang tercantum dalam Tabel 2. Jika penentu diurutkan dengan salah, resource akan diabaikan.

2. Simpan resource alternatif masing-masing dalam direktori baru ini. File resource harus dinamai sama persis dengan file resource default.

Misalnya, berikut ini beberapa resource default dan resource alternatif:

res/
    drawable/
        icon.png
        background.png
    drawable-hdpi/
        icon.png
        background.png

Penentu hdpi menunjukkan bahwa resource dalam direktori itu diperuntukkan bagi perangkat dengan layar berkepadatan tinggi. Gambar dalam direktori drawable memiliki ukuran untuk kepadatan layar tertentu, tetapi nama filenya persis sama. Dengan demikian, ID resource yang Anda gunakan untuk mereferensikan gambar icon.png atau background.png akan selalu sama. Android memilih versi setiap resource yang paling cocok dengan perangkat saat ini dengan membandingkan informasi konfigurasi perangkat dengan penentu dalam nama direktori resource.

Perhatian: Saat menentukan resource alternatif, pastikan Anda juga menentukan resource dalam konfigurasi default. Jika tidak, aplikasi Anda mungkin akan mengalami pengecualian runtime saat perangkat mengubah konfigurasi. Misalnya, jika Anda menambahkan string hanya ke values-en, bukan values, aplikasi Anda mungkin mengalami pengecualian Resource Not Found saat pengguna mengubah bahasa sistem default.

Tabel 2 mencantumkan penentu kualitas konfigurasi sesuai urutan prioritas. Anda dapat menambahkan beberapa penentu ke satu nama direktori dengan memisahkan setiap penentu dengan tanda hubung. Jika menggunakan beberapa penentu untuk direktori resource, Anda harus menambahkannya ke nama direktori sesuai urutan yang tercantum dalam tabel.

Tabel 2. Nama-nama pengontrol kualitas konfigurasi.

Catatan: Penentu hanya didukung oleh versi Android tertentu. Menggunakan penentu baru secara implisit akan menambahkan penentu versi platform sehingga perangkat lama dapat mengabaikannya. Untuk menghindari masalah, selalu sertakan satu set resource default (satu set resource tanpa penentu). Untuk mengetahui informasi selengkapnya, lihat bagian tentang menyediakan kompatibilitas perangkat terbaik dengan resource.

Di aplikasi Compose, penentu konfigurasi terkait tata letak dan dimensi tidak diperlukan. Meskipun masih ada, data tersebut dikecualikan dari Tabel 2. Penentu ini mencakup: arah tata letak, lebar terkecil, lebar yang tersedia, tinggi yang tersedia, ukuran layar, aspek layar, layar bulat, dan orientasi layar. Untuk tabel lengkap pengontrol kualitas konfigurasi dalam urutan prioritas, lihat Ringkasan resource aplikasi (Tampilan).

Aturan penamaan penentu

Berikut ini beberapa aturan tentang penggunaan nama pengontrol kualitas konfigurasi:

• Anda dapat menetapkan beberapa penentu untuk satu set resource, yang dipisahkan dengan tanda hubung. Misalnya, drawable-en-rUS-night berlaku untuk perangkat bahasa Inggris-AS dalam mode malam.
• Penentu harus dalam urutan seperti yang tercantum dalam Tabel 2.
  • Salah: drawable-hdpi-night/
  • Benar: drawable-night-hdpi/
• Direktori resource alternatif tidak dapat disusun bertingkat. Misalnya, Anda tidak bisa memiliki res/drawable/drawable-en/.
• Nilai tidak peka huruf besar/kecil. Compiler resource mengubah nama direktori menjadi huruf kecil sebelum pemrosesan untuk menghindari masalah pada sistem file yang tidak peka huruf besar/kecil. Setiap penggunaan huruf besar dalam nama hanyalah demi keterbacaan.
• Hanya mendukung satu nilai untuk setiap jenis penentu. Misalnya, jika Anda ingin menggunakan file drawable yang sama dengan bahasa Spanyol dan Prancis, Anda tidak bisa memiliki direktori yang bernama drawable-es-fr/. Sebagai gantinya, Anda memerlukan dua direktori resource, seperti drawable-es/ dan drawable-fr/, yang berisi file yang sesuai.

Setelah Anda menyimpan resource alternatif ke dalam direktori yang diberi nama dengan penentu ini, Android secara otomatis menerapkan resource dalam aplikasi Anda berdasarkan pada konfigurasi perangkat saat ini. Setiap kali resource diminta, Android akan memeriksa direktori resource alternatif berisi file resource yang diminta, lalu mencari resource yang paling cocok.

Jika tidak ada resource alternatif yang cocok dengan konfigurasi perangkat tertentu, Android akan menggunakan resource default terkait—set resource untuk jenis resource tertentu yang tidak termasuk pengontrol kualitas konfigurasi.

Membuat resource alias

Jika memiliki resource yang ingin Anda gunakan untuk lebih dari satu konfigurasi perangkat, tetapi tidak ingin menyediakannya sebagai resource default, Anda tidak harus menempatkan resource yang sama di lebih dari satu direktori resource alternatif. Sebagai gantinya, Anda dapat membuat resource alternatif yang berfungsi sebagai alias untuk resource yang disimpan dalam direktori resource default.

Drawable

Misalnya, bayangkan Anda memiliki ikon aplikasi, icon.png, dan membutuhkan versi unik untuk lokal berbeda. Akan tetapi, dua lokalitas, bahasa Inggris-Kanada dan bahasa Prancis-Kanada, harus menggunakan versi yang sama. Anda tidak perlu menyalin gambar yang sama ke dalam direktori resource baik untuk bahasa Inggris-Kanada maupun bahasa Prancis-Kanada. Sebagai gantinya, Anda bisa menyimpan gambar yang sama-sama menggunakan nama apa punselain icon.png, misalnya icon_ca.png, dan menempatkannya di direktori res/drawable/ default. Kemudian, buat file icon.xml di res/drawable-en-rCA/ dan res/drawable-fr-rCA/ yang merujuk ke resource icon_ca.png menggunakan elemen <bitmap>.

<?xml version="1.0" encoding="utf-8"?>
<bitmap xmlns:android="http://schemas.android.com/apk/res/android" android:src="@drawable/icon_ca" />

Dengan membuat file ini, Anda dapat menyimpan satu versi saja dari file PNG dan dua file XML kecil yang mengarah ke resource tersebut. Kemudian, Anda dapat menggunakan painterResource(R.drawable.icon) dan sistem akan memilih file yang sesuai setelah mendeteksi lokalitas.

String dan nilai sederhana lainnya

Untuk membuat alias ke string yang ada, gunakan ID resource dari string yang diinginkan sebagai nilai untuk string baru:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello</string>
    <string name="hi">@string/hello</string>
</resources>

Resource R.string.hi sekarang merupakan alias untuk R.string.hello.

Nilai sederhana lainnya memiliki cara kerja yang sama, misalnya warna:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="red">#f00</color>
    <color name="highlight">@color/red</color>
</resources>

Mengakses resource aplikasi

Setelah menyediakan resource dalam aplikasi, Anda dapat menerapkannya dengan mereferensikan ID resource-nya. Semua ID resource didefinisikan di class R project Anda, yang dihasilkan otomatis oleh fitur aapt.

Jika aplikasi Anda telah dikompilasi, aapt akan menghasilkan class R, yang berisi ID resource untuk semua resource dalam direktori res/. Untuk setiap jenis resource, ada subclass R, seperti R.drawable untuk semua resource drawable. Selain itu juga, untuk setiap resource jenis tersebut, terdapat bilangan bulat statis, misalnya, R.drawable.icon. Bilangan bulat ini adalah ID resource yang bisa Anda gunakan untuk mengambil resource.

Meskipun class R merupakan tempat menetapkan ID resource, Anda tidak perlu melihat ke sana untuk menemukan ID resource. ID resource selalu terdiri dari hal berikut:

• Jenis resource: setiap resource dikelompokkan ke dalam "jenis", seperti string atau drawable.
• Nama resource, yang merupakan nama file tanpa ekstensi.

Mengakses resource di Compose

Jetpack Compose menyediakan fungsi bawaan yang kompatibel dengan composable untuk mengakses resource secara aman.

• String:

  stringResource(id = R.string.hello)

• Drawable:

  painterResource(id = R.drawable.my_icon)

Mengakses resource dalam kode non-UI

Jika Anda perlu mengakses resource di luar hierarki UI—seperti di ViewModel, Repository, atau Service sistem—Anda dapat menyelesaikannya menggunakan Context.

// Retrieve a localized string resource
val greeting = context.getString(R.string.hello_world)

Anda juga dapat mengambil tiap resource dengan menggunakan berbagai metode di Resources. Di sini, Anda bisa mendapatkan instance dengan getResources.

Sintaksis

Inilah sintaksis untuk mereferensikan resource dalam kode:

[<package_name>.]R.<resource_type>.<resource_name>

• <package_name> adalah nama paket yang di dalamnya terdapat resource (tidak dibutuhkan bila mereferensikan resource dari paket Anda sendiri).
• <resource_type> adalah subclass R untuk jenis resource.
• <resource_name> dapat berupa nama file resource tanpa ekstensi atau nilai atribut android:name dalam elemen XML untuk nilai sederhana.

Untuk mengetahui informasi selengkapnya tentang setiap jenis resource dan cara mereferensikannya, lihat Resource dalam Compose.

Mengakses file asli

Walaupun tidak lazim, Anda mungkin perlu mengakses file dan direktori asli. Jika demikian, penyimpanan file di res/ tidak akan berhasil, karena satu-satunya cara untuk membaca resource dari res/ adalah dengan ID resource. Sebagai gantinya, Anda dapat menyimpan resource dalam direktori assets/.

File yang disimpan di direktori assets/ tidak diberi ID resource, sehingga Anda tidak bisa mereferensikannya melalui class R atau dari resource XML. Sebagai gantinya, Anda bisa melakukan kueri file di direktori assets/ seperti sebuah sistem file biasa dan membaca data mentah dengan menggunakan AssetManager.

Namun, jika yang Anda butuhkan hanya kemampuan membaca data mentah (misalnya sebuah file video atau audio), maka simpanlah file itu di direktori res/raw/ dan baca stream byte dengan menggunakan openRawResource.

Mengakses resource platform

Android berisi sejumlah resource standar, seperti gaya dan tema sistem. Untuk mengaksesnya, tetapkan referensi resource Anda dengan class paket android. Misalnya: painterResource(android.R.drawable.ic_menu_info_details).

Menyediakan kompatibilitas perangkat terbaik dengan resource

Agar aplikasi Anda dapat mendukung beberapa konfigurasi perangkat, Anda harus selalu menyediakan resource default untuk setiap jenis resource yang digunakan aplikasi Anda.

Misalnya, jika aplikasi Anda mendukung beberapa bahasa, selalu sertakan direktori values/ (tempat string Anda disimpan) tanpa penentu bahasa dan wilayah. Jika Anda justru menempatkan semua file string dalam direktori yang memiliki penentu bahasa dan wilayah, aplikasi Anda akan error saat berjalan pada perangkat yang telah diatur ke bahasa yang tidak didukung string Anda.

Selama Anda menyediakan resource values/ default, aplikasi akan berjalan dengan baik sekalipun pengguna tidak memahami bahasa yang disajikan. Lebih baik daripada error.

Resource default perlu disediakan bukan hanya karena aplikasi mungkin berjalan pada konfigurasi yang belum Anda antisipasi, namun juga karena versi baru Android terkadang menambahkan pengontrol kualitas konfigurasi yang tidak didukung oleh versi lama. Jika Anda menggunakan penentu resource baru, tetapi mempertahankan kompatibilitas kode dengan versi Android yang lebih rendah, maka saat versi Android yang lebih rendah menjalankan aplikasi, aplikasi akan error jika Anda tidak menyediakan resource default karena aplikasi tidak dapat menggunakan resource yang dinamai dengan penentu baru.

Misalnya, jika minSdkVersion disetel ke 4, dan Anda memenuhi syarat semua resource drawable menggunakan mode malam (night atau notnight, yang ditambahkan di level API 8), perangkat level API 4 tidak dapat mengakses resource drawable dan akan error. Dalam hal ini, Anda mungkin ingin notnight menjadi resource default. Oleh karena itu, kecualikan penentu itu dan tempatkan resource drawable dalam drawable/ atau drawable-night/.

Singkatnya, agar bisa menyediakan kompatibilitas perangkat terbaik, selalu sediakan resource default untuk resource yang diperlukan aplikasi Anda supaya berjalan dengan benar. Selanjutnya buatlah resource alternatif untuk konfigurasi perangkat tertentu dengan menggunakan pengontrol kualitas konfigurasi.

Ada satu pengecualian untuk aturan ini: Jika minSdkVersion aplikasi Anda berukuran 4 atau lebih besar, Anda tidak memerlukan resource drawable default saat menyediakan resource drawable alternatif dengan penentu kepadatan layar. Tanpa resource drawable default sekali pun, Android dapat menemukan yang paling cocok di antara kepadatan layar alternatif dan menskalakan bitmap sesuai kebutuhan. Akan tetapi, demi pengalaman terbaik pada semua jenis perangkat, sediakan drawable alternatif untuk ketiga jenis kepadatan.

Cara Android menemukan resource yang paling cocok

Saat Anda meminta resource yang Anda berikan alternatifnya, Android akan memilih resource alternatif yang akan digunakan saat runtime, bergantung pada konfigurasi perangkat saat ini. Untuk mendemonstrasikan cara Android memilih resource alternatif, anggaplah direktori drawable berikut masing-masing berisi versi berbeda dari gambar yang sama:

drawable/
drawable-en/
drawable-fr-rCA/
drawable-en-night/
drawable-en-notouch-12key/
drawable-night-ldpi/
drawable-night-notouch-12key/

Dan anggaplah yang berikut ini merupakan konfigurasi perangkatnya:

Lokal = en-GB
Mode malam = night
Kepadatan piksel layar = hdpi
Jenis layar sentuh = notouch
Metode input teks utama = 12key

Dengan membandingkan konfigurasi perangkat dengan resource alternatif yang tersedia, Android akan memilih drawable dari drawable-en-night.

Sistem akan menentukan keputusannya mengenai resource yang akan digunakan dengan logika berikut:

Gambar 2. Diagram alir cara Android menemukan resource yang paling cocok.

1. Menghapus file resource yang bertentangan dengan konfigurasi perangkat.

   Direktori drawable-fr-rCA/ dihapus karena bertentangan dengan lokal en-GB.

   drawable/
   drawable-en/
   drawable-fr-rCA/
   drawable-en-night/
   drawable-en-notouch-12key/
   drawable-night-ldpi/
   drawable-night-notouch-12key/
   

   Pengecualian: Kepadatan piksel layar adalah satu penentu yang tidak dihapus karena bertentangan. Meskipun kepadatan layar perangkat adalah hdpi, drawable-night-ldpi/ tidak dihapus karena setiap kepadatan layar dianggap cocok untuk saat ini. Untuk mengetahui informasinya, lihat Ringkasan kompatibilitas layar.

2. Cari penentu prioritas tertinggi berikutnya dalam daftar (Tabel 2). (Mulai dengan MCC.)
3. Apakah salah satu direktori resource menyertakan penentu ini?
   • Jika tidak, kembali ke langkah dua dan lihat penentu berikutnya. Dalam contoh ini, jawabannya adalah "tidak" hingga penentu bahasa tercapai.
   • Jika ya, lanjutkan ke langkah keempat.
4. Hapus direktori resource yang tidak termasuk penentu ini. Dalam contoh ini, selanjutnya sistem akan menghapus semua direktori yang tidak menyertakan penentu bahasa:

   drawable/
   drawable-en/
   drawable-en-night/
   drawable-en-notouch-12key/
   drawable-night-ldpi/
   drawable-night-notouch-12key/
   

   Pengecualian: Jika penentu yang dimaksud adalah kepadatan piksel layar, Android akan memilih opsi yang paling cocok dengan kepadatan layar perangkat. Secara umum, Android lebih memilih untuk memperkecil skala gambar asli yang lebih besar daripada memperbesar skala gambar asli yang lebih kecil. Untuk mengetahui informasi selengkapnya, lihat Ringkasan kompatibilitas layar.

5. Ulangi langkah dua, tiga, dan empat hingga tersisa satu direktori. Dalam contoh ini, mode malam adalah penentu berikutnya yang memiliki kecocokan. Jadi, resource yang tidak menentukan mode malam akan dihapus:

   drawable-en/
   drawable-en-night/
   drawable-en-notouch-12key/
   

   Direktori yang tersisa adalah drawable-en-night.

Meskipun prosedur dijalankan untuk setiap resource yang diminta, sistem akan mengoptimalkan beberapa aspeknya. Satu optimalisasi tersebut adalah bahwa setelah konfigurasi perangkat diketahui, sistem mungkin akan menghapus resource alternatif yang sama sekali tidak cocok. Misalnya, jika bahasa konfigurasi adalah bahasa Inggris, setiap direktori resource yang memiliki penentu bahasa yang diatur ke selain bahasa Inggris tidak akan pernah disertakan dalam kumpulan resource yang diperiksa (meskipun direktori resource tanpa penentu bahasa masih disertakan).

Saat memilih resource berdasarkan penentu ukuran layar, sistem akan menggunakan resource yang didesain untuk layar yang lebih kecil daripada layar saat ini jika tidak ada resource yang lebih cocok. Misalnya, layar ukuran besar akan menggunakan resource layar ukuran normal jika diperlukan.

Akan tetapi, jika satu-satunya resource yang tersedia lebih besar daripada layar saat ini, sistem tidak akan menggunakannya dan aplikasi Anda akan error jika tidak ada resource lain yang cocok dengan konfigurasi perangkat (misalnya, jika semua resource tata letak diberi tag penentu xlarge, tetapi perangkat memiliki layar ukuran normal).

Catatan: Prioritas penentu (dalam Tabel 2) lebih penting daripada jumlah penentu yang sama persis dengan perangkat. Dalam contoh sebelumnya, pada langkah keempat, pilihan terakhir pada daftar berisi tiga penentu yang benar-benar cocok dengan perangkat (mode malam, jenis layar sentuh, dan metode input), sementara drawable-en hanya memiliki satu parameter yang cocok (bahasa). Akan tetapi, bahasa memiliki prioritas lebih tinggi daripada penentu lainnya sehingga drawable-night-notouch-12key dieliminasi.

Referensi lainnya

Untuk mempelajari lebih lanjut resource aplikasi, lihat referensi tambahan berikut:

Dokumentasi

• Resource di Compose

Melihat konten

• Ringkasan resource aplikasi (Tampilan)