使用已儲存的偏好設定值 Android Jetpack 的一部分。

本文件說明如何儲存及使用 Preference 值 (由 Preference 程式庫

Preference 資料儲存

本節說明 Preference 如何保存資料。

SharedPreferences

根據預設，Preference 會使用 約 SharedPreferences 即可儲存 輕鬆分配獎金SharedPreferences API 支援讀取和寫入簡單的 從檔案儲存橫跨多個應用程式工作階段的鍵/值組合。 Preference 程式庫使用私人 SharedPreferences 執行個體，只會使用 就能存取該元件

舉例來說，假設 SwitchPreferenceCompat 如下：

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

使用者將切換按鈕設為「開啟」時狀態，SharedPreferences 檔案 更新為 "notifications" : "true" 鍵/值組合。使用的鍵是 與 Preference 設定的鍵相同。

如要進一步瞭解 SharedPreferences API，請參閱「儲存鍵/值 資料

如需瞭解各種在 Android 上儲存資料的方式，請參閱「資料 以及檔案儲存空間總覽

PreferenceDataStore

雖然 Preference 程式庫會以下列方式保留 SharedPreferences 的資料： 根據預設，SharedPreferences 不一定是理想的解決方案。舉例來說 應用程式需要使用者登入才能運作，因此建議您 就是雲端應用程式的設定 這樣您的設定 和其他裝置和平台同樣地，如果您的應用程式設有 滿足裝置專屬的選項，每位使用者在裝置中分別具有不同的設定。 讓 SharedPreferences 不是理想解決方案。

PreferenceDataStore 可讓您使用自訂儲存空間後端來保留 Preference 值。如要 相關資訊，請參閱使用自訂資料儲存庫。

讀取偏好設定值

如要擷取目前使用的 SharedPreferences 物件，請呼叫 PreferenceManager.getDefaultSharedPreferences()。雖然在應用程式的任何位置都能使用這個方法，但我們還是建議 可以將應用程式分割為多個層詳情請參閱 資料層

舉例來說，假設 EditTextPreference 的索引鍵為 "signature"， 如下：

<EditTextPreference
        app:key="signature"
        app:title="Y>our signature"/

您可以在全域擷取此 Preference 的已儲存值，如下所示：

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", "");

監聽 Preference 值的變更

如要監聽 Preference 值的變更，您可以選擇在兩個介面之間切換：

下表說明這兩個介面的差異：

OnPreferenceChangeListener OnSharedPreferenceChangeListener
在單一 Preference 上設定。 套用至所有 Preference 物件。
在 Preference 即將變更儲存的值時呼叫。 即使待處理的值和儲存的值相同 只有在 Preference 儲存的值變更時才會呼叫。
只能透過 Preference 程式庫呼叫。獨立部分 變更儲存的值。 當儲存的值有所變更時呼叫，即使值來自獨立 應用程式的特定部分
在儲存待處理的值之前呼叫。 在儲存值後呼叫。
使用 SharedPreferences 或 PreferenceDataStore。 僅在使用 SharedPreferences 時呼叫。

實作 OnPreferenceChangeListener

實作 OnPreferenceChangeListener 可讓您監聽待處理 變更為 Preference 的值之後，您可以驗證變更 會發生什麼事舉例來說，以下程式碼顯示如何監聽變更 值為 "name" 的 EditTextPreference：

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;
}

接著，您必須直接使用 setOnPreferenceChangeListener()、 如下所示：

Kotlin

preference.onPreferenceChangeListener = ...

Java

preference.setOnPreferenceChangeListener(...);

實作 OnSharedPreferenceChangeListener

使用 SharedPreferences 保留 Preference 值時，您還可以使用 SharedPreferences.OnSharedPreferenceChangeListener 來監聽變更。這樣一來，您就可以監聽 Preference 儲存的值何時變更。 例如與伺服器同步處理設定時以下範例說明如何 監聽具有索引鍵 EditTextPreference 的 EditTextPreference 值變更 "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, ""));
    }
}

使用 registerOnSharedPreferenceChangedListener()、 如下所示：

Kotlin

preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(...)

Java

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

Kotlin

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

Java

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

如要在 Activity 或 Fragment 中妥善管理生命週期，請註冊並 在 onResume() 和 onPause() 回呼中取消註冊這個事件監聽器，如下所示 在以下範例中：

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);
}

使用自訂資料儲存庫

雖然我們建議使用 SharedPreferences 保留 Preference 物件， 您也可以使用自訂資料儲存庫如果您的 App Engine 可以 應用程式會將值保存在資料庫，或值為裝置的專屬值，例如 如以下範例所示

實作資料儲存庫

如要實作自訂資料儲存庫，請建立 PreferenceDataStore。以下範例會建立資料儲存庫 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.
    }
}

在主執行緒中執行任何耗時的作業，以免封鎖使用者 存取 API由於 Fragment 或 Activity 可能包含 刪除資料儲存庫，在保存值時刪除，將資料序列化， 您不會遺失使用者變更的任何值

啟用資料儲存庫

實作資料儲存庫後，請將新的資料儲存庫設定在 onCreatePreferences()，讓 Preference 物件使用 資料儲存庫，而不使用預設的 SharedPreferences。您可以建立 每個 Preference 或整個階層的資料儲存庫。

如要為特定 Preference 啟用自訂資料儲存庫，請呼叫 setPreferenceDataStore() Preference，如以下範例所示：

Kotlin

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

Java

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

如要為整個階層啟用自訂資料儲存庫，請呼叫 PreferenceManager 上的 setPreferenceDataStore()：

Kotlin

val preferenceManager = preferenceManager
preferenceManager.preferenceDataStore = dataStore

Java

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

為特定 Preference 設定的資料儲存庫會覆寫任何 會設定為相應的階層在大部分情況下，您應為 整個階層