Mulai 27 Maret 2025, sebaiknya gunakan android-latest-release, bukan aosp-main, untuk mem-build dan berkontribusi pada AOSP. Untuk mengetahui informasi selengkapnya, lihat Perubahan pada AOSP.

Halaman ini diterjemahkan oleh Cloud Translation API.

Arsitektur informasi

Android 8.0 memperkenalkan arsitektur informasi baru untuk aplikasi Setelan guna menyederhanakan cara setelan diatur dan memudahkan pengguna menemukan setelan dengan cepat untuk menyesuaikan perangkat Android mereka. Android 9 memperkenalkan beberapa peningkatan untuk menyediakan lebih banyak fungsi Setelan dan penerapan yang lebih mudah.

Contoh dan sumber

Sebagian besar halaman di Setelan saat ini diimplementasikan menggunakan framework baru. Contoh yang baik adalah DisplaySettings: packages/apps/Settings/src/com/android/settings/DisplaySettings.java

Jalur file untuk komponen penting tercantum di bawah:

CategoryKey: packages/SettingsLib/src/com/android/settingslib/drawer/CategoryKey.java
DashboardFragmentRegistry: packages/apps/Settings/src/com/android/settings/dashboard/DashboardFragmentRegistry.java
DashboardFragment: packages/apps/Settings/src/com/android/settings/dashboard/DashboardFragment.java
AbstractPreferenceController: frameworks/base/packages/SettingsLib/src/com/android/settingslib/core/AbstractPreferenceController.java
BasePreferenceController (diperkenalkan di Android 9): packages/apps/Settings/src/com/android/settings/core/BasePreferenceController.java

Implementasi

Produsen perangkat dianjurkan untuk menyesuaikan arsitektur informasi Setelan yang ada dan menyisipkan halaman setelan tambahan sesuai kebutuhan untuk mengakomodasi fitur khusus partner. Memindahkan preferensi dari halaman lama (diterapkan sebagai SettingsPreferencePage) ke halaman baru (diterapkan menggunakan DashboardFragment) bisa jadi rumit. Preferensi dari halaman lama kemungkinan tidak diterapkan dengan PreferenceController.

Jadi, saat memindahkan preferensi dari halaman lama ke halaman baru, Anda perlu membuat PreferenceController dan memindahkan kode ke pengontrol sebelum membuat instance di DashboardFragment baru. API yang diperlukan PreferenceController dijelaskan dalam namanya dan didokumentasikan dalam Javadoc.

Sangat disarankan untuk menambahkan pengujian unit untuk setiap PreferenceController. Jika perubahan dikirimkan ke AOSP, pengujian unit diperlukan. Untuk mendapatkan informasi selengkapnya tentang cara menulis pengujian berbasis Robolectric, lihat file readme packages/apps/Settings/tests/robotests/README.md.

Arsitektur informasi gaya plugin

Setiap item setelan diterapkan sebagai Preferensi. Preferensi dapat dengan mudah dipindahkan dari satu halaman ke halaman lain.

Untuk mempermudah pemindahan beberapa setelan, Android 8.0 memperkenalkan fragmen host gaya plugin yang berisi item setelan. Item setelan dimodelkan sebagai pengontrol gaya plugin. Oleh karena itu, halaman setelan dibuat oleh fragmen host tunggal dan beberapa pengontrol setelan.

DashboardFragment

DashboardFragment adalah host pengontrol preferensi gaya plugin. Fragmen ini diwarisi dari PreferenceFragment dan memiliki hook untuk meluaskan dan memperbarui daftar preferensi statis dan daftar preferensi dinamis.

Preferensi statis

Daftar preferensi statis ditentukan dalam XML menggunakan tag <Preference>. Implementasi DashboardFragment menggunakan metode getPreferenceScreenResId() untuk menentukan file XML mana yang berisi daftar preferensi statis yang akan ditampilkan.

Preferensi dinamis

Item dinamis merepresentasikan kartu dengan maksud, yang mengarah ke Aktivitas eksternal atau internal. Biasanya, maksud pengguna mengarah ke halaman setelan yang berbeda. Misalnya, item setelan "Google" di halaman beranda Setelan adalah item dinamis. Item dinamis ditentukan dalam AndroidManifest (dibahas di bawah) dan dimuat melalui FeatureProvider (didefinisikan sebagai DashboardFeatureProvider).

Setelan dinamis lebih berat daripada setelan yang dikonfigurasi secara statis, jadi biasanya developer harus menerapkan setelan sebagai setelan statis. Namun, setelan dinamis dapat berguna jika salah satu kondisi berikut berlaku:

