Ringkasan resource aplikasi

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

Anda harus selalu mengeksternalkan resource aplikasi seperti gambar dan string dari kode, agar Anda bisa memeliharanya secara independen. Anda juga harus menyediakan resource alternatif untuk konfigurasi perangkat tertentu, dengan mengelompokkannya dalam direktori resource yang bernama 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 kepada Anda bagaimana mengelompokkan resource Anda dalam project Android dan memberikan resource alternatif untuk konfigurasi perangkat tertentu, dan kemudian mengaksesnya dari kode aplikasi Anda atau file XML lainnya.

Mengelompokkan jenis resource

Anda harus menempatkan setiap jenis resource dalam subdirektori spesifik pada direktori res/ project. Misalnya, berikut hierarki file untuk proyek sederhana:

MyProject/
    src/
        MyActivity.java
    res/
        drawable/
            graphic.png
        layout/
            main.xml
            info.xml
        mipmap/
            icon.png
        values/
            strings.xml

Seperti yang Anda lihat dalam contoh ini, direktori res/ berisi semua resource (dalam subdirektori): satu resource gambar, dua resource tata letak, beberapa direktori mipmap/ untuk ikon peluncur, dan satu 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 hitung nilai. (Animasi properti juga dapat disimpan dalam direktori ini, namun direktori animator/ lebih disukai bagi animasi properti agar kedua jenis ini dapat dibedakan.)
color/ File XML yang mendefinisikan daftar status warna. Lihat Resource Daftar Status Warna
drawable/

File bitmap (.png, .9.png, .jpg, .gif) atau file XML yang dikompilasi menjadi subjenis resource drawable berikut:

  • File bitmap
  • Nine-Patches (bitmap yang dapat diubah ukurannya)
  • Daftar status
  • Bentuk
  • Drawable animasi
  • Drawable lainnya

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. Lihat Resource Tata Letak.
menu/ File XML yang menetapkan menu aplikasi, seperti Menu Opsi, Menu Konteks, atau Sub Menu. Lihat Resource Menu.
raw/

File arbitrer yang akan disimpan dalam bentuk mentah. Untuk membuka resource ini dengan InputStream mentah, panggil Resources.openRawResource() dengan ID resource, yaitu R.raw.filename.

Namun, jika memerlukan akses ke nama file asli dan hierarki file, Anda dapat mempertimbangkan untuk menyimpan beberapa resource dalam direktori assets/ (bukan res/raw/). File dalam assets/ tidak diberi ID resource, jadi Anda dapat membacanya hanya menggunakan AssetManager.

values/

File XML yang berisi nilai-nilai sederhana, seperti string, bilangan bulat, dan warna.

Karena file resource XML dalam subdirektori res/ lainnya menetapkan satu resource berdasarkan nama file XML, file dalam direktori values/ menggambarkan beberapa resource. Untuk file dalam direktori ini, setiap turunan elemen <resources> menetapkan satu resource. Misalnya, elemen <string> membuat resource R.string dan elemen <color> membuat resource R.color.

Karena setiap resource ditetapkan dengan elemen XML-nya sendiri, Anda bisa bebas menamai file ini dan menempatkan jenis resource berbeda dalam satu file. Akan tetapi, agar 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:

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 yang tersedia di penelusuran.
font/ File font dengan ekstensi seperti .ttf, .otf, atau .ttc, atau file XML yang menyertakan elemen <font-family>. Untuk informasi selengkapnya tentang font sebagai resource, buka Font dalam XML.

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

Untuk informasi selengkapnya tentang jenis resource tertentu, lihat dokumentasi Jenis Resource.

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, jika perangkat memiliki layar lebih besar dari layar normal, maka Anda harus menyediakan resource tata letak yang berbeda yang memanfaatkan ruang layar ekstra. Atau, jika perangkat memiliki setelan bahasa berbeda, maka Anda harus menyediakan resource string berbeda yang menerjemahkan teks dalam antarmuka pengguna Anda. Untuk menyediakan resource berbeda ini bagi konfigurasi perangkat yang berbeda, Anda harus menyediakan resource alternatif, selain resource default.

Menyediakan resource alternatif

Hampir setiap aplikasi harus menyediakan resource alternatif untuk mendukung konfigurasi perangkat tertentu. Misalnya, Anda harus menyertakan resource drawable alternatif untuk kepadatan layar 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.

Gambar 1. Dua perangkat berbeda, masing-masing menggunakan resource tata letak berbeda.

