如要儲存少量鍵/值,則應使用 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);