本頁面由 Cloud Translation API 翻譯而成。

使用已儲存的偏好設定值 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="Your 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 設定的資料儲存庫會覆寫任何會設定為相應的階層在大部分情況下，您應為整個階層