偏好設定

建立互動式設定畫面，無需存取裝置儲存空間或管理 UI。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2023 年 7 月 26 日 1.2.1 - - -

宣告依附元件

如要新增 Preference 依附元件，必須將 Google Maven 存放區新增至您的專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增您需要的構件依附元件：

Groovy

dependencies {
    def preference_version = "1.2.1"

    // Java language implementation
    implementation "androidx.preference:preference:$preference_version"
    // Kotlin
    implementation "androidx.preference:preference-ktx:$preference_version"
}

Kotlin

dependencies {
    val preference_version = "1.2.1"

    // Java language implementation
    implementation("androidx.preference:preference:$preference_version")
    // Kotlin
    implementation("androidx.preference:preference-ktx:$preference_version")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

1.2 版本

1.2.1 版本

2023 年 7 月 26 日

發布 androidx.preference:preference:1.2.1。查看 1.2.1 版的修訂項目。

修正錯誤

  • PreferenceHeaderFragmentCompat現在在 ComponentDialog 中使用或使用 Hilt 的 @AndroidEntryPoint 這類程式庫 (納入 Fragment 的 Context) 時，可以正確處理系統返回按鈕。
  • 偏好設定現在取決於活動 1.5.1。(Ie5d22)。
  • PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment 現在會將 header.extras 做為 Fragment 引數傳播。

1.2.0 版本

2022 年 1 月 26 日

已釋出「androidx.preference:preference:1.2.0」和「androidx.preference:preference-ktx:1.2.0」。1.2.0 版本包含以下修訂項目。

自 1.1.0 版本之後的重要異動

  • 新增的 PreferenceHeaderFragmentCompat 雙窗格偏好設定，可在手機、折疊式裝置和平板電腦中自動調整比例。在 PreferenceHeaderFragmentCompat 上覆寫 onCreatePreferenceHeader()可得到標題窗格。標題 PreferenceFragmentCompat 中使用 app:fragment 的 <Preference> 會使該片段出現在第二個詳細資料窗格中。手動選取任何偏好設定之前的初始詳細資料片段，只要覆寫 onCreateInitialDetailFragment() 即可自訂。預設導入作業會傳回第一個已定義片段的偏好設定。
class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

  • 在先前未指定 @NonNull 或 @Nullable 的許多 API，新增是否可為空值註解。如果您在 Kotlin 程式碼中選擇的空值，與現在定義的空值不符，這可能表示異動將 Kotlin 來源毀損。

  • PreferenceFragmentCompat 現在先尋找父項片段上的OnPreferenceStartFragmentCallback、OnNavigateToScreenListener 和 OnDisplayPreferenceDialogListener介面，再確認代管結構或活動是否導入這些介面。

1.2.0-rc01 版本

2021 年 12 月 15 日

自從 1.2.0-beta01後，「androidx.preference:preference:1.2.0-rc01」和「androidx.preference:preference-ktx:1.2.0-rc01」沒有發布任何異動。1.2.0-rc01 版本包含這些修訂版本。

1.2.0-beta01 版本

2021 年 11 月 17 日

自從偏好設定 1.2.0-alpha02後，「androidx.preference:preference:1.2.0-beta01」和「androidx.preference:preference-ktx:1.2.0-beta01」沒有發布任何異動。1.2.0-beta01 版本包含這些修訂版本。

1.2.0-alpha02 版本

2021 年 11 月 3 日

已釋出「androidx.preference:preference:1.2.0-alpha02」和「androidx.preference:preference-ktx:1.2.0-alpha02」。1.2.0-alpha02 版本包含以下修訂項目。

API 異動

  • 在先前未指定 @NonNull 或 @Nullable 的許多 API，新增是否可為空值註解。(I04252、Ie2cc0)。
  • 從 PreferenceHeaderFragmentCompat 中移除 openPreference() API - 系統會為您呼叫這個方法，請勿手動呼叫。(Ia6989)

行為異動

  • Preference -OnNavigateToScreenListener 和 OnDisplayPreferenceDialogListener 的 PreferenceFragmentCompat 回呼會使用與 OnPreferenceTreeClickListener 相同的模式，並查詢有效資訊清單的父項片段階層，然後再查看即可查看代管結構或活動是否導入這些介面。(I7ae6c)

1.2.0-alpha01 版本

2021 年 10 月 27 日

已釋出「androidx.preference:preference:1.2.0-alpha01」和「androidx.preference:preference-ktx:1.2.0-alpha01」。1.2.0-alpha01 版包含此連結所列的修訂項目。

新功能

  • 新增到雙窗格偏好設定的 PreferenceHeaderFragmentCompat (I9a2d8)

行為異動

  • 現在可以在非活動內容中導入 OnPreferenceDisplayDialogCallback、OnPreferenceStartScreenCallback 和 OnPreferenceStartFragmentCallback 的偏好設定回呼。勾選 getContext() 後，會先檢查這些回呼是否在呼叫 getActivity() 之前實作。如果 getContext() 傳回活動 (常見情況)，則行為不變。

  • PreferenceFragmentCompat 對 onPreferenceTreeClick 的呼叫現在會先尋找 父項片段上的OnPreferenceStartFragmentCallback 介面的導入，再考慮活動的導入。(c64eed)

1.1 版本

1.1.1 版本

2020 年 4 月 15 日

已釋出「androidx.preference:preference:1.1.1」和「androidx.preference:preference-ktx:1.1.1」。1.1.1 版本包含以下修訂項目。

修正錯誤

  • 從 xml 加載 FragmentContainerView 時，PreferenceDialogFragmentCompat 不會擲回 IllegalStateException。(b/150051716)

依附元件更新

  • 偏好設定現在取決於「片段」1.2.4。(aosp/1277317)
  • preference-ktx 依附元件現在會依照 androidx.core:core-ktx:1.1.0 和 androidx.fragment:fragment-ktx:1.2.4 而定，以反映 preference 主要成果的依附元件，並確保升級 preference-ktx 會同時更新轉換依附元件的主要和 -ktx 構件。(aosp/1277319)

1.1.0 版本

2019 年 9 月 5 日

發布 androidx.preference:preference:1.1.0 和 androidx.preference:preference-ktx:1.1.0。您可以前往這裡查看這個版本包含的修訂版本。

如果這是您首次發布的 1.1.* 版本，以下是自上次穩定版本 (1.0.0) 起重大異動的精簡清單。您也可以參考設定指南、範例應用程式，以及 Android 開發人員高峰會講座。

自 1.0.0 版以來的重要異動

  • 以架構片段為基礎的 PreferenceFragment 和其他類別已淘汰；請改用 PreferenceFragmentCompat 和其他 *compat 類別。
  • 您現在可以在偏好設定上設定 SummaryProvider，這樣一來，每當偏好設定有所更新或使用者看到偏好設定時，即可動態設定摘要。詳情請參閱指南。
  • 已新增EditTextPreference.OnBindEditTextListener介面。這樣一來，就可以在對話方塊繫結後自訂 EditText 中顯示的對應對話方塊。這樣就能直接在 EditTextPreference 上使用 android:inputType 這類屬性 (Android 程式庫並不支援這項功能)。詳情請參閱指南。
  • 已新增 Preference.setCopyingEnabled()。設定完畢後，長按「偏好設定」就會顯示內容選單，讓使用者複製「偏好設定」摘要。
  • 已更新 SeekBarPreference 樣式，以符合 Material 規格。請參閱 SeekBarPreference 的其他詳細異動記錄，
  • 修正大量錯誤、改善樣式、提高 API 等級相容性，以及一般 QOL。

1.1.0-rc01 版本

2019 年 7 月 2 日

發布 androidx.preference:preference:1.1.0-rc01 和 androidx.preference:preference-ktx:1.1.0-rc01。您可以前往這裡查看這個版本包含的修訂項目。

API 異動

  • 淘汰 Preference#onInitializeAccessibilityNodeInfo
  • 這個方法可以針對特定偏好設定偏好取得無障礙節點資訊，但是這項自訂的錯誤層。如果想調整無障礙資訊，應改為覆寫 onBindViewHolder，並直接在檢視畫面中新增無障礙資訊。

1.1.0-beta01 版本

2019 年 6 月 5 日

發布 androidx.preference:preference:1.1.0-beta01 和 androidx.preference:preference-ktx:1.1.0-beta01。您可以前往這裡查看這個版本包含的修訂版本。

自 1.1.0 版本之後的重要異動

如果這是第 1.1.* 個要更新的版本，以下列出自上次 1.1.0穩定版本 以來較大的異動清單。您也可以參考設定指南、範例應用程式，以及 Android 開發人員高峰會講座。

  • PreferenceFragment 和採用架構片段的其他類別已淘汰，請改用 PreferenceFragmentCompat 和其他 *compat 類別。
  • 您現在可以在偏好設定上設定 SummaryProvider，讓系統在偏好設定有所更新時，向使用者顯示動態摘要。詳情請參閱指南。
  • 已新增EditTextPreference.OnBindEditTextListener介面。如此一來，在對話方塊繫結完成後，即可自訂對應的對話方塊中顯示的 EditText。這是直接用在 EditTextPreference 使用 android:inputType 等屬性的直接替代項目，但 AndroidX 程式庫並不支援這項功能。詳情請參閱指南。
  • 已新增 Preference.setCopyingEnabled()。設定完畢後，長按「偏好設定」就會顯示內容選單，讓使用者複製「偏好設定」摘要。
  • 符合 Material 規格之更新後的 SeekBarPreference 樣式。如需 SeekBarPreference 的其他異動，請參閱詳細的異動記錄。
  • 修正大量錯誤、改善樣式、提高 API 等級相容性，以及一般 QOL。

自 1.1.0-alpha05 起的 API 異動

  • 從 public API 中移除 getOnBindEditTextListener，則只有在與這個 API 互動時，才需要使用 setOnBindEditTextListener。

如果遇到問題，或有任何新功能建議，請按這裡回報錯誤！

1.1.0-alpha05 版本

2019 年 5 月 7 日

發布 androidx.preference:preference:1.1.0-alpha05 和 androidx.preference:preference-ktx:1.1.0-alpha05。您可以前往這裡查看這個版本包含的修訂項目。

新功能

  • 更新無法選取的偏好設定樣式 - 標題和摘要現在採用相同的顏色，以表明使用者無法與其互動，且僅用於顯示資訊。
  • 注意：建議您將 enableCopying="true" 新增至無法選取的偏好設定，以便長按複製摘要。

修正錯誤

  • 已修正在 PreferenceCategory 和其他無法選取偏好設定時，會遇到的迴歸問題
  • 修正 TalkBack 無法將 DropDropPreference 顯示為可點擊的原因
  • 修正部分 RTL 版面配置問題
  • 配合 Fragment 更新 PreferenceFragmentCompat 中部分空值的註解

1.1.0-alpha04 版本

2019 年 3 月 13 日

已釋出「androidx.preference:preference:1.1.0-alpha04」和「androidx.preference:preference-ktx:1.1.0-alpha04」。您可以前往這裡查看這個版本包含的修訂版本完整清單。

新功能

更新「SeekBarPreference」！

  • 已根據教材規格更新樣式
    • 根據預設，值標籤已隱藏，但仍可透過 app:showSeekBarValue="true" 或 setShowSeekBarValue(true) 顯示。這個標籤並非 Material 規格的一部分，但我們深知，雖然使用頻率很高，但我們仍建議繼續支援。
    • 拖曳 SeekBar 時，值標籤現在會隨之更新，而非釋出時。請注意，這不表示內部系統已更新該值，請參閱下方的新 API 即可啟用該功能。
    • 注意：雖然系統支援這項操作，但請避免在 SeekBarPreference 設定摘要，因為這項功能並不是根據 Material 規格而設定。
  • 支援持續更新，讓 SeekBar 在拖曳 SeekBar 時更新已儲存的值。你可以透過 XML 或 app:updatesContinuously="true" 或 setUpdatesContinuously(true) 啟用程式輔助功能。一旦 SeekBar 在畫面上的位置異動，系統就會觸發這個事件。

API 異動

  • 新增缺少空值的 findPreference() 註解

修正錯誤

  • 修正錯誤：如果未啟用複製功能，無法正確移除內容選單事件監聽器

1.1.0-alpha03 版本

2019 年 2 月 7 日

androidx.preference:preference 1.1.0-alpha03

以下為 androidx.preference:preference 1.1.0-alpha03 和 androidx.preference:preference-ktx 1.1.0-alpha03 發布內容，並經過下列異動。

修正錯誤

  • 修正問題：EditTextPreference 對話方塊有時會顯示複製/貼上彈出式視窗
  • 修正基礎轉接器未能正確取消註冊的問題，造成特定條件 (b/121006469) 造成記憶體流失
  • 修正設定異動期間發生的某些對話方塊相關當機問題 (b/122167543)
  • 已修正 SummaryProvider 無法用於 MultiSelectListPreference (b/123022772)

1.1.0-alpha02 版本

2018 年 12 月 17 日

另請參閱最近更新的設定指南和範例應用程式。

新功能

  • 已新增 EditTextPreference.OnBindEditTextListener 介面。這樣一來，對話方塊繫結後，即可在自訂對話方塊中顯示編輯的 TextText。例如，設定自訂輸入類型 / 長度或新增 TextWatcher。

  • 已新增 Preference.setCopyingEnabled() 設定完畢後，長按「偏好設定」就會顯示內容選單，讓使用者複製「偏好設定」摘要。此 API 可用於複製靜態資訊，例如使用者專屬 ID / 應用程式版本資訊。

  • 偏好設定主題現已套用到活動主題。也就是說，從程式碼建立偏好設定時，您不再需要使用 PreferenceManager#getContext() 的結構定義，只要使用您的片段/活動內容即可。

API 異動

  • 將 findPreference() 重構為傳回 <T extends Preference> 也就是說，使用 foundPreference() 時，不需要明確投放偏好設定。舉例來說，EditTextPreference preference = findPreference(“edit_text”) 現已成為有效的代碼。

1.1.0-alpha01 版本

2018 年 11 月 5 日

新功能

  • 您現在可以在偏好設定上設定 SummaryProvider，讓系統在偏好設定有所更新時，向使用者顯示動態摘要。
  • 為 ListPreference 和 EditTextPreference 新增預設 SummaryProvider 實作。設定完畢後，系統就會自動更新偏好設定摘要以反映已儲存的值；如果沒有儲存任何值，則會顯示「Not Set」(未設定)。 您可以使用 app:useSimpleSummaryProvider=”true 來設定
  • 新增 PreferenceGroup#removePreferenceRecursative 可遞迴找到並移除群組中的偏好設定，或降低階層中的巢狀群組。

API 異動

  • 以 Fragment 為基礎的架構和其他類別現已淘汰；您應該改用 PreferenceFragmentCompat 和其他 compat 類別。

修正錯誤

  • 已修正 iconSpaceReserved 與 PreferenceCategories 無法正常運作。
  • 已修正 PreferenceCategory，在 API 21 以下未採用 colorAccent 做為標題的顏色。
  • 修正 API 21 以下的一些 SeekBarPreference 版面配置不一致。