Setelan tidak diterapkan secara langsung di aplikasi Setelan (seperti menyuntikkan setelan yang diterapkan oleh aplikasi OEM/Operator).
Setelan akan muncul di halaman beranda Setelan.
Anda sudah memiliki Aktivitas untuk setelan dan tidak ingin menerapkan konfigurasi statis tambahan.

Untuk mengonfigurasi Aktivitas sebagai setelan dinamis, lakukan hal berikut:

Tandai aktivitas sebagai setelan dinamis dengan menambahkan intent-filter ke aktivitas.
Memberi tahu aplikasi Setelan kategori yang sesuai. Kategori adalah konstanta, yang ditentukan dalam CategoryKey.
Opsional: Tambahkan teks ringkasan saat setelan ditampilkan.

Berikut adalah contoh yang diambil dari aplikasi Setelan untuk DisplaySettings.

<activity android:name="Settings$DisplaySettingsActivity"
                   android:label="@string/display_settings"
                   android:icon="@drawable/ic_settings_display">
             <!-- Mark the activity as a dynamic setting -->
              <intent-filter>
                     <action android:name="com.android.settings.action.IA_SETTINGS" />
              </intent-filter>
             <!-- Tell Settings app which category it belongs to -->
              <meta-data android:name="com.android.settings.category"
                     android:value="com.android.settings.category.ia.homepage" />
             <!-- Add a summary text when the setting is displayed -->
              <meta-data android:name="com.android.settings.summary"
                     android:resource="@string/display_dashboard_summary"/>
             </activity>

Pada waktu rendering, fragmen akan meminta daftar Preferensi dari XML statis dan setelan dinamis yang ditentukan di AndroidManifest. Baik PreferenceController ditentukan dalam kode Java atau dalam XML, DashboardFragment mengelola logika penanganan setiap setelan melalui PreferenceController (dibahas di bawah). Kemudian, daftar tersebut ditampilkan di UI sebagai daftar campuran.

PreferenceController

Ada perbedaan antara penerapan PreferenceController di Android 9 dan Android 8.x, seperti yang dijelaskan di bagian ini.

PreferenceController dalam rilis Android 9

PreferenceController berisi semua logika untuk berinteraksi dengan preferensi, termasuk menampilkan, memperbarui, mengindeks penelusuran, dll.

Antarmuka PreferenceController ditentukan sebagai BasePreferenceController. Misalnya, lihat kode di packages/apps/Settings/src/com/android/settings/core/ BasePreferenceController.java

Ada beberapa subclass BasePreferenceController, yang masing-masing dipetakan ke gaya UI tertentu yang didukung aplikasi Setelan secara default. Misalnya, TogglePreferenceController memiliki API yang secara langsung memetakan cara pengguna harus berinteraksi dengan UI preferensi berbasis tombol.

BasePreferenceController memiliki API seperti getAvailabilityStatus(), displayPreference(), handlePreferenceTreeClicked(),, dll. Dokumentasi mendetail untuk setiap API ada di class antarmuka.

Batasan dalam menerapkan BasePreferenceController (dan subkelasnya seperti TogglePreferenceController) adalah tanda tangan konstruktor harus cocok dengan salah satu dari berikut ini:

public MyController(Context context, String key) {}
public MyController(Context context) {}

Saat menginstal preferensi ke fragmen, dasbor menyediakan metode untuk melampirkan PreferenceController sebelum waktu tampilan. Pada waktu penginstalan, pengontrol terhubung ke fragmen sehingga semua peristiwa relevan mendatang dikirim ke pengontrol.

DashboardFragment menyimpan daftar PreferenceController di layar. Di onCreate() fragmen, semua pengontrol dipanggil untuk metode getAvailabilityStatus(), dan jika menampilkan nilai benar, displayPreference() dipanggil untuk memproses logika tampilan. getAvailabilityStatus() juga penting untuk memberi tahu framework Setelan item mana yang tersedia selama penelusuran.

PreferenceController di rilis Android 8.x

PreferenceController berisi semua logika untuk berinteraksi dengan preferensi, termasuk menampilkan, memperbarui, mengindeks penelusuran, dll.

Sesuai dengan interaksi preferensi, antarmuka PreferenceController memiliki API isAvailable(), displayPreference(), handlePreferenceTreeClicked(), dll. Dokumentasi mendetail tentang setiap API dapat ditemukan di class antarmuka.

DashboardFragment menyimpan daftar PreferenceControllers di layar. Di onCreate() fragmen, semua pengontrol dipanggil untuk metode isAvailable(), dan jika menampilkan nilai benar, displayPreference() dipanggil untuk memproses logika tampilan.

Menggunakan DashboardFragment

Memindahkan preferensi dari halaman A ke B

Jika preferensi tercantum secara statis dalam file XML preferensi halaman asli, ikuti prosedur pemindahan Statis untuk rilis Android Anda di bawah. Jika tidak, ikuti prosedur pemindahan Dinamis untuk rilis Android Anda.

