Menggunakan nilai Preference yang tersimpan Bagian dari Android Jetpack.

Dokumen ini menjelaskan cara menyimpan dan menggunakan Nilai Preference yang disimpan oleh pustaka Preference.

Penyimpanan data Preference

Bagian ini menjelaskan bagaimana sebuah Preference dapat menyimpan data.

SharedPreferences

Secara default, Preference menggunakan SharedPreferences untuk menyimpan masing-masing. SharedPreferences API mendukung pembacaan dan penulisan dengan mudah pasangan nilai kunci dari file yang disimpan di seluruh sesi aplikasi. Tujuan Library Preference menggunakan instance SharedPreferences pribadi sehingga hanya aplikasi apa saja yang dapat mengaksesnya.

Sebagai contoh, asumsikan SwitchPreferenceCompat berikut:

<SwitchPreferenceCompat
        app:key="notifications"
        app:title="Enable message notifications"/>

Saat pengguna mengalihkan tombol ini ke "aktif" status, file SharedPreferences pembaruan dengan pasangan nilai kunci "notifications" : "true". Kunci yang digunakan adalah sama dengan kunci yang ditetapkan untuk Preference.

Untuk informasi selengkapnya tentang API SharedPreferences, lihat Menyimpan nilai kunci data.

Untuk mengetahui informasi tentang berbagai cara menyimpan data di Android, lihat Data dan ringkasan penyimpanan file.

PreferenceDataStore

Meskipun library Preference mempertahankan data dengan SharedPreferences dengan default, SharedPreferences tidak selalu merupakan solusi ideal. Misalnya, jika aplikasi mengharuskan pengguna untuk masuk, Anda mungkin ingin pengaturan aplikasi di {i>cloud<i} sehingga pengaturan tercermin di seluruh perangkat dan platform lain. Demikian pula, jika aplikasi Anda memiliki konfigurasi opsi khusus perangkat, setiap pengguna di perangkat memiliki pengaturan terpisah, sehingga SharedPreferences menjadi solusi yang kurang ideal.

PreferenceDataStore memungkinkan Anda menggunakan backend penyimpanan kustom untuk mempertahankan nilai Preference. Untuk selengkapnya informasi selengkapnya, lihat Menggunakan datastore kustom.

Membaca nilai Preferensi

Untuk mengambil objek SharedPreferences yang sedang digunakan, panggil PreferenceManager.getDefaultSharedPreferences(). Meskipun metode ini berfungsi dari mana saja dalam aplikasi Anda, sebaiknya Anda membagi aplikasi menjadi beberapa lapisan. Untuk informasi selengkapnya, lihat Data .

Misalnya, dengan EditTextPreference dengan kunci "signature", seperti berikut ini:

<EditTextPreference
        app:key="signature"
        app:title="Your signature"/>

Anda dapat mengambil nilai tersimpan untuk Preference ini secara global, seperti berikut:

Kotlin

val sharedPreferences = PreferenceManager.getDefaultSharedPreferences(this /* Activity context */)
val name = sharedPreferences.getString("signature", "")

Java

SharedPreferences sharedPreferences =
        PreferenceManager.getDefaultSharedPreferences(this /* Activity context */);
String name = sharedPreferences.getString("signature", "");

Memproses perubahan nilai Preference

Untuk memproses perubahan nilai Preference, Anda dapat memilih antara dua antarmuka:

• Preference.OnPreferenceChangeListener
• SharedPreferences.OnSharedPreferenceChangeListener

Tabel berikut menunjukkan perbedaan antara kedua antarmuka:

OnPreferenceChangeListener	OnSharedPreferenceChangeListener
Ditetapkan pada satu Preference.	Berlaku untuk semua objek Preference.
Dipanggil saat Preference akan mengubah nilai tersimpannya, meskipun nilai yang tertunda sama dengan nilai yang disimpan.	Hanya dipanggil saat nilai yang disimpan untuk Preference berubah.
Hanya dipanggil melalui library Preference. Bagian terpisah aplikasi dapat mengubah nilai yang disimpan.	Dipanggil setiap kali nilai tersimpan berubah, meskipun berasal dari blok terpisah dari aplikasi.
Dipanggil sebelum nilai tertunda disimpan.	Dipanggil setelah nilai disimpan.
Dipanggil saat menggunakan SharedPreferences atau PreferenceDataStore.	Hanya dipanggil saat menggunakan SharedPreferences.

Mengimplementasikan OnPreferenceChangeListener

Dengan menerapkan OnPreferenceChangeListener, Anda dapat memproses panggilan ubah ke nilai Preference. Kemudian, Anda dapat memvalidasi apakah perubahan apa yang terjadi. Misalnya, kode berikut menunjukkan cara memproses perubahan pada nilai EditTextPreference dengan kunci "name":

Kotlin

override fun onPreferenceChange(preference: Preference, newValue: Any): Boolean {
    Log.e("preference", "Pending Preference value is: $newValue")
    return true
}

Java

@Override
public boolean onPreferenceChange(Preference preference, Object newValue) {
    Log.e("preference", "Pending Preference value is: " + newValue);
    return true;
}

Selanjutnya, Anda perlu mengatur pemroses ini secara langsung dengan setOnPreferenceChangeListener(), sebagai berikut:

Kotlin

preference.onPreferenceChangeListener = ...

Java

preference.setOnPreferenceChangeListener(...);

Mengimplementasikan OnSharedPreferenceChangeListener

