Resource adalah file tambahan dan konten statis yang digunakan kode Anda, seperti bitmap, penetapan tata letak, 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 tata letak UI yang berbeda bergantung pada ukuran layar atau string 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.java res/ drawable/ graphic.png layout/ main.xml info.xml mipmap/ icon.png values/ strings.xml
Direktori res/
berisi semua resource dalam
subdirektorinya: resource gambar, dua resource tata letak, 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.
Direktori | Jenis Resource |
---|---|
animator/ |
File XML yang menetapkan Animasi properti. |
anim/ |
File XML yang menetapkan Animasi
tween. Animasi properti juga dapat disimpan dalam direktori ini, tetapi
direktori animator/ lebih disukai bagi animasi properti agar kedua jenis
ini dapat dibedakan. |
color/ |
File XML yang mendefinisikan daftar status warna. Untuk mengetahui informasi selengkapnya, lihat Resource daftar status warna. |
drawable/ |
File bitmap (PNG,
Untuk mengetahui informasi selengkapnya, lihat Resource drawable. |
mipmap/ |
File drawable untuk beragam kepadatan ikon peluncur. Untuk informasi selengkapnya tentang mengelola
ikon peluncur dengan folder mipmap/ , lihat
Menempatkan ikon aplikasi di
direktori mipmap. |
layout/ |
File XML yang mendefinisikan tata letak antarmuka pengguna. Untuk mengetahui informasi selengkapnya, lihat Resource tata letak. |
menu/ |
File XML yang menetapkan menu aplikasi, seperti menu opsi, menu konteks, atau submenu. Untuk mengetahui informasi selengkapnya, lihat Resource menu. |
raw/ |
File arbitrer yang akan disimpan dalam bentuk mentah. Untuk membuka resource ini dengan Namun, jika Anda memerlukan akses ke nama file asli dan hierarki file, pertimbangkan
untuk menyimpan resource dalam direktori |
values/ |
File XML yang berisi nilai-nilai sederhana, seperti string, bilangan bulat, dan warna. Karena file resource XML dalam subdirektori Karena setiap resource ditetapkan dengan elemen XML-nya sendiri, Anda dapat bebas menamai file ini dan menempatkan berbagai jenis resource dalam satu file. Akan tetapi, agar lebih jelas, Anda mungkin perlu menempatkan jenis resource unik dalam file berbeda. Misalnya, berikut ini adalah beberapa ketentuan penamaan file untuk resource yang dapat Anda buat dalam direktori ini:
Untuk mengetahui informasi selengkapnya, lihat Resource string, Resource gaya, dan Jenis resource lainnya. |
xml/ |
File XML arbitrer yang bisa dibaca saat runtime dengan memanggil Resources.getXML() . Berbagai file konfigurasi XML
harus disimpan di sini, seperti konfigurasi Penelusuran.
|
font/ |
File font dengan ekstensi seperti TTF, OTF,
atau TTC, atau file XML yang
menyertakan elemen <font-family> . Untuk mengetahui informasi selengkapnya tentang
font sebagai resource, lihat
Menambahkan font sebagai resource XML.
|
Perhatian: Jangan pernah menyimpan file resource langsung di dalam
direktori res/
. Hal ini menyebabkan error compiler.
Untuk mengetahui informasi selengkapnya tentang setiap jenis resource, lihat Ringkasan jenis resource.
Resource yang disimpan dalam subdirektori yang didefinisikan dalam tabel 1 merupakan 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 resource tata letak yang berbeda untuk perangkat yang memiliki layar lebih besar dari biasanya untuk memanfaatkan ruang layar ekstra. Anda juga dapat menyediakan berbagai resource string yang menerjemahkan teks di antarmuka pengguna berdasarkan setelan bahasa perangkat. Guna menyediakan berbagai resource ini untuk konfigurasi perangkat yang berbeda, Anda harus menyediakan resource alternatif selain resource default.
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.
![](https://developer.android.com/static/images/resources/resource_devices_diagram2.png?authuser=6&hl=id)
Gambar 1. Dua perangkat menggunakan resource tata letak berbeda berdasarkan ukuran layar.
Agar dapat menyebutkan alternatif konfigurasi tertentu untuk satu set resource, lakukan langkah berikut:
- 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 menetapkan 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 urutan penentu salah, resource akan diabaikan.
- 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 pengontrol kualitas konfigurasi yang valid 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.
Konfigurasi | Nilai penentu | Deskripsi |
---|---|---|
MCC dan MNC | Contoh:mcc310
mcc208-mnc00
|
Kode negara seluler (MCC), secara opsional diikuti oleh kode jaringan seluler (MNC)
dari kartu SIM dalam perangkat. Misalnya, Jika perangkat menggunakan koneksi radio (yakni ponsel GSM), nilai MCC dan MNC berasal dari kartu SIM. Anda juga dapat menggunakan MCC saja, misalnya, untuk menyertakan resource legal spesifik untuk negara tersebut di aplikasi Anda. Jika Anda perlu menentukan berdasarkan bahasa saja, gunakan penentu bahasa, skrip (opsional), dan region (opsional). Jika Anda menggunakan penentu MCC dan MNC, lakukan dengan hati-hati dan uji apakah penentunya berfungsi seperti yang diharapkan. Lihat juga kolom konfigurasi |
Bahasa, skrip (opsional), dan wilayah (opsional) | Contoh:en fr en-rUS fr-rFR fr-rCA b+en b+en+US b+es+419 b+zh+Hant b+sr+Latn+RS |
Bahasa didefinisikan oleh kode bahasa dua huruf ISO 639-1, dapat juga diikuti
dengan kode wilayah dua huruf ISO 3166-1-alpha-2 (diawali dengan
huruf kecil Kode tidak peka huruf besar/kecil. Awalan Android 7.0 (API level 24) memperkenalkan dukungan untuk tag bahasa BCP 47, yang dapat Anda gunakan untuk menentukan resource khusus bahasa dan wilayah. Tag bahasa terdiri dari urutan satu atau beberapa subtag, yang masing-masing menyaring atau mempersempit rentang bahasa yang diidentifikasi oleh keseluruhan tag. Untuk informasi lebih lanjut tentang tag bahasa, lihat Tag untuk Mengidentifikasi Bahasa. Untuk menggunakan tag bahasa BCP 47, gabungkan
Tag bahasa dapat berubah selama masa pakai aplikasi Anda jika pengguna mengubah bahasanya dalam setelan sistem. Untuk informasi tentang pengaruh hal ini terhadap aplikasi Anda selama runtime, lihat Menangani perubahan konfigurasi. Untuk panduan lengkap melokalkan aplikasi Anda ke bahasa lain, lihat Melokalkan aplikasi. Lihat juga metode |
Arah tata letak | ldrtl ldltr |
Arah tata letak aplikasi Anda. Arah tata letak ini bisa berlaku untuk resource mana pun seperti tata letak, drawable, atau nilai. Misalnya, jika Anda ingin memberikan tata letak spesifik untuk bahasa Arab dan tata letak umum untuk bahasa "kanan-ke-kiri" lainnya, seperti bahasa Persia atau Ibrani, Anda harus menggunakan direktori seperti berikut:
Catatan: Guna mengaktifkan fitur tata letak kanan ke kiri
untuk aplikasi, Anda harus menyetel Ditambahkan di API level 17. |
Lebar terkecil | sw<N>dp Contoh: sw320dp sw600dp sw720dp dll. |
Dimensi terpendek dari area layar yang tersedia untuk aplikasi.
Secara khusus,
Misalnya, jika tata letak mengharuskan dimensi area layar terkecilnya
setiap saat paling tidak 600 dp, Anda bisa menggunakan penentu ini untuk
membuat resource tata letak di direktori Penggunaan lebar terkecil untuk menentukan ukuran layar umum sangatlah berguna karena lebar sering kali menjadi faktor penentu dalam mendesain tata letak. UI sering di-scroll secara vertikal, tetapi memiliki batasan yang cukup ketat untuk ruang minimum yang diperlukannya secara horizontal. Lebar yang tersedia juga merupakan faktor kunci dalam menentukan apakah akan menggunakan tata letak satu panel untuk handset ataukah tata letak multipanel untuk tablet. Dengan demikian, Anda mungkin harus memperhatikan ukuran lebar terkecil yang memungkinkan di setiap perangkat. Lebar terkecil perangkat memperhitungkan dekorasi layar dan UI sistem. Misalnya, jika perangkat memiliki elemen UI persisten pada layar yang memperhitungkan ruang di sepanjang sumbu dengan lebar terkecil, sistem menyatakan lebar terkecil menjadi lebih kecil dari ukuran layar sebenarnya, karena itu adalah piksel layar yang tidak tersedia untuk UI Anda. Sebagian nilai yang mungkin Anda gunakan di sini untuk ukuran layar umum:
Jika aplikasi Anda menyediakan beberapa direktori resource dengan nilai yang berbeda untuk
penentu Ditambahkan dalam level API 13. Lihat juga atribut Untuk mengetahui informasi selengkapnya tentang mendesain untuk layar yang berbeda menggunakan penentu ini, lihat Desain responsif/adaptif dengan tampilan. |
Lebar dan tinggi yang tersedia | w<N>dp h<N>dp Contoh: w720dp w1024dp h720dp h1024dp dll. |
Menentukan lebar atau tinggi layar minimum yang tersedia (dalam unit Lebar dan tinggi yang tersedia sering kali berguna untuk menentukan apakah akan menggunakan tata letak multipanel karena, meskipun di perangkat tablet, Anda sering kali tidak menginginkan tata letak multipanel yang sama untuk orientasi potret seperti yang Anda lakukan untuk lanskap. Dengan demikian, Anda dapat menggunakan keduanya untuk menentukan lebar dan/atau tinggi minimum yang diperlukan untuk tata letak, bukan menggunakan penentu ukuran dan orientasi bersama-sama. Jika aplikasi Anda menyediakan beberapa direktori resource dengan nilai yang berbeda untuk konfigurasi ini, sistem akan menggunakan nilai terdekat dengan (tanpa melebihi) lebar layar perangkat saat ini. Nilai terdekat ditentukan dengan menambahkan selisih antara lebar layar sebenarnya dan lebar yang ditentukan dengan selisih antara tinggi layar sebenarnya dan tinggi yang ditentukan, dengan tinggi dan lebar yang tidak ditentukan memiliki nilai 0. Karena nilainya mengecualikan area yang ditempati oleh
Inset jendela, maka jika perangkat memiliki
elemen UI yang persisten di tepi layar, nilai lebar dan tinggi
lebih kecil dari dimensi layar sebenarnya, meskipun aplikasi ditampilkan dari tepi ke tepi
menggunakan
Beberapa dekorasi layar vertikal yang tidak tetap (seperti status bar ponsel yang dapat disembunyikan saat layar penuh) tidak diperhitungkan di sini, begitu juga dekorasi jendela seperti panel judul atau panel tindakan, sehingga aplikasi harus siap menangani ruang yang agak lebih kecil dari yang ditentukan. Catatan: Sistem memilih resource yang cocok dengan lebar dan tinggi. Oleh karena itu, resource yang menentukan keduanya lebih diutamakan daripada resource yang menentukan salah satunya saja. Misalnya, jika layar sebenarnya memiliki lebar 720 dp dan tinggi 1280 dp, dan satu resource memenuhi syarat dengan lebar 720 dp, dan resource lainnya memenuhi syarat sebagai lebar 700 dp dan tinggi 1200 dp, yang kedua akan dipilih meskipun yang pertama adalah pencocokan persis untuk yang ditetapkannya. Ditambahkan dalam level API 13. Lihat juga kolom konfigurasi Untuk mengetahui informasi selengkapnya tentang mendesain untuk layar yang berbeda menggunakan penentu ini, lihat Desain responsif/adaptif dengan tampilan. |
Ukuran layar |
small normal large xlarge
|
Catatan: Menggunakan penentu ukuran tidak berarti bahwa resource hanya tersedia untuk layar dengan ukuran tersebut. Jika Anda tidak menyediakan resource alternatif dengan penentu yang lebih cocok dengan konfigurasi perangkat saat ini, sistem dapat menggunakan resource mana saja yang paling cocok. Perhatian: Jika semua resource Anda menggunakan penentu
ukuran yang lebih besar dari layar saat ini, sistem
tidak akan menggunakannya dan aplikasi Anda akan error saat runtime. Hal ini terjadi, misalnya, jika semua resource
tata letak diberi tag dengan penentu Ditambahkan di API level 4. Lihat juga bidang konfigurasi Untuk mengetahui informasi selengkapnya, lihat Ringkasan kompatibilitas layar |
Aspek layar |
long notlong
|
Ditambahkan di API level 4. Aspek layar ini sepenuhnya berdasarkan rasio aspek layar (layar Lihat juga bidang konfigurasi |
Layar bulat |
round notround
|
Ditambahkan di API level 23. Lihat juga metode
konfigurasi |
Wide Color Gamut |
widecg nowidecg
|
Ditambahkan di API level 26. Lihat juga metode konfigurasi |
Rentang Dinamis Tinggi (HDR) |
highdr lowdr
|
Ditambahkan di API level 26. Lihat juga metode konfigurasi |
Orientasi layar |
port land
|
Orientasi layar dapat berubah selama masa pakai aplikasi Anda jika pengguna memutar layar. Untuk mengetahui informasi tentang pengaruh orientasi layar terhadap aplikasi Anda selama runtime, lihat Menangani perubahan konfigurasi. Lihat juga kolom
konfigurasi |
Mode UI |
car desk television appliance watch vrheadset
|
Ditambahkan dalam level API 8; televisi ditambahkan dalam API 13; jam ditambahkan dalam API 20. Untuk mengetahui informasi tentang cara aplikasi merespons saat perangkat dimasukkan ke dalam atau dilepaskan dari dok-nya, baca Menentukan dan memantau jenis dan status terpasang ke dok. Respons aplikasi dapat berubah selama masa pakai aplikasi jika pengguna menempatkan perangkat di
dok. Anda dapat mengaktifkan atau menonaktifkan sebagian mode ini menggunakan
|
Mode malam |
night notnight
|
Ditambahkan dalam API level 8. Mode malam dapat berubah selama masa pakai aplikasi jika mode malam dibiarkan dalam
mode otomatis (default), dalam hal ini perubahan mode berdasarkan pada waktu hari. Anda dapat mengaktifkan
atau menonaktifkan mode ini menggunakan |
Kepadatan piksel layar (dpi) |
ldpi mdpi hdpi xhdpi xxhdpi xxxhdpi nodpi tvdpi anydpi nnndpi
|
Terdapat rasio skala 3:4:6:8:12:16 antara enam kepadatan utama (dengan mengabaikan kepadatan tvdpi). Jadi, bitmap 9x9 di ldpi adalah 12x12 di mdpi, 18x18 di hdpi, 24x24 di xhdpi, dan seterusnya. Catatan: Menggunakan penentu kepadatan tidak menyiratkan bahwa resource hanya untuk layar dengan kepadatan tersebut. Jika Anda tidak menyediakan resource alternatif dengan penentu yang lebih cocok dengan konfigurasi perangkat saat ini, sistem akan menggunakan resource mana saja yang paling cocok. Untuk mengetahui informasi selengkapnya tentang cara menangani kepadatan layar yang berbeda dan cara Android menskalakan bitmap agar sesuai dengan kepadatan saat ini, lihat Ringkasan kompatibilitas layar. |
Jenis layar sentuh |
notouch finger
|
Lihat juga kolom konfigurasi |
Ketersediaan keyboard |
keysexposed keyshidden keyssoft
|
Jika Anda menyediakan resource Ketersediaan keyboard dapat berubah selama masa pakai aplikasi jika pengguna membuka keyboard hardware. Untuk mengetahui informasi tentang pengaruh ketersediaan keyboard terhadap aplikasi Anda selama runtime, lihat Menangani perubahan konfigurasi. Lihat juga kolom konfigurasi |
Metode input teks utama |
nokeys qwerty 12key
|
Lihat juga kolom konfigurasi |
Ketersediaan tombol navigasi |
navexposed navhidden
|
Ketersediaan tombol navigasi dapat berubah selama masa pakai aplikasi jika pengguna menampilkan tombol navigasi. Untuk mengetahui informasi tentang pengaruh ketersediaan tombol navigasi terhadap aplikasi Anda selama runtime, lihat Menangani perubahan konfigurasi. Lihat juga kolom konfigurasi |
Metode navigasi non-sentuh utama |
nonav dpad trackball wheel
|
Lihat juga kolom konfigurasi |
Versi platform (API level) | Contoh:v3 v4 v7 dll. |
Level API yang didukung oleh perangkat. Misalnya, |
Catatan: Penentu hanya didukung oleh versi Android tertentu. Menggunakan penentu baru secara implisit
akan menambahkan penentu versi platform sehingga perangkat lama dapat mengabaikannya. Misalnya, menggunakan
penentu w600dp
akan otomatis menyertakan penentu v13
, karena
penentu lebar yang tersedia baru di API level 13. Untuk menghindari masalah, selalu sertakan satu set
resource default (satu set resource tanpa penentu). Untuk mengetahui informasi selengkapnya, lihat
bagian Menyediakan kompatibilitas perangkat terbaik dengan
resource.
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-land
berlaku untuk perangkat bahasa Inggris-AS dalam orientasi lanskap. - Penentu harus dalam urutan seperti yang tercantum dalam tabel 2.
- Salah:
drawable-hdpi-port/
- Benar:
drawable-port-hdpi/
- Salah:
- 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, sepertidrawable-es/
dandrawable-fr/
, yang berisi file yang sesuai. Namun, Anda tidak harus menduplikasi file tersebut di kedua lokasi. Sebagai gantinya, Anda dapat membuat alias ke resource, seperti yang dijelaskan di bagian Membuat resource alias.
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.
Catatan: Tidak semua resource menawarkan mekanisme yang memungkinkan
Anda membuat alias ke resource lain. Khususnya, resource animasi, menu, mentah, dan resource lain yang tidak ditetapkan
dalam direktori xml/
tidak menawarkan fitur ini.
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
dalam res/drawable-en-rCA/
dan res/drawable-fr-rCA/
yang mengacu ke resource icon_ca.png
yang menggunakan elemen <bitmap>
. Dengan membuat file ini, Anda dapat menyimpan satu versi saja
dari file PNG dan dua file XML kecil yang mengarah ke resource tersebut. Lihat contoh di bagian berikut
untuk mengetahui detailnya.
Drawable
Untuk membuat alias ke drawable yang ada, gunakan elemen <drawable>
.
<?xml version="1.0" encoding="utf-8"?> <resources> <drawable name="icon">@drawable/icon_ca</drawable> </resources>
Jika Anda menyimpan file ini sebagai icon.xml
dalam direktori resource alternatif, seperti res/values-en-rCA/
, file akan dikompilasi
menjadi resource yang dapat Anda referensikan sebagai R.drawable.icon
, tetapi
sebenarnya merupakan alias untuk resource R.drawable.icon_ca
yang
disimpan dalam res/drawable/
.
Tata Letak
Untuk membuat alias ke tata letak yang ada, gunakan elemen <include>
yang digabungkan dalam <merge>
.
<?xml version="1.0" encoding="utf-8"?> <merge> <include layout="@layout/main_ltr"/> </merge>
Jika Anda menyimpan file ini sebagai main.xml
, file akan dikompilasi menjadi resource yang dapat Anda referensikan
sebagai R.layout.main
, tetapi sebenarnya merupakan alias untuk
resource R.layout.main_ltr
.
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
,drawable
, danlayout
. Untuk mengetahui informasi selengkapnya tentang berbagai jenis, lihat Ringkasan jenis resource. - Nama resource, yang dapat berupa: nama file,
tidak termasuk ekstensi; atau nilai dalam atribut
android:name
XML, jika resource tersebut merupakan nilai sederhana (misalnya string).
Ada dua cara untuk mengakses resource:
- Dalam kode: menggunakan bilangan bulat statis dari subclass untuk class
R
, seperti:R.string.hello
string
adalah jenis resource danhello
adalah nama resource. Ada banyak Android API yang dapat mengakses resource asalkan Anda menyediakan ID resource dengan format ini. Untuk mengetahui informasi selengkapnya, lihat bagian Mengakses resource dalam kode. - Di XML: menggunakan sintaksis XML khusus yang berkaitan dengan ID resource yang didefinisikan dalam class
R
, misalnya:@string/hello
string
adalah jenis resource danhello
adalah nama resource. Anda dapat menggunakan sintaksis ini dalam resource XML di mana pun Anda ingin menyediakan sebuah nilai dalam sebuah resource. Untuk mengetahui informasi selengkapnya, lihat bagian Mengakses resource dari XML.
Mengakses resource dalam kode
Anda dapat menggunakan resource dalam kode dengan meneruskan ID resource sebagai parameter metode. Misalnya,
Anda dapat menyetel ImageView
agar menggunakan resource res/drawable/myimage.png
dengan menggunakan setImageResource()
:
Kotlin
val imageView = findViewById(R.id.myimageview) as ImageView imageView.setImageResource(R.drawable.myimage)
Java
ImageView imageView = (ImageView) findViewById(R.id.myimageview); imageView.setImageResource(R.drawable.myimage);
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 subclassR
untuk jenis resource.<resource_name>
dapat berupa nama file resource tanpa ekstensi atau nilai atributandroid:name
dalam elemen XML untuk nilai sederhana.
Untuk mengetahui informasi selengkapnya tentang setiap jenis resource dan cara mereferensikannya, lihat Ringkasan jenis resource.
Kasus penggunaan
Ada banyak metode yang menerima parameter ID resource dan Anda dapat mengambil resource dengan menggunakan metode di Resources
. Anda
dapat mengambil instance Resources
dengan Context.getResources()
.
Berikut beberapa contoh cara mengakses resource dalam kode:
Kotlin
// Load a background for the current screen from a drawable resource. window.setBackgroundDrawableResource(R.drawable.my_background_image) // Set the Activity title by getting a string from the Resources object, because // this method requires a CharSequence rather than a resource ID. window.setTitle(resources.getText(R.string.main_title)) // Load a custom layout for the current screen. setContentView(R.layout.main_screen) // Set a slide in animation by getting an Animation from the Resources object. flipper.setInAnimation(AnimationUtils.loadAnimation(this, R.anim.hyperspace_in)) // Set the text on a TextView object using a resource ID. val msgTextView = findViewById(R.id.msg) as TextView msgTextView.setText(R.string.hello_message)
Java
// Load a background for the current screen from a drawable resource. getWindow().setBackgroundDrawableResource(R.drawable.my_background_image) ; // Set the Activity title by getting a string from the Resources object, because // this method requires a CharSequence rather than a resource ID. getWindow().setTitle(getResources().getText(R.string.main_title)); // Load a custom layout for the current screen. setContentView(R.layout.main_screen); // Set a slide in animation by getting an Animation from the Resources object. flipper.setInAnimation(AnimationUtils.loadAnimation(this, R.anim.hyperspace_in)); // Set the text on a TextView object using a resource ID. TextView msgTextView = (TextView) findViewById(R.id.msg); msgTextView.setText(R.string.hello_message);
Perhatian: Jangan ubah file R.java
secara manual. Library ini dihasilkan oleh alat aapt
saat project Anda
dikompilasi. Perubahan apa pun akan ditimpa apabila nanti Anda mengompilasi.
Mengakses resource dari XML
Anda dapat mendefinisikan nilai untuk beberapa atribut dan elemen XML dengan menggunakan referensi ke resource yang ada. Anda akan sering melakukannya saat membuat file tata letak, untuk memasok string dan gambar bagi widget Anda.
Misalnya, jika Anda menambahkan Button
ke tata letak, gunakan
resource string untuk teks tombol:
<Button android:layout_width="fill_parent" android:layout_height="wrap_content" android:text="@string/submit" />
Sintaksis
Berikut adalah sintaksis untuk merujuk resource dalam resource XML:
@[<package_name>:]<resource_type>/<resource_name>
<package_name>
adalah nama paket yang di dalamnya terdapat resource (tidak dibutuhkan bila mereferensikan resource dari paket yang sama).<resource_type>
adalah subclassR
untuk jenis resource.<resource_name>
dapat berupa nama file resource tanpa ekstensi atau nilai atributandroid:name
dalam elemen XML untuk nilai sederhana.
Untuk mengetahui informasi selengkapnya tentang setiap jenis resource dan cara mereferensikannya, lihat Ringkasan jenis resource.
Kasus penggunaan
Dalam beberapa kasus, Anda harus menggunakan resource untuk suatu nilai dalam XML, misalnya untuk menerapkan gambar drawable ke widget, tetapi Anda juga dapat menggunakan resource di XML mana pun yang menerima nilai sederhana. Misalnya, jika Anda mempunyai file resource berikut yang berisi resource warna dan resource string:
<?xml version="1.0" encoding="utf-8"?> <resources> <color name="opaque_red">#f00</color> <string name="hello">Hello!</string> </resources>
Anda dapat menggunakan resource ini dalam file tata letak berikut untuk mengatur warna teks dan string teks:
<?xml version="1.0" encoding="utf-8"?> <EditText xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="fill_parent" android:layout_height="fill_parent" android:textColor="@color/opaque_red" android:text="@string/hello" />
Dalam hal ini, Anda tidak perlu menyebutkan nama paket dalam referensi resource karena resource berasal dari paket Anda sendiri. Untuk mereferensikan resource sistem, Anda harus memasukkan nama paket seperti yang ditampilkan pada contoh berikut:
<?xml version="1.0" encoding="utf-8"?> <EditText xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="fill_parent" android:layout_height="fill_parent" android:textColor="@android:color/secondary_text_dark" android:text="@string/hello" />
Catatan: Selalu gunakan resource string agar aplikasi Anda dapat dilokalkan untuk bahasa lain. Untuk informasi tentang cara membuat resource alternatif (seperti string yang dilokalkan), lihat Menyediakan resource alternatif. Untuk panduan lengkap melokalkan aplikasi Anda ke bahasa lain, lihat Melokalkan aplikasi.
Anda bahkan dapat menggunakan resource dalam XML untuk membuat alias. Misalnya, Anda bisa membuat resource drawable yang merupakan alias bagi resource drawable lainnya:
<?xml version="1.0" encoding="utf-8"?> <bitmap xmlns:android="http://schemas.android.com/apk/res/android" android:src="@drawable/other_drawable" />
Hal ini terdengar berlebihan, tapi dapat sangat berguna saat menggunakan resource alternatif. Untuk mengetahui informasi selengkapnya, lihat bagian membuat resource alias.
Atribut gaya referensi
Resource atribut gaya memungkinkan Anda mereferensikan nilai suatu atribut dalam tema yang diterapkan saat ini. Dengan mereferensikan atribut gaya, Anda dapat menyesuaikan tampilan elemen UI dengan menata gayanya agar cocok dengan beragam variasi standar yang disediakan oleh tema saat ini, bukan menyediakan nilai yang di-hardcode. Mereferensikan sebuah atribut gaya pada dasarnya berarti "Gunakan gaya yang didefinisikan oleh atribut ini, dalam tema saat ini".
Untuk mereferensikan atribut gaya, sintaksis namanya hampir sama dengan format resource
normal. Namun, sebagai ganti simbol "at" (@
), gunakan tanda tanya (?
), Jenis
resource bersifat opsional. Jadi, sintaksis referensinya adalah sebagai berikut:
?[<package_name>:][<resource_type>/]<resource_name>
Misalnya, berikut ini cara Anda mereferensikan atribut untuk menyetel warna teks agar cocok dengan warna teks sekunder dari tema sistem:
<EditText id="text" android:layout_width="fill_parent" android:layout_height="wrap_content" android:textColor="?android:textColorSecondary" android:text="@string/hello_world" />
Di sini, atribut android:textColor
menetapkan nama atribut gaya
dalam tema saat ini. Android kini menggunakan nilai yang diterapkan pada atribut gaya android:textColorSecondary
sebagai nilai untuk android:textColor
dalam widget ini. Karena alat resource sistem
mengetahui bahwa resource atribut diharapkan dalam konteks ini,
Anda tidak perlu menyatakan jenisnya secara eksplisit, yakni
?android:attr/textColorSecondary
. Anda dapat mengecualikan jenis attr
.
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
.
Akan tetapi, 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, tema, dan tata letak. Untuk
mengakses semua resource ini, tentukan referensi resource Anda dengan
nama paket android
. Misalnya, Android menyediakan resource tata letak yang bisa Anda gunakan untuk item daftar dalam ListAdapter
:
Kotlin
listAdapter = ArrayAdapter(this, android.R.layout.simple_list_item_1, myarray)
Java
setListAdapter(new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, myarray));
Dalam contoh ini, simple_list_item_1
adalah resource tata letak yang didefinisikan oleh platform untuk item di ListView
. Anda bisa menggunakannya daripada membuat
tata letak sendiri untuk item daftar.
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.
Demikian pula, jika Anda menyediakan resource tata letak berbeda berdasarkan orientasi layar, pilih satu orientasi sebagai default. Misalnya, sebagai ganti menyediakan resource tata letak dalam layout-land/
untuk lanskap dan layout-port/
untuk potret, biarkan salah satu sebagai default, seperti
layout/
untuk lanskap dan layout-port/
untuk potret.
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 lama, maka saat versi lama Android 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-port/ drawable-en-notouch-12key/ drawable-port-ldpi/ drawable-port-notouch-12key/
Dan anggaplah yang berikut ini merupakan konfigurasi perangkatnya:
Lokal = en-GB
Orientasi layar = port
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-port
.
Sistem akan menentukan keputusannya mengenai resource yang akan digunakan dengan logika berikut:
![](https://developer.android.com/static/images/resources/res-selection-flowchart.png?authuser=6&hl=id)
Gambar 2. Diagram alir cara Android menemukan resource yang paling cocok.
- Menghapus file sumber daya yang bertentangan dengan konfigurasi perangkat.
Direktori
drawable-fr-rCA/
dihapus karena bertentangan dengan lokalen-GB
.drawable/ drawable-en/
drawable-fr-rCA/drawable-en-port/ drawable-en-notouch-12key/ drawable-port-ldpi/ drawable-port-notouch-12key/Pengecualian: Kepadatan piksel layar adalah satu penentu yang tidak dihapus karena bertentangan. Meskipun kepadatan layar perangkat adalah hdpi,
drawable-port-ldpi/
tidak dihapus karena setiap kepadatan layar dianggap cocok untuk saat ini. Untuk mengetahui informasinya, lihat Ringkasan kompatibilitas layar. - Cari penentu prioritas tertinggi berikutnya dalam daftar (tabel 2). (Mulai dengan MCC.)
- 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.
- 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-port/ drawable-en-notouch-12key/drawable-port-ldpi/drawable-port-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.
- Ulangi langkah dua, tiga, dan empat hingga tersisa satu direktori. Dalam contoh ini, orientasi
layar adalah penentu berikutnya yang memiliki kecocokan.
Jadi, resource yang tidak menetapkan orientasi layar akan dihapus:
drawable-en/drawable-en-port/drawable-en-notouch-12key/Direktori yang tersisa adalah
drawable-en-port
.
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 dari layar saat ini jika tidak ada resource yang lebih cocok. Misalnya, layar ukuran besar menggunakan resource layar ukuran normal jika diperlukan.
Namun, jika
satu-satunya resource yang tersedia lebih besar dari layar saat ini, sistem
tidak akan menggunakannya dan aplikasi Anda akan error jika tidak ada resource lain yang cocok dengan konfigurasi
perangkat. Hal ini terjadi, misalnya, jika semua resource tata letak diberi tag dengan 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 (orientasi,
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-port-notouch-12key
dieliminasi.