儲存鍵/值資料

如要儲存少量鍵/值，則應使用 SharedPreferences API。SharedPreferences 物件會指向包含鍵/值對的檔案，並提供讀取和寫入的簡易方法。每個 SharedPreferences 檔案都由架構管理，可設定為不公開或共用。

本頁面將說明如何使用 SharedPreferences API 儲存及擷取簡易值。

注意：SharedPreferences API 是用來讀取及寫入鍵/值組合，請勿與 Preference API 混淆，儘管 SharedPreferences 也能儲存使用者設定，但 Preference API 的功能是用來協助建構應用程式設定的使用者介面。如需瞭解 Preference API，請參閱「設定開發人員指南」。

取得共用偏好設定

如要建立新共用偏好設定檔案，或是存取現有檔案，請擇一使用下列方法：

  • getSharedPreferences() — 如果需要多個共用偏好設定檔，並能以不同名稱辨識，請使用第一個參數指定。在應用程式中，您可以隨意使用 Context 呼叫這個方法。
  • getPreferences() — 如果只需要使用一個共用偏好設定檔，請使用 Activity。這個方法會擷取相對應的預設共用偏好設定，因此不需要設定不同檔名。

舉例來說，以下程式碼會存取共用偏好設定檔，資源字串 R.string.preference_file_key 已識別並使用私人模式開啟該檔案，因此只有應用程式可以存取它：

Kotlin

val sharedPref = activity?.getSharedPreferences(
        getString(R.string.preference_file_key), Context.MODE_PRIVATE)

Java

Context context = getActivity();
SharedPreferences sharedPref = context.getSharedPreferences(
        getString(R.string.preference_file_key), Context.MODE_PRIVATE);

命名共用偏好設定檔時，請務必使用應用程式可明確識別的名稱。其實只要將檔名加上應用程式 ID 即可。例如："com.example.myapp.PREFERENCE_FILE_KEY"

如果只需要一個共用偏好設定檔，您可以使用 getPreferences() 方法作為替代方案：

Kotlin

val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE)

Java

SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);

注意：自 API 級別 17 起，MODE_WORLD_READABLE 和 MODE_WORLD_WRITEABLE 模式已遭淘汰。從 Android 7.0 (API 級別 24) 開始，如有需要，Android 提供使用者 SecurityException 方法。如果您的應用程式需要與其他程式共用私人檔案，方法 FileProvider 與 FLAG_GRANT_READ_URI_PERMISSION 可搭配使用。如需進一步瞭解，請參閱共用檔案。

如果您儲存應用程式設定時，是使用 SharedPreferences API，則應改用 getDefaultSharedPreferences() 以取得應用程式完整的預設共用偏好設定檔案。如需進一步瞭解，請參閱「設定開發人員指南」。

寫入共用偏好設定

如要寫入共用偏好設定檔案，請在 SharedPreferences 上呼叫 edit() 來建立 SharedPreferences.Editor。

注意：在 EncryptedSharedPreferences 物件上呼叫 edit() 方法，而非 SharedPreferences 物件，這樣能讓您以更安全的方式編輯共用偏好設定。如需進一步瞭解，請參閱如何「更安全地處理資料」指南。

透過 putInt() 和 putString() 等方法，傳送要寫入的鍵和值。然後呼叫 apply() 或 commit() 以儲存變更。例如：

Kotlin

val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return
with (sharedPref.edit()) {
    putInt(getString(R.string.saved_high_score_key), newHighScore)
    apply()
}

Java

SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
SharedPreferences.Editor editor = sharedPref.edit();
editor.putInt(getString(R.string.saved_high_score_key), newHighScore);
editor.apply();

apply() 會立即變更記憶體內的 SharedPreferences 物件，但並非同步將更新寫入磁碟。如需同步寫入，請改用 commit()。由於 commit() 具有同步功能，如果使用主執行緒呼叫，可能會導致 UI 轉譯作業暫停。

讀取共用偏好設定

如要從共用偏好設定檔案擷取值，可以使用 getInt() 和 getString() 等方法呼叫，並提供與所需值相對應的鍵；此外，在沒有鍵的情況下，則會回傳預設值。例如：

Kotlin

val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return
val defaultValue = resources.getInteger(R.integer.saved_high_score_default_key)
val highScore = sharedPref.getInt(getString(R.string.saved_high_score_key), defaultValue)

Java

SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
int defaultValue = getResources().getInteger(R.integer.saved_high_score_default_key);
int highScore = sharedPref.getInt(getString(R.string.saved_high_score_key), defaultValue);