Untuk menyebutkan alternatif konfigurasi tertentu untuk satu set resource:

  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 menetapkan konfigurasi individual yang akan digunakan resource ini (yang 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.

  2. Simpan masing-masing resource alternatif 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 di masing-masing direktori drawable memiliki ukuran untuk kepadatan layar tertentu, namun nama filenya persis sama. Dengan demikian, ID resource yang Anda gunakan untuk mereferensikan gambar icon.png atau background.png selalu sama, namun Android memilih versi masing-masing 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.

Android mendukung beberapa pengontrol kualitas konfigurasi dan Anda dapat menambahkan beberapa penentu ke satu nama direktori, dengan memisahkan setiap penentu dengan tanda hubung. Tabel 2 berisi daftar pengontrol kualitas konfigurasi yang valid, dalam urutan prioritas—jika Anda menggunakan beberapa penentu sebagai direktori resource, Anda harus menambahkannya ke nama direktori sesuai urutan yang tercantum dalam tabel.

Tabel 2. Nama-nama pengontrol kualitas konfigurasi.

Konfigurasi Nilai-nilai Penentu Deskripsi
MCC dan MNC Contoh:
mcc310
mcc310-mnc004
mcc208-mnc00
dll.

Kode negara seluler (MCC), secara opsional diikuti oleh kode jaringan seluler (MNC) dari kartu SIM dalam perangkat. Misalnya, mcc310 adalah AS untuk operator mana saja, mcc310-mnc004 adalah AS untuk Verizon, dan mcc208-mnc00 Prancis untuk Orange.

Jika perangkat menggunakan koneksi radio (ponsel GSM), nilai-nilai MCC dan MNC berasal dari kartu SIM.

Anda juga dapat menggunakan MCC saja (misalnya, untuk menyertakan resource legal spesifik untuk negara itu di aplikasi Anda). Jika Anda perlu menentukan hanya berdasarkan bahasa, gunakan penentu bahasa, skrip (opsional), dan region (opsional) (dibahas berikutnya). Jika Anda memutuskan untuk menggunakan penentu MCC dan MNC, Anda harus melakukannya dengan hati-hati dan menguji apakah penentu itu berjalan sesuai harapan.

Lihat juga kolom konfigurasi mcc, dan mnc, yang masing-masing menunjukkan kode negara seluler saat ini dan kode jaringan seluler.

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, bisa juga diikuti dengan kode wilayah dua huruf ISO 3166-1-alpha-2 (diawali dengan huruf kecil r).

Kode tidak peka huruf besar atau kecil; awalan r akan digunakan untuk membedakan bagian region. Anda tidak bisa menetapkan region saja.

Android 7.0 (API level 24) memperkenalkan dukungan untuk tag bahasa BCP 47, yang dapat Anda gunakan untuk menentukan resource khusus bahasa dan region. Tag bahasa terdiri dari urutan satu atau beberapa subtag, yang masing-masing memperhalus 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 b+ dan kode bahasa ISO 639-1 dua huruf, secara opsional diikuti oleh subtag tambahan yang dipisahkan oleh +.

Tag bahasa dapat berubah selama masa pakai aplikasi Anda jika pengguna mengubah bahasanya dalam setelan sistem. Lihat Menangani Perubahan Runtime untuk informasi tentang bagaimana hal ini dapat memengaruhi aplikasi Anda selama runtime.

Lihat Pelokalan untuk panduan lengkap melokalkan aplikasi Anda ke bahasa lain.

Lihat juga metode getLocales(), yang menyediakan daftar lokalitas yang ditentukan. Daftar ini termasuk lokal utama.

Arah Tata Letak ldrtl
ldltr

Arah tata letak aplikasi Anda. ldrtl berarti "arah tata letak-kanan-ke-kiri". ldltr berarti "arah tata letak-kiri-ke-kanan" dan merupakan nilai implisit default.

Ini bisa berlaku untuk resource mana pun seperti tata letak, drawable, atau nilai-nilai.

Misalnya, jika Anda ingin memberikan beberapa tata letak khusus untuk bahasa Arab dan beberapa tata letak umum untuk bahasa "kanan-ke-kiri" lainnya (seperti bahasa Persia atau Ibrani), maka Anda akan memiliki hal berikut:

res/
  layout/
    main.xml (Tata letak default)
  layout-ar/
    main.xml (Tata letak khusus untuk bahasa Arab)
  layout-ldrtl/
    main.xml (Bahasa "kanan-ke-kiri" apa pun, kecuali bahasa Arab, karena penentu bahasa "ar" memiliki prioritas yang lebih tinggi)

Catatan: Untuk mengaktifkan fitur tata letak kanan ke kiri untuk aplikasi, Anda harus menyetel supportsRtl ke "true" dan menyetel targetSdkVersion ke versi 17 atau yang lebih tinggi.

Ditambahkan di API level 17.

smallestWidth sw<N>dp

Contoh:
sw320dp
sw600dp
sw720dp
dll.

Dimensi terpendek dari area layar yang tersedia untuk aplikasi. Secara khusus, smallestWidth jendela aplikasi adalah yang terpendek dari tinggi dan lebar jendela yang tersedia (Anda juga dapat menganggapnya sebagai " lebar terkecil" untuk jendela). Anda dapat menggunakan penentu ini untuk memastikan bahwa aplikasi memiliki lebar minimal <N> dp untuk UI-nya.

Misalnya, jika tata letak mengharuskan dimensi layar terkecilnya setiap saat paling tidak 600 dp, maka Anda bisa menggunakan penentu ini untuk membuat resource tata letak, res/layout-sw600dp/. Sistem akan menggunakan resource ini hanya bila dimensi layar terkecil yang tersedia minimal 600dp, tanpa mempertimbangkan apakah sisi 600dp adalah tinggi atau lebar yang dipersepsikan pengguna. Lebar terkecil dapat berubah jika ukuran jendela diubah (mengubah lebar/tinggi yang tersedia) atau diposisikan ulang (berpotensi mengubah inset sistem).

Penggunaan lebar terkecil untuk menentukan ukuran layar umum sangatlah berguna karena lebar sering kali menjadi faktor penentu dalam mendesain tata letak. UI akan 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. Sehingga, mungkin Anda perlu memperhatikan tentang ukuran lebar terkecil yang memungkinkan pada setiap perangkat.

Lebar terkecil perangkat memperhitungkan dekorasi layar dan UI sistem. Misalnya, jika perangkat memiliki beberapa 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:

  • 320, untuk perangkat dengan konfigurasi layar seperti:
    • 240x320 ldpi (handset QVGA)
    • 320x480 mdpi (handset)
    • 480x800 hdpi (handset kepadatan tinggi)
  • 480, untuk layar seperti 480x800 mdpi (tablet/handset).
  • 600, untuk layar seperti 600x1024 mdpi (tablet 7").
  • 720, untuk layar seperti 720x1280 mdpi (tablet 10").

Bila aplikasi Anda menyediakan beberapa direktori resource dengan nilai yang berbeda untuk penentu smallestWidth, sistem akan menggunakan nilai terdekat dengan (tanpa melebihi) smallestWidth perangkat.

Ditambahkan dalam API level 13.

Lihat juga atribut android:requiresSmallestWidthDp, yang mendeklarasikan smallestWidth minimum yang kompatibel dengan aplikasi Anda, dan kolom konfigurasi smallestScreenWidthDp, yang menyimpan nilai smallestWidth perangkat.

Untuk informasi selengkapnya tentang mendesain untuk layar yang berbeda menggunakan penentu ini, lihat Mendukung berbagai ukuran layar.

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 dp yang ditentukan oleh nilai <N>) tempat resource harus digunakan. Nilai konfigurasi ini dibandingkan dengan lebar dan tinggi tampilan saat ini saat orientasi perangkat berubah antara potret dan lanskap, perangkat melipat atau membentangkan, atau sistem masuk atau keluar dari mode multi-aplikasi. Dalam mode multi-aplikasi, nilai mencerminkan lebar dan tinggi jendela yang berisi aplikasi, bukan lebar dan tinggi layar perangkat. Demikian pula, untuk aktivitas tersemat, nilainya berkaitan dengan lebar dan tinggi setiap aktivitas, bukan lebar dan tinggi layar (lihat Penyematan aktivitas).

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. Terdekat ke ditentukan dengan menambahkan perbedaan antara lebar layar sebenarnya dan lebar yang ditentukan dengan perbedaan antara tinggi layar sebenarnya dan tinggi yang ditentukan, dengan tinggi dan lebar yang tidak ditentukan memiliki nilai 0.

Nilainya mengecualikan area yang ditempati oleh inset jendela, jadi jika perangkat memiliki elemen UI yang persisten di tepi layar, nilai lebar dan tinggi lebih kecil dari dimensi layar sebenarnya—bahkan saat aplikasi ditampilkan dari tepi ke tepi menggunakan Window#setDecorFitsSystemWindows(boolean) atau WindowCompat#setDecorFitsSystemWindows(Window,boolean).

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 judulnya panel 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 akan lebih diutamakan daripada resource yang menentukan salah satunya saja. Misalnya, jika layar yang sebenarnya adalah w720dp dengan h1280dp dan satu resource memenuhi syarat dengan w720dp, dan resource lainnya memenuhi syarat sebagai w700dp-h1200dp, yang kedua akan dipilih meskipun yang pertama cocok persis dengan apa yang ditetapkan.

Ditambahkan dalam API level 13.

Lihat juga kolom konfigurasi screenWidthDp dan screenHeightDp, yang menyimpan lebar dan tinggi layar saat ini.

Untuk informasi selengkapnya tentang mendesain untuk layar yang berbeda menggunakan penentu ini, lihat Mendukung berbagai ukuran layar.

Ukuran layar small
normal
large
xlarge
  • small: Layar yang berukuran serupa dengan layar QVGA kepadatan rendah. Ukuran tata letak minimum untuk layar kecil adalah sekitar 320x426 satuan dp. Misalnya QVGA kepadatan rendah dan VGA kepadatan tinggi.
  • normal: Layar yang berukuran serupa dengan layar HVGA kepadatan sedang. Ukuran tata letak minimum untuk layar normal adalah sekitar 320x470 satuan dp. Contoh layar seperti itu adalah WQVGA kepadatan rendah, HVGA kepadatan sedang, WVGA kepadatan tinggi.
  • large: Layar yang berukuran serupa dengan layar VGA kepadatan sedang. Ukuran layout minimum untuk layar besar adalah sekitar 480x640 satuan dp. Misalnya layar VGA dan WVGA kepadatan sedang.
  • xlarge: Layar yang jauh lebih besar dari layar HVGA kepadatan sedang tradisional. Ukuran tata letak minimum untuk layar ekstra besar adalah sekitar 720x960 satuan dp. Perangkat dengan layar ekstra besar sering kali terlalu besar untuk dibawa dalam saku dan kemungkinan besar berupa perangkat bergaya tablet. Ditambahkan di API level 9.

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 sumber daya Anda menggunakan penentu yang berukuran lebih besar daripada layar saat ini, sistem tidak akan menggunakannya dan aplikasi akan error saat runtime (misalnya, jika semua resource tata letak ditandai dengan penentu xlarge, namun perangkat memiliki ukuran layar normal).

Ditambahkan di API level 4.

Lihat juga bidang konfigurasi screenLayout, yang menunjukkan apakah layar berukuran kecil, normal, atau besar.

Lihat Ringkasan kompatibilitas layar untuk informasi selengkapnya.

Aspek layar long
notlong
  • long: Layar panjang, seperti WQVGA, WVGA, FWVGA
  • notlong: Layar tidak panjang, seperti QVGA, HVGA, dan VGA

Ditambahkan di API level 4.

Ini hanya didasarkan pada rasio aspek layar (layar "panjang" lebih lebar). Ini tidak terkait dengan orientasi layar.

Lihat juga bidang konfigurasi screenLayout, yang menunjukkan apakah layar panjang.

Layar bulat round
notround
  • round: Layar bulat, misalnya perangkat wearable yang bulat
  • notround: Layar persegi panjang, misalnya ponsel atau tablet

Ditambahkan di API level 23.

Lihat juga metode konfigurasi isScreenRound(), yang menunjukkan apakah layar tersebut bulat.

Wide Color Gamut widecg
nowidecg
  • widecg: Menampilkan dengan wide color gamut seperti Tampilan P3 atau AdobeRGB
  • nowidecg: Menampilkan dengan narrow color gamut seperti sRGB

Ditambahkan di API level 26.

Lihat juga metode konfigurasi isScreenWideColorGamut(), yang menunjukkan apakah layar tersebut memiliki wide color gamut.

Rentang Dinamis Tinggi (HDR) highdr
lowdr
  • highdr: Menampilkan dengan rentang dinamis tinggi
  • lowdr: Menampilkan dengan rentang dinamis rendah/standar

Ditambahkan di API level 26.

Lihat juga metode konfigurasi isScreenHdr(), yang menunjukkan apakah layar tersebut memiliki kapabilitas HDR.

Orientasi layar port
land
  • port: Perangkat dalam orientasi potret (vertikal)
  • land: Perangkat dalam orientasi lanskap (horizontal)

Ini bisa berubah selama masa pakai aplikasi Anda jika pengguna memutar layar. Lihat Menangani Perubahan Runtime untuk informasi tentang bagaimana hal ini memengaruhi aplikasi Anda selama runtime.

Lihat juga kolom konfigurasi orientation, yang menunjukkan orientasi perangkat saat ini.

Mode UI car
desk
television
appliance
watch
vrheadset
  • car: Perangkat sedang menampilkan di dok mobil
  • desk: Perangkat sedang menampilkan di dok meja
  • television: Perangkat sedang menampilkan di televisi, yang menyediakan pengalaman "sepuluh kaki" dengan UI-nya pada layar besar yang berada jauh dari pengguna, terutama diorientasikan seputar DPAD atau interaksi non-pointer lainnya
  • appliance: Perangkat berfungsi sebagai alat, tanpa tampilan
  • watch: Perangkat memiliki tampilan dan dikenakan di pergelangan tangan
  • vrheadset: Perangkat ditampilkan dalam headset virtual reality

Ditambahkan dalam API level 8, televisi ditambahkan dalam API 13, jam ditambahkan dalam API 20.

Untuk informasi tentang cara aplikasi merespons saat perangkat dimasukkan ke dalam atau dilepaskan dari dok-nya, bacalah Menentukan dan Memantau Kondisi dan Jenis Dok.

Ini bisa berubah selama masa pakai aplikasi jika pengguna menempatkan perangkat di dok. Anda bisa mengaktifkan atau menonaktifkan sebagian mode ini menggunakan UiModeManager. Lihat Menangani Perubahan Runtime untuk informasi tentang cara hal ini memengaruhi aplikasi Anda selama runtime.

Mode malam night
notnight
  • night: Malam hari
  • notnight: Siang hari

Ditambahkan dalam API level 8.

Ini bisa 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 UiModeManager. Lihat Menangani Perubahan Runtime untuk informasi tentang bagaimana hal ini memengaruhi aplikasi Anda selama runtime.

Kepadatan piksel layar (dpi) ldpi
mdpi
hdpi
xhdpi
xxhdpi
xxxhdpi
nodpi
tvdpi
anydpi
nnndpi
  • ldpi: Layar berkepadatan rendah; sekitar 120 dpi.
  • mdpi: Layar berkepadatan sedang (pada HVGA tradisional); sekitar 160 dpi.
  • hdpi: Layar berkepadatan tinggi; sekitar 240 dpi.
  • xhdpi: Layar berkepadatan ekstra tinggi; sekitar 320 dpi. Ditambahkan di API Level 8
  • xxhdpi: Layar berkepadatan ekstra-ekstra-tinggi; sekitar 480 dpi. Ditambahkan di API Level 16
  • xxxhdpi: Kepadatan ekstra-ekstra-ekstra-tinggi (hanya ikon peluncur, lihat catatan dalam Mendukung Beberapa Layar); sekitar 640dpi. Ditambahkan di API Level 18
  • nodpi: Ini bisa digunakan untuk resource bitmap yang tidak ingin Anda skalakan agar cocok dengan kepadatan perangkat.
  • tvdpi: Layar antara mdpi dan hdpi; sekitar 213 dpi. Ini tidak dianggap sebagai grup kepadatan "utama". Kepadatan ini utamanya ditujukan untuk televisi dan kebanyakan aplikasi tidak memerlukannya—menyediakan resource mdpi dan hdpi sudah cukup untuk sebagian besar aplikasi dan sistem akan menskalakan sebagaimana mestinya. Ditambahkan di API Level 13
  • anydpi: Penentu ini mencocokkan semua kepadatan layar dan diprioritaskan atas penentu lainnya. Berguna bagi vektor drawable. Ditambahkan di API Level 21
  • nnndpi: Digunakan untuk menampilkan kepadatan non-standar, dengan nnn adalah kepadatan layar bilangan bulat positif. Ini seharusnya tidak digunakan dalam banyak kasus. Gunakan bucket kepadatan standar, yang sangat mengurangi overhead untuk mendukung berbagai kepadatan layar perangkat di pasar.

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.

Jika Anda memutuskan bahwa resource gambar tidak terlihat cukup baik di televisi atau perangkat tertentu lainnya dan ingin mencoba resource tvdpi, faktor penskalaannya adalah 1,33*mdpi. Misalnya, gambar resolusi 100 px x 100 px untuk layar mdpi seharusnya menjadi 133 px x 133 px untuk tvdpi.

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 mungkin akan menggunakan resource mana saja yang paling cocok.

Lihat Mendukung Beberapa Layar untuk informasi selengkapnya tentang cara menangani kepadatan layar yang berbeda dan cara Android menurunkan skala bitmap Anda agar sesuai dengan kepadatan saat ini.

Jenis layar sentuh notouch
finger
  • notouch: Perangkat tidak memiliki layar sentuh.
  • finger: Perangkat memiliki layar sentuh yang dimaksudkan untuk digunakan melalui interaksi dengan jari pengguna.

Lihat juga kolom konfigurasi touchscreen, yang menunjukkan jenis layar sentuh pada perangkat.

Ketersediaan keyboard keysexposed
keyshidden
keyssoft
  • keysexposed: Perangkat menyediakan keyboard. Jika perangkat mengaktifkan keyboard virtual (kemungkinan), ini dapat digunakan bahkan saat keyboard hardware tidak diekspos kepada pengguna, meskipun perangkat tidak memiliki keyboard hardware. Jika keyboard software tidak disediakan atau dinonaktifkan, maka ini hanya digunakan bila keyboard hardware diekspos.
  • keyshidden: Perangkat memiliki keyboard hardware yang tersedia tetapi tersembunyi dan perangkat tidak mengaktifkan keyboard virtual.
  • keyssoft: Perangkat mengaktifkan keyboard virtual, baik itu terlihat atau tidak.

Jika Anda menyediakan resource keysexposed, namun bukan resource keyssoft, sistem akan menggunakan resource keysexposed baik saat keyboard terlihat atau tidak, asalkan sistem telah mengaktifkan keyboard virtual.

Ini bisa berubah selama masa pakai aplikasi jika pengguna membuka keyboard hardware. Lihat Menangani Perubahan Runtime untuk informasi tentang cara hal ini memengaruhi aplikasi Anda selama runtime.

Lihat juga kolom konfigurasi hardKeyboardHidden dan keyboardHidden, yang masing-masing menunjukkan visibilitas keyboard hardware dan visibilitas segala jenis keyboard (termasuk keyboard virtual).

Metode input teks utama nokeys
qwerty
12key
  • nokeys: Perangkat tidak memiliki tombol hardware untuk input teks.
  • qwerty: Perangkat memiliki keyboard qwerty hardware, baik terlihat maupun tidak pada pengguna.
  • 12key: Perangkat memiliki keyboard hardware 12 tombol, baik terlihat atau tidak kepada pengguna.

Lihat juga kolom konfigurasi keyboard, yang menunjukkan metode input teks utama yang tersedia.

Versi Platform (API level) Contoh:
v3
v4
v7
dll.

API level yang didukung oleh perangkat. Misalnya, v1 untuk API level 1 (perangkat dengan Android 1.0 atau yang lebih tinggi) dan v4 untuk API level 4 (perangkat dengan Android 1.6 atau yang lebih tinggi). Lihat dokumen API level Android untuk informasi selengkapnya tentang nilai-nilai ini.

Catatan: Sebagian pengontrol kualitas konfigurasi telah ditambahkan sejak Android 1.0, jadi tidak semua versi Android mendukung semua penentu. Menggunakan penentu baru secara implisit akan menambahkan penentu versi platform sehingga perangkat yang lebih lama pasti mengabaikannya. Misalnya, menggunakan penentu w600dp secara otomatis akan 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 informasi selengkapnya, lihat bagian tentang Menyediakan Kompatibilitas Perangkat Terbaik dengan Resource.

Aturan penamaan penentu

Inilah beberapa aturan tentang penggunaan nama pengontrol kualitas konfigurasi:

  • Anda bisa 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. Contoh :
    • Salah: drawable-hdpi-port/
    • Benar: drawable-port-hdpi/
  • Direktori resource alternatif tidak bisa 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 didukung 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 bernama drawable-es-fr/. Sebagai gantinya, Anda memerlukan dua direktori resource, seperti drawable-es/ dan drawable-fr/, yang berisi file yang sesuai. Namun, Anda tidak harus menduplikasi file yang sama di kedua lokasi. Sebagai gantinya, Anda dapat membuat alias ke satu resource. Lihat Membuat resource alias di bawah ini.

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 (dibahas di bawah). 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

Bila memiliki resource yang ingin Anda gunakan untuk lebih dari satu konfigurasi perangkat (namun tidak ingin menyediakannya sebagai resource default), Anda tidak perlu menempatkan resource yang sama di lebih dari satu direktori resource alternatif. Sebagai gantinya, (dalam beberapa kasus) Anda bisa 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 lokal, bahasa Inggris-Kanada dan bahasa Prancis-Kanada, harus menggunakan versi yang sama. Anda mungkin berasumsi bahwa Anda perlu menyalin gambar yang sama ke dalam direktori resource baik untuk bahasa Inggris-Kanada maupun bahasa Prancis-Kanada, namun bukan demikian. Sebagai gantinya, Anda bisa menyimpan gambar yang sama-sama digunakan sebagai icon_ca.png (nama apa saja selain icon.png) dan memasukkannya dalam direktori default res/drawable/. 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>. Hal ini memungkinkan Anda menyimpan satu versi saja dari file PNG dan dua file XML kecil yang menunjuk ke sana. (Contoh file XML ditampilkan di bawah.)

Drawable

Untuk membuat alias ke drawable yang ada, gunakan elemen <drawable>. Contoh:

<?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/), maka file akan dikompilasi menjadi resource yang bisa Anda referensikan sebagai R.drawable.icon, namun 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 ada dalam <merge>. Contoh:

<?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 bisa Anda referensikan sebagai R.layout.main, namun sebenarnya merupakan alias untuk resource R.layout.main_ltr.

String dan nilai-nilai sederhana lainnya

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

<?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 cara kerjanya sama. Misalnya, sebuah warna:

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

Mengakses resource aplikasi Anda

Setelah menyediakan resource dalam aplikasi Anda, Anda bisa menerapkannya dengan mengacu pada ID resource-nya. Semua ID resource didefinisikan di class R proyek Anda, yang dihasilkan oleh fitur aapt secara otomatis.

Bila aplikasi Anda telah dikompilasi, aapt akan menghasilkan class R, yang berisi ID resource untuk semua resource dalam direktori res/ Anda. Untuk setiap jenis resource, terdapat subclass R (misalnya, R.drawable untuk semua resource drawable), dan untuk setiap resource jenis tersebut, terdapat bilangan bulat statis (misalnya, R.drawable.icon). Bilangan bulat ini adalah ID resource yang dapat Anda gunakan untuk mengambil resource.

Walaupun class R adalah tempat menetapkan ID resource, Anda tidak perlu melihat ke sana untuk menemukan ID resource. ID resource selalu terdiri dari:

  • Jenis resource: Setiap resource dikelompokkan ke dalam "jenis", seperti string, drawable, dan layout. Untuk mengetahui selengkapnya tentang berbagai jenis, lihat Jenis Resource.
  • Nama resource, bisa berupa: nama file, tidak termasuk ekstensi; atau nilai dalam atribut android:name XML, jika resource itu sebuah nilai sederhana (misalnya sebuah string).

Ada dua cara untuk mengakses resource:

  • Dalam kode: Menggunakan bilangan bulat statis dari sub-class class R, seperti:
    R.string.hello

    string adalah jenis resource dan hello adalah nama resource. Ada banyak Android API yang bisa mengakses resource Anda bila Anda menyediakan ID resource dengan format ini. Lihat Mengakses Resource dalam Kode.

  • Di XML: Menggunakan sebuah sintaksis XML khusus yang juga berkaitan dengan ID resource yang didefinisikan dalam class R, misalnya:
    @string/hello

    string adalah jenis resource dan hello adalah nama resource. Anda dapat menggunakan sintaksis ini dalam resource XML di mana saja Anda ingin menyediakan sebuah nilai dalam sebuah resource. Lihat Mengakses Resource dari XML.

Mengakses resource dalam kode

Anda bisa menggunakan resource dalam kode dengan menyalurkan ID resource sebagai sebuah parameter metode. Misalnya, Anda bisa 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 bisa mengambil tiap resource dengan menggunakan berbagai metode di Resources, di mana Anda bisa mendapatkan instance dengan getResources().

Sintaksis

Inilah sintaksis untuk mengacu 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).

