Android Preference Headers 白屏：XML 重複標籤導致解析失敗

問題現象

使用 PreferenceActivity + Headers 重寫設定頁，onBuildHeaders 載入 XML 後顯示白屏，無任何 Header。

錯誤 XML

<?xml version="1.0" encoding="utf-8"?>
<preference-headers xmlns:android="https://schemas.android.com/apk/res/android">
    <preference-headers xmlns:android="https://schemas.android.com/apk/res/android">  <!-- 重複根標籤！ -->
        <header android:fragment="..." android:title="..." android:summary="..." />
        ...
    </preference-headers>
</preference-headers>

根本原因

XML 中出現巢狀重複的 <preference-headers> 根元素，導致解析器無法正確建立 Header 列表，結果為空。

正確 XML

<?xml version="1.0" encoding="utf-8"?>
<preference-headers xmlns:android="https://schemas.android.com/apk/res/android">
    <header
        android:fragment="com.example.SettingsActivity$DesignFragment"
        android:title="@string/pref_header_design"
        android:summary="@string/pref_header_design_summary" />
    <header
        android:fragment="com.example.SettingsActivity$SettingsFragment"
        android:title="@string/pref_header_units"
        android:summary="@string/pref_header_units_summary" />
    <header
        android:fragment="com.example.SettingsActivity$DatabaseFragment"
        android:title="@string/pref_header_db"
        android:summary="@string/pref_header_db_summary" />
</preference-headers>

關鍵檢查點

1. 單一根元素：XML 必須只有一個 <preference-headers>。
2. Fragment 完整類名：android:fragment 需包含外部類名 + $ + 內部類名（如 com.example.SettingsActivity$DesignFragment）。
3. Fragment 繼承 PreferenceFragment：每個 Header 對應的 Fragment 必須繼承 PreferenceFragment（或 PreferenceFragmentCompat）。
4. onBuildHeaders 呼叫正確資源：loadHeadersFromResource(R.xml.pref_headers, target)。

現代替代方案：PreferenceFragmentCompat + Settings Activity

// SettingsActivity.kt
class SettingsActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.settings_activity)
        supportFragmentManager
            .beginTransaction()
            .replace(R.id.settings_container, SettingsFragment())
            .commit()
    }
}

// SettingsFragment.kt
class SettingsFragment : PreferenceFragmentCompat() {
    override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
        setPreferencesFromResource(R.xml.root_preferences, rootKey)
    }
}

優勢：支援 Material Design、向下相容、程式碼更簡潔、不依賴 Header 機制。

XML 結構錯誤是白屏常見主因，仔細檢查巢狀標籤與屬性拼寫能快速定位。