Perpindahan statis di Android 9

Temukan file XML preferensi untuk halaman asli dan halaman tujuan. Anda dapat menemukan informasi ini dari metode getPreferenceScreenResId() halaman.
Hapus preferensi dari XML halaman asli.
Tambahkan preferensi ke XML halaman tujuan.
Hapus PreferenceController untuk preferensi ini dari implementasi Java halaman asli. Biasanya dalam createPreferenceControllers(). Pengontrol dapat dideklarasikan langsung di XML.
Catatan: Preferensi mungkin tidak memiliki PreferenceController.
Buat instance PreferenceController di createPreferenceControllers() halaman tujuan. Jika PreferenceController ditentukan dalam XML di halaman lama, tentukan dalam XML untuk halaman baru juga.

Pemindahan dinamis di Android 9

Temukan kategori yang menghosting halaman asli dan tujuan. Anda dapat menemukan informasi ini di DashboardFragmentRegistry.
Buka file AndroidManifest.xml yang berisi setelan yang perlu Anda pindahkan dan temukan entri Aktivitas yang merepresentasikan setelan ini.
Tetapkan nilai metadata aktivitas untuk com.android.settings.category ke kunci kategori halaman baru.

Pemindahan statis di rilis Android 8.x

Temukan file XML preferensi untuk halaman asli dan halaman tujuan.

getPreferenceScreenResId()

Hapus preferensi di XML halaman asli.
Tambahkan preferensi ke XML halaman tujuan.
Hapus PreferenceController untuk preferensi ini di penerapan Java halaman asli. Biasanya dalam getPreferenceControllers().

Catatan: Ada kemungkinan preferensi tidak memiliki PreferenceController.

Buat instance PreferenceController di getPreferenceControllers() halaman tujuan.

Pemindahan dinamis dalam rilis Android 8.x

Temukan kategori yang menghosting halaman asli dan tujuan. Anda dapat menemukan informasi ini di DashboardFragmentRegistry.
Buka file AndroidManifest.xml yang berisi setelan yang perlu Anda pindahkan dan temukan entri Aktivitas yang merepresentasikan setelan ini.
Ubah nilai metadata aktivitas untuk com.android.settings.category, tetapkan titik nilai ke kunci kategori halaman baru.

Membuat preferensi baru di halaman

Jika preferensi tercantum secara statis dalam file XML preferensi halaman asli, ikuti prosedur statis di bawah. Jika tidak, ikuti prosedur dinamis.

Membuat preferensi statis

Temukan file XML preferensi untuk halaman. Anda dapat menemukan informasi ini dari metode getPreferenceScreenResId() halaman.
Tambahkan item Preferensi baru di XML. Pastikan item memiliki android:key yang unik.
Tentukan PreferenceController untuk preferensi ini dalam metode getPreferenceControllers() halaman.
- Di Android 8.x dan secara opsional di Android 9, buat instance PreferenceController untuk preferensi ini dalam metode createPreferenceControllers() halaman.
  Jika preferensi ini sudah ada di tempat lain, kemungkinan sudah ada PreferenceController untuk preferensi tersebut. Anda dapat menggunakan kembali PreferenceController tanpa membuat yang baru.
- Mulai Android 9, Anda dapat memilih untuk mendeklarasikan PreferenceController dalam XML di samping preferensi. Contoh:
```
<Preference
        android:key="reset_dashboard"
        android:title="@string/reset_dashboard_title"
        settings:controller="com.android.settings.system.ResetPreferenceController"/>
```

Membuat preferensi dinamis

Temukan kategori yang menghosting halaman asli dan tujuan. Anda dapat menemukan informasi ini di DashboardFragmentRegistry.
Buat Aktivitas baru di AndroidManifest
Tambahkan metadata yang diperlukan ke Aktivitas baru untuk menentukan setelan. Tetapkan nilai metadata untuk com.android.settings.category ke nilai yang sama yang ditentukan di langkah 1.

Buat halaman baru

Buat fragmen baru, yang diwarisi dari DashboardFragment.
Tentukan kategorinya di DashboardFragmentRegistry.
Catatan: Langkah ini bersifat opsional. Jika Anda tidak memerlukan preferensi dinamis apa pun di halaman ini, Anda tidak perlu memberikan kunci kategori.
Ikuti langkah-langkah untuk menambahkan setelan yang diperlukan untuk halaman ini. Untuk mengetahui informasi selengkapnya, lihat bagian Implementasi.

Validasi

Jalankan pengujian robolectric di Setelan. Semua pengujian yang ada dan baru harus berhasil.
Buat dan instal Setelan, lalu buka halaman yang sedang diubah secara manual. Halaman akan segera diperbarui.

Arsitektur informasi Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.