Lihat Jenis Resource untuk informasi selengkapnya tentang masing-masing jenis resource dan cara mengacunya.

Kasus penggunaan

Ada banyak metode yang menerima parameter ID resource dan Anda bisa mengambil resource dengan menggunakan metode di Resources. Anda bisa mengambil instance Resources dengan Context.getResources().

Berikut adalah 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: Anda tidak boleh mengubah file R.java secara manual karena file tersebut dihasilkan oleh alat aapt saat project Anda dikompilasi. Perubahan apa pun akan ditimpa bila nanti Anda mengompilasi.

Mengakses resource dari XML

Anda bisa mendefinisikan nilai untuk beberapa atribut dan elemen XML dengan menggunakan acuan 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 sebuah Button ke tata letak, Anda harus menggunakan sebuah resource string bagi teks tombolnya:

<Button
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:text="@string/submit" />

Sintaksis

Berikut adalah sintaksis untuk mengacu 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 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).

Lihat Jenis Resource untuk informasi selengkapnya tentang masing-masing jenis resource dan cara mengacunya.

Kasus penggunaan

Dalam beberapa kasus, Anda harus menggunakan resource untuk suatu nilai dalam XML (misalnya, untuk menerapkan gambar yang dapat digambar pada widget), namun Anda juga bisa menggunakan resource di XML mana saja 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 bisa 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 mengacu resource sistem, Anda perlu memasukkan nama paketnya. Contoh:

