萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> Android 開發

Android SharedPreferences 讀寫鍵值對完整範例

SharedPreferences 是 Android 輕量級鍵值對儲存方案,適用於保存使用者偏好設定、登入狀態、小量結構化資料。本文提供完整的讀寫封裝工具類,涵蓋同步/非同步提交、型別安全讀取、預設值處理、刪除與清空等常用操作。

核心工具類

public class PrefsHelper {
    private static final String PREF_NAME = "app_config";
    private static SharedPreferences sPrefs;
    private static SharedPreferences.Editor sEditor;

    // 單例模式初始化
    public static void init(Context context) {
        if (sPrefs == null) {
            sPrefs = context.getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE);
            sEditor = sPrefs.edit();
        }
    }

    // 同步寫入 (apply 非同步,commit 同步並回傳 boolean)
    public static void putString(String key, String value) { sEditor.putString(key, value).apply(); }
    public static void putInt(String key, int value) { sEditor.putInt(key, value).apply(); }
    public static void putLong(String key, long value) { sEditor.putLong(key, value).apply(); }
    public static void putFloat(String key, float value) { sEditor.putFloat(key, value).apply(); }
    public static void putBoolean(String key, boolean value) { sEditor.putBoolean(key, value).apply(); }
    public static void putStringSet(String key, Set value) { sEditor.putStringSet(key, value).apply(); }

    // 型別安全讀取 (提供預設值)
    public static String getString(String key, String defValue) { return sPrefs.getString(key, defValue); }
    public static int getInt(String key, int defValue) { return sPrefs.getInt(key, defValue); }
    public static long getLong(String key, long defValue) { return sPrefs.getLong(key, defValue); }
    public static float getFloat(String key, float defValue) { return sPrefs.getFloat(key, defValue); }
    public static boolean getBoolean(String key, boolean defValue) { return sPrefs.getBoolean(key, defValue); }
    public static Set getStringSet(String key, Set defValue) { return sPrefs.getStringSet(key, defValue); }

    // 刪除單一鍵 / 全部清空
    public static void remove(String key) { sEditor.remove(key).apply(); }
    public static void clear() { sEditor.clear().apply(); }

    // 判斷鍵是否存在
    public static boolean contains(String key) { return sPrefs.contains(key); }

    // 註冊變更監聽器
    public static void registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener) {
        sPrefs.registerOnSharedPreferenceChangeListener(listener);
    }
    public static void unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener) {
        sPrefs.unregisterOnSharedPreferenceChangeListener(listener);
    }
}

使用範例

// Application.onCreate() 初始化一次
PrefsHelper.init(this);

// 寫入
PrefsHelper.putString("user_token", "abc123");
PrefsHelper.putBoolean("is_logged_in", true);
PrefsHelper.putInt("theme_mode", 2); // 0=跟隨系統, 1=淺色, 2=深色

// 讀取
String token = PrefsHelper.getString("user_token", "");
boolean loggedIn = PrefsHelper.getBoolean("is_logged_in", false);
int theme = PrefsHelper.getInt("theme_mode", 0);

// 監聽主題變更
PrefsHelper.registerOnSharedPreferenceChangeListener((prefs, key) -> {
    if ("theme_mode".equals(key)) {
        int newTheme = prefs.getInt(key, 0);
        applyTheme(newTheme);
    }
});

進階技巧與避坑

  • apply() vs commit(): apply() 非同步寫入磁碟,不阻塞主執行緒,效能優;commit() 同步寫入並回傳成功與否,需在背景執行緒呼叫。推薦統一用 apply()。
  • MODE_PRIVATE 獨佔模式: 僅本應用可讀寫,安全。勿使用 MODE_WORLD_READABLE/WRITABLE (API 17+ 已棄用且有安全風險)。
  • 大資料不適用: SharedPreferences 全量載入記憶體,資料超過 100KB 會明顯拖慢啟動速度。大量資料請用 Room (SQLite)、DataStore (Proto/Preferences) 或檔案儲存。
  • 跨進程問題: 多進程 (如 :remote 服務) 共享 Preferences 需配合 Context.MODE_MULTI_PROCESS (已棄用) 或改用 DataStore / ContentProvider / MMKV。
  • 鍵名規範: 建議加前綴分類,如 pref_user_token、pref_theme_mode,避免衝突。

現代替代方案:Jetpack DataStore

Google 官方推薦使用 DataStore 取代 SharedPreferences:

  • Preferences DataStore:鍵值對,基於 Kotlin Flow + 協程,非同步、交易性、型別安全。
  • Proto DataStore:自定義資料結構 (Protocol Buffers),嚴格 schema、序列化效能高。
// Preferences DataStore 依賴
implementation "androidx.datastore:datastore-preferences:1.0.0"

// 使用
val dataStore = context.createDataStore("settings")
val EXAMPLE_COUNTER = intPreferencesKey("example_counter")
suspend fun incrementCounter() {
    dataStore.edit { settings ->
        val current = settings[EXAMPLE_COUNTER] ?: 0
        settings[EXAMPLE_COUNTER] = current + 1
    }
}
新專案請直接上 DataStore;存量專案可漸進式遷移,SharedPreferences 仍可共存使用。
copyright © 萬盛學電腦網 all rights reserved