```kotlin= // 取得 SharedPreferences 實例，"MyPrefs" 為檔名 val prefs = getSharedPreferences(name: String, mode: Int) val prefs = getSharedPreferences("MyPrefs", Context.MODE_PRIVATE) ``` - getSharedPreferences(): 取得或建立一個 SharedPreferences 實例，需填入檔案名稱及存取模式做為參數。 - Context.MODE_PRIVATE: 此模式代表資料只對本應用程式可見，如果檔案不存在會自動建立，是getSharedPreferences()最常用的模式。

其他的模式(不推薦使用，僅作為補充資訊)

- MODE_APPEND（舊版）: 將資料追加到已存在檔案的末尾。實際使用上很少見，容易造成資料混亂。 - MODE_WORLD_READABLE / MODE_WORLD_WRITEABLE（舊版，不推薦）允許其他應用讀取或寫入此 SharedPreferences。因為安全風險，從 Android 7.0 開始已不再支援。 - MODE_MULTI_PROCESS（舊版，有限支持）允許多個進程讀取同一份 SharedPreferences。實務上不穩定，官方建議使用 ContentProvider 或 DataStore 代替。

步驟1：取得 SharedPreferences.Editor

想要進行寫入，必須先拿到SharedPreferences.Editor物件 ```kotlin= // 取得必須先拿到SharedPreferences val prefs = getSharedPreferences("MyPrefs", Context.MODE_PRIVATE) // 從SharedPreferences取得SharedPreferences.Editor物建 val editor = prefs.edit() ``` - edit():會回傳 SharedPreferences.Editor，用它來修改或新增鍵值對。

步驟2：使用 putXXX() 寫入資料

SharedPreferences 支援基本資料類型 ```kotlin= editor.putString("username", "PU") // 儲存字串 editor.putInt("age", 28) // 儲存整數 editor.putBoolean("isFirstRun", true) // 儲存布林值 editor.putFloat("score", 95.5f) // 儲存浮點數 editor.putLong("userId", 123456L) // 儲存長整數 ```

步驟3：提交資料

提交資料有分兩種commit()和apply() - commit(): 同步操作，會立即寫入磁碟，但因是同步，所以會阻塞主線程，==完成後會回傳一個Boolean值表示是否成功==。 - 適合場景：需要確保資料已經寫入磁碟，例如重要設定或登出時立即清除敏感資訊。 ```kotlin= val isSuccess = prefs.edit().putString("username", "PU").commit() ``` - apply(): 非同步操作，會在背景寫入磁碟，不阻塞主線程，不回傳結果，因此無法立即得知是否寫入成功。 ```kotlin= prefs.edit().putString("username", "PU").apply() ```

apply() VS commit()

SharedPreferences 異動資料後，必需呼叫 apply() 或 commit() 資料才會實際寫入檔案。 - apply():此方法是將要修改的資料提交到記憶體，再使用非同步方法寫入硬碟，因此效率較高，但並不保證資料一定寫入成功。此外，apply()不會回傳值，執行失敗也不會顯示任何訊息。因此在某些特定情況下，資料並沒有正確寫入到硬碟，開發人員也很難發現此問題，建議在主線程中使用。 - commit():此方法會同步將資料寫入硬碟，因此在多執行緒使用時，會互相等待commit()執行完成，因此效率較差。此外，commit()會回傳 boolean 值，表示本次修改是否提交成功，對資料是否正確寫入至硬碟有比較高的保障。 ※參見參考資料: [SharedPreferences 的commit和apply分析](https://blog.csdn.net/u010198148/article/details/51706483) [Android儲存資料--使用SharedPreferences](https://blog.tarswork.com/post/android-storage-using-shared-preferences/)

進階

可以採用[ScopeFunction](https://hackmd.io/@9YAtszqXS2OLNZOrLY_-Jg/kotlin_ScopeFunction#apply)(推薦使用)或鍊式呼叫來一次大量提交 ScopeFunction ```kotlin= val prefs = getSharedPreferences("MyPrefs", Context.MODE_PRIVATE) // 使用 Kotlin apply { } 進入 Editor 的作用域 prefs.edit().apply { putString("username", "PU") putInt("age", 28) putBoolean("isFirstRun", true) putFloat("score", 95.5f) putLong("userId", 123456L) apply() // 提交修改 } ``` 鍊式呼叫: ```kotlin= val prefs = getSharedPreferences("MyPrefs", Context.MODE_PRIVATE) // 直接鍊式呼叫 putXXX()，最後 apply() 提交 prefs.edit() .putString("username", "PU") .putInt("age", 28) .putBoolean("isFirstRun", true) .putFloat("score", 95.5f) .putLong("userId", 123456L) .apply() // 非同步提交 ```

SharedPreferences 提供 getXXX() 方法，依資料類型不同使用不同方法: ```kotlin= val prefs = getSharedPreferences("MyPrefs", Context.MODE_PRIVATE) // 讀取資料 val username = prefs.getString("username", "預設值") // 字串 val age = prefs.getInt("age", 0) // 整數 val isFirstRun = prefs.getBoolean("isFirstRun", true) // 布林值 val score = prefs.getFloat("score", 0f) // 浮點數 val userId = prefs.getLong("userId", 0L) // 長整數 ``` - getXXX(): 選擇和資料對應類型的getXXX()，內部需要填入鍵值和一個預設值作為參數，當對應的鍵值不存在時會返回這個預設值。

>[!Warning]使用刪除後要記得使用commit()或apply()來提交變更 - remove(): 刪除指定的單個鍵值對 ```kotlin= val prefs = getSharedPreferences("MyPrefs", Context.MODE_PRIVATE) // 刪除單個鍵 prefs.edit().remove("username").apply() // 連續刪除多個--鍊式 prefs.edit() .remove("username") .remove("age") .apply() // 最後一次提交 // 連續刪除多個--scopeFunction prefs.edit().apply { remove("username") remove("age") apply() // 這裡的 apply() 是提交資料 } ``` - clear(): 清除所有資料 ```kotlin= prefs.edit().clear().apply() ```

- contains(): 判斷某個 key 是否存在，內部需填入一個鍵值作為參數，會回傳一個Boolean來表示該鍵值是否存在 ```kotlin= val prefs = getSharedPreferences("MyPrefs", Context.MODE_PRIVATE) if (prefs.contains("username")) { val username = prefs.getString("username", "") println("使用者名稱：$username") } else { println("username 尚未設定") } ``` - all: SharedPreferences實例的屬性，可用於查詢所有 key-value，會回傳一個Map<String, *>，內含所有鍵值對 ```kotlin= val prefs = getSharedPreferences("MyPrefs", Context.MODE_PRIVATE) // 用perfs.all獲取所有的鍵值對，並將其賦予變數 val allPrefs: Map = prefs.all for ((key, value) in allPrefs) { println("$key = $value") } ```