<?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: Anda harus selalu menggunakan resource string, sehingga 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 Pelokalan.

Anda bahkan bisa 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, namun bisa sangat berguna saat menggunakan resource alternatif. Baca selengkapnya tentang Membuat resource alias.

Mengacu atribut gaya

Resource atribut gaya memungkinkan Anda mengacu nilai suatu atribut dalam tema yang diterapkan saat ini. Dengan mengacu sebuah atribut gaya memungkinkan Anda menyesuaikan tampilan elemen UI dengan menata gayanya agar cocok dengan beragam variasi standar yang dipasok oleh tema saat ini, sebagai ganti memasok nilai yang ditanamkan (hard-coded). Mengacu sebuah atribut gaya pada dasarnya adalah "gunakan gaya yang didefinisikan oleh atribut ini, dalam tema saat ini".

Untuk mereferensikan sebuah atribut gaya, sintaksis namanya hampir sama dengan format resource normal, namun sebagai ganti simbol (@), gunakan sebuah tanda tanya (?), dan bagian jenis resource bersifat opsional. Sebagai contoh:

?[<package_name>:][<resource_type>/]<resource_name>

Misalnya, berikut ini cara Anda mereferensikan suatu 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, maka Anda tidak perlu menyatakan jenisnya secara eksplisit (yang akan berupa ?android:attr/textColorSecondary—Anda bisa mengecualikan jenis attr.

Mengakses file asli

Walaupun tidak lazim, Anda mungkin perlu mengakses file dan direktori asli. Jika demikian, maka menyimpan file Anda di res/ tidak akan berhasil, karena satu-satunya cara untuk membaca resource dari res/ adalah dengan ID resource. Sebagai gantinya, Anda bisa 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, tetapkan acuan 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 menciptakan tata letak sendiri untuk item daftar.

Menyediakan kompatibilitas perangkat terbaik dengan resource

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

Misalnya, jika aplikasi Anda mendukung beberapa bahasa, selalu sertakan direktori values/ (tempat string Anda disimpan) tanpa penentu bahasa dan region. Jika sebaliknya Anda menempatkan semua file string dalam direktori yang memiliki penentu bahasa dan region, maka aplikasi Anda akan error saat berjalan pada perangkat yang telah diatur ke bahasa yang tidak didukung string Anda. Namun asalkan Anda menyediakan resource default values/, aplikasi akan berjalan lancar (meskipun pengguna tidak memahami bahasa itu—ini lebih baik daripada error).

Demikian pula, jika Anda menyediakan resource tata letak berbeda berdasarkan orientasi layar, Anda harus memilih 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, namun mempertahankan kompatibilitas kode dengan versi Android yang lebih lama, maka saat versi lama Android menjalankan aplikasi, aplikasi itu akan error jika Anda tidak menyediakan resource default, karena aplikasi tidak bisa menggunakan resource yang dinamai dengan penentu baru. Misalnya, jika minSdkVersion disetel ke 4, dan Anda memenuhi syarat semua resource drawable dengan menggunakan mode malam (night atau notnight, yang ditambahkan di API Level 8), maka perangkat API level 4 tidak bisa mengakses resource drawable dan akan error. Dalam hal ini, Anda mungkin ingin notnight menjadi resource default, jadi Anda harus mengecualikan penentu itu agar resource drawable ada dalam drawable/ atau drawable-night/.

Jadi, agar bisa menyediakan kompatibilitas perangkat terbaik, sediakan selalu 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 drawable resource alternatif dengan penentu kepadatan layar. Tanpa resource drawable default sekali pun, Android bisa menemukan yang paling cocok di antara kepadatan layar alternatif dan menskalakan bitmap sesuai kebutuhan. Akan tetapi, demi pengalaman terbaik pada semua jenis perangkat, Anda harus menyediakan 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:

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-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. Informasi selengkapnya tersedia dalam dokumen Mendukung Beberapa Layar.

  2. Pilih penentu prioritas (berikutnya) dalam daftar (tabel 2). (Mulai dengan MCC, lalu pindah ke bawah.)
  3. Apakah salah satu direktori resource menyertakan penentu ini?
    • Jika Tidak, kembali ke langkah 2 dan lihat penentu berikutnya. (Dalam contoh, jawabannya adalah "tidak" hingga penentu bahasa tercapai.)
    • Jika Ya, lanjutkan ke langkah 4.
  4. Hapus direktori resource yang tidak termasuk penentu ini. Dalam contoh, sistem 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 kemungkinan akan memperkecil skala gambar asli yang lebih besar daripada meningkatkan skala atas gambar asli yang lebih kecil. Lihat Mendukung Beberapa Layar.

  5. Kembali dan ulangi langkah 2, 3, dan 4 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 aspek lebih lanjut. 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 ("en"), maka setiap direktori resource yang memiliki penentu bahasa akan 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. Misalnya, dalam langkah 4 di atas, 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 tidak masuk.