Jika nilai Preference dipertahankan menggunakan SharedPreferences, Anda juga dapat menggunakan SharedPreferences.OnSharedPreferenceChangeListener untuk memproses perubahan. Hal ini memungkinkan Anda memproses kapan nilai yang disimpan oleh Preference Anda berubah, seperti saat menyinkronkan setelan dengan server. Contoh berikut menunjukkan cara proses perubahan nilai EditTextPreference dengan kunci "name":

Kotlin

override fun onSharedPreferenceChanged(sharedPreferences: SharedPreferences, key: String) {
    if (key == "signature") {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""))
    }
}

Java

@Override
public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {
    if (key.equals("signature")) {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""));
    }
}

Mendaftarkan pemroses menggunakan registerOnSharedPreferenceChangedListener(), sebagai berikut:

Kotlin

preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(...)

Java

getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(...);

Peringatan: Untuk mencegah pembersihan sampah memori yang tidak diinginkan, simpan referensi yang kuat ke pemroses. Saat Anda memanggil registerOnSharedPreferenceChangeListener(), SharedPreferenceManager tidak menyimpan referensi yang kuat ke pemroses. Kepada mengatasi masalah ini, Anda dapat menerapkan onSharedPreferenceChanged() secara langsung di PreferenceFragmentCompat. Anda juga dapat membuat variabel instance, seperti yang ditunjukkan pada contoh berikut:

Kotlin

    val listener: SharedPreferences.OnSharedPreferenceChangeListener =
            SharedPreferences.OnSharedPreferenceChangeListener {...}
    

Java

    SharedPreferences.OnSharedPreferenceChangeListener listener =
            new SharedPreferences.OnSharedPreferenceChangeListener() {...}
    

Untuk pengelolaan siklus proses yang tepat di Activity atau Fragment, daftar dan batalkan pendaftaran pemroses ini di callback onResume() dan onPause(), seperti yang ditampilkan dalam contoh berikut:

Kotlin

override fun onResume() {
    super.onResume()
    preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(this)
}

override fun onPause() {
    super.onPause()
    preferenceManager.sharedPreferences.unregisterOnSharedPreferenceChangeListener(this)
}

Java

@Override
public void onResume() {
    super.onResume();
    getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(this);
}

@Override
public void onPause() {
    super.onPause();
    getPreferenceManager().getSharedPreferences().unregisterOnSharedPreferenceChangeListener(this);
}

Menggunakan datastore kustom

Meskipun kami merekomendasikan untuk mempertahankan objek Preference menggunakan SharedPreferences, Anda juga dapat menggunakan datastore kustom. Datastore kustom dapat berguna jika aplikasi menyimpan nilai ke database atau jika nilai bersifat khusus perangkat, yang ditunjukkan dalam contoh berikut.

Mengimplementasikan datastore

Untuk mengimplementasikan datastore kustom, buat class yang memperluas PreferenceDataStore. Contoh berikut membuat datastore yang menangani Nilai String:

Kotlin

class DataStore : PreferenceDataStore() {
    override fun putString(key: String, value: String?) {
        // Save the value somewhere.
    }

    override fun getString(key: String, defValue: String?): String? {
        // Retrieve the value.
    }
}

Java

public class DataStore extends PreferenceDataStore {
    @Override
    public void putString(String key, @Nullable String value) {
        // Save the value somewhere.
    }
    @Override
    @Nullable
    public String getString(String key, @Nullable String defValue) {
        // Retrieve the value.
    }
}

Catatan: Hanya ganti metode yang digunakan oleh objek Preference. Menelepon metode yang tidak Anda implementasikan menghasilkan UnsupportedOperationException.

Jalankan operasi apa pun yang memakan waktu lama di luar thread utama untuk menghindari pemblokiran pengguna dalam antarmuka berbasis web yang sederhana. Karena Fragment atau Activity mungkin saja berisi variabel datastore akan dihancurkan sambil mempertahankan nilai, lalu lakukan serialisasi data tersebut agar tidak kehilangan nilai apa pun yang diubah oleh pengguna.

Mengaktifkan datastore

Setelah Anda mengimplementasikan datastore, tetapkan datastore baru di onCreatePreferences() sehingga objek Preference dapat mempertahankan nilai dengan datastore daripada menggunakan SharedPreferences default. Anda dapat mengaktifkan datastore untuk setiap Preference atau untuk seluruh hierarki.

Guna mengaktifkan datastore kustom untuk Preference tertentu, panggil setPreferenceDataStore() di Preference, seperti yang ditunjukkan dalam contoh berikut:

Kotlin

val preference: Preference? = findPreference("key")
preference?.preferenceDataStore = dataStore

Java

Preference preference = findPreference("key");
if (preference != null) {
    preference.setPreferenceDataStore(dataStore);
}

Guna mengaktifkan datastore kustom untuk seluruh hierarki, panggil setPreferenceDataStore() pada PreferenceManager:

Kotlin

val preferenceManager = preferenceManager
preferenceManager.preferenceDataStore = dataStore

Java

PreferenceManager preferenceManager = getPreferenceManager();
preferenceManager.setPreferenceDataStore(dataStore);

{i>Datastore<i} yang ditetapkan untuk Preference tertentu akan menggantikan {i>datastore<i} yang ditetapkan untuk hierarki yang sesuai. Dalam kebanyakan kasus, Anda menetapkan datastore untuk seluruh hierarki.

Catatan: Jika Anda menetapkan datastore untuk Preference setelah Preference yang melekat pada hierarki, nilai awal untuk Preference tidak disebarkan lagi.