CheckBoxPreference 是 Android 偏好設定框架中的布林值切換組件。使用者點擊即可在勾選(true)與取消勾選(false)之間切換,狀態會自動以布林值形式儲存至 SharedPreferences。適用於功能開關、通知開關、隱私權設定等二元選擇場景。
<?xml version="1.0" encoding="utf-8"?>
<PreferenceScreen xmlns:android="https://schemas.android.com/apk/res/android">
<PreferenceCategory android:title="通知與隱私設定">
<CheckBoxPreference
android:key="pref_push_notifications"
android:title="推播通知"
android:summary="接收應用程式推播訊息"
android:defaultValue="true" />
<CheckBoxPreference
android:key="pref_auto_sync"
android:title="自動同步資料"
android:summary="在 Wi-Fi 環境下自動同步雲端資料"
android:defaultValue="false"
android:dependency="pref_push_notifications" />
<CheckBoxPreference
android:key="pref_analytics"
android:title="匿名使用統計"
android:summary="協助我們改善應用程式體驗"
android:defaultValue="true" />
</PreferenceCategory>
</PreferenceScreen>
| 屬性 | 說明 | 預設值 |
|---|---|---|
| android:key | SharedPreferences 中的鍵值,必須唯一 | 無 |
| android:title | 主要顯示文字 | 無 |
| android:summary | 輔助說明文字,支援 %s 佔位符顯示當前值 | 無 |
| android:defaultValue | 初始布林值("true" 或 "false") | false |
| android:dependency | 依賴另一個 CheckBoxPreference 的 key,被依賴項取消勾選時本項自動停用 | 無 |
| android:disableDependentsState | 何時停用依賴項:true=勾選時停用,false=取消勾選時停用 | false |
public class SettingsFragment extends PreferenceFragmentCompat
implements SharedPreferences.OnSharedPreferenceChangeListener {
@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
setPreferencesFromResource(R.xml.preferences, rootKey);
}
@Override
public void onResume() {
super.onResume();
// 註冊監聽器
getPreferenceScreen().getSharedPreferences()
.registerOnSharedPreferenceChangeListener(this);
// 初始化摘要顯示
updateSummaries();
}
@Override
public void onPause() {
super.onPause();
getPreferenceScreen().getSharedPreferences()
.unregisterOnSharedPreferenceChangeListener(this);
}
@Override
public void onSharedPreferenceChanged(SharedPreferences prefs, String key) {
if (key.equals("pref_push_notifications") || key.equals("pref_auto_sync")) {
updateSummaries();
// 執行業務邏輯,如註冊/註銷推播服務
handleNotificationSettingChange(prefs.getBoolean(key, true));
}
}
private void updateSummaries() {
SharedPreferences prefs = getPreferenceScreen().getSharedPreferences();
CheckBoxPreference pushPref = findPreference("pref_push_notifications");
if (pushPref != null) {
pushPref.setSummary(prefs.getBoolean("pref_push_notifications", true)
? "已啟用推播通知" : "推播通知已關閉");
}
}
private void handleNotificationSettingChange(boolean enabled) {
// 實際業務邏輯:啟動/停止 Firebase Messaging 服務等
}
}
若需自訂 CheckBoxPreference 外觀(如更換勾選圖示、調整文字大小),可建立自訂佈局:
<!-- res/layout/custom_checkbox_preference.xml -->
<LinearLayout xmlns:android="https://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:orientation="horizontal"
android:gravity="center_vertical"
android:padding="16dp">
<TextView
android:id="@android:id/title"
android:layout_width="0dp"
android:layout_height="wrap_content"
android:layout_weight="1"
android:textSize="16sp"
android:textColor="?android:textColorPrimary" />
<CheckBox
android:id="@android:id/checkbox"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:buttonTint="?colorAccent"
android:focusable="false"
android:clickable="false" />
</LinearLayout>
在 XML 中引用:
<CheckBoxPreference
android:key="pref_custom_style"
android:title="自訂樣式開關"
android:layout="@layout/custom_checkbox_preference" />
onSharedPreferenceChanged 中手動更新摘要,系統不會自動處理android:defaultValue 必須為字串 "true" 或 "false",而非布林值onResume/onPause 中註冊/註銷監聽器,避免記憶體洩漏CheckBoxPreference 是實作開關型設定的首選組件。善用 dependency 屬性可建立直觀的設定層級關係,配合 OnSharedPreferenceChangeListener 即時響應使用者操作。注意生命週期管理與摘要同步,即可打造流暢的設定體驗。