偏好設定元件和屬性 Android Jetpack 的一部分。

這個主題說明建構設定畫面時最常用的一些 Preference 元件和屬性。

偏好設定元件

本節說明常見的 Preference 元件。詳情請參閱每個元件的對應參考資料頁面。

偏好設定基礎架構

PreferenceFragmentCompat - Fragment 用於顯示 Preference 物件的互動階層。

偏好設定容器

PreferenceScreen - 表示設定畫面的頂層容器。這是 Preference 階層的根元件。

PreferenceCategory - 用於將類似 Preferences 分組的容器。PreferenceCategory 會顯示類別標題,並以視覺化方式分隔 Preferences 群組。

個人偏好設定

Preference - 代表個別設定的基本建構模塊。如果 Preference 設為保留,則會有對應的鍵/值組合,讓使用者自行選擇可在應用程式其他位置存取的設定。

EditTextPreference - 保留 String 值的 Preference。使用者只要輕觸 Preference,就能啟動包含文字欄位的對話方塊,讓使用者可以變更保留的值。

ListPreference - 保留「String」(字串) 值的 Preference。使用者可以在對話方塊中變更這個值,對話方塊中包含帶有對應標籤的圓形按鈕清單。

MultiSelectListPreference - 保留一組「String」(字串) 的 Preference。使用者可以在對話方塊中變更這些值,對話方塊中包含帶有對應標籤的核取方塊清單。

SeekBarPreference - 保留整數值的 Preference。只要拖曳 Preference 版面配置中顯示的對應搜尋列,即可變更這個值。

SwitchPreferenceCompat - 保留布林值的 Preference。只要點選對應的切換按鈕小工具互動,或輕觸 Preference 版面配置,即可變更這個值。

CheckBoxPreference - 保留布林值的 Preference。只要點選對應的核取方塊,或輕觸 Preference 版面配置,即可變更這個值。

偏好設定屬性

以下列出了設定 Preference 外觀和行為的一些最常用的屬性。

通用屬性

title

表示 Preference 標題的 String 值。

範例: app:title="Title"

summary

表示 Preference 摘要的 String 值。

範例: app:summary="Summary"

icon

代表 Preference 圖示的 Drawable

範例: app:icon="@drawable/ic_camera"

key

String 值表示用於保留關聯 Preference 值的索引鍵。索引鍵可讓您在執行階段中進一步自訂 Preference。您應為階層中的每個 Preference 設定索引鍵。

範例: app:key="key"

enabled

表示使用者是否能與 Preference 互動的布林值。當值為 false時,Preference 顯示為灰色,而使用者無法與其互動。預設值為 true

範例: app:enabled="false"

selectable

表示使用者是否能與 Preference 互動的布林值。預設值為 true

範例: app:selectable="false"

isPreferenceVisible

表示是否顯示 PreferencePreference 類別的布林值。這相當於呼叫 setVisible()

範例: app:isPreferenceVisible="false"

defaultValue

表示 Preference 的預設值。如果找不到這個 Preference 的其他保留值,系統就會設定並保留這個值。值類型取決於關聯的 Preference

範例: app:defaultValue="true"

dependency

代表控制這個 Preference 狀態的 SwitchPreferenceCompat 索引鍵。當對應的切換按鈕關閉時,這個 Preference 停用且無法修改。

範例: app:dependency="parent"

PreferenceCategory 屬性

initialExpandedChildrenCount

啟用可展開式 Preference 行為的整數值。這個值表示可在 PreferenceGroup 中顯示的子項數量上限。系統收合所有額外子項,使用者輕觸展開按鈕即可顯示。根據預設,這個值為 Integer.MAX_VALUE,系統會顯示所有子項。

警告:如果使用這個屬性,請務必在 PreferenceCategory 上設定金鑰,以便在設定發生變化時 (例如旋轉螢幕時),系統可以正確儲存與還原狀態。

範例: app:initialExpandedChildrenCount="0"

ListPreference / MultiSelectListPreference 屬性

entries

「String」(字串) 陣列,相當於要顯示給使用者的清單項目。這些值中的每一個值都會按索引對應至內部保留的值陣列。舉例來說,當使用者選取第一個清單項目時,系統會保留對應值陣列中的第一個元素。

範例: app:entries="@array/entries"

警告: 請確認兩個陣列的長度相同,且每個陣列的索引皆符合正確的項目/值組合。

entryValues

要保留的項目陣列。這些值中的每一個值都會按照索引與顯示給使用者的清單項目陣列對應。

範例: app:entryValues="@array/values"