偏好设置组件和属性 Android Jetpack 的一部分。
本页面介绍了构建设置屏幕时最常用的一些 Preference
组件和属性。
偏好设置组件
本部分介绍了常见的 Preference
组件。如需了解详情,请参阅每个组件的对应参考页面。
偏好设置基础架构
PreferenceFragmentCompat
- 负责显示 Preference
对象的互动层次结构的 Fragment
。
偏好设置容器
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
-
指示
Preference
类别或Preference
类别是否可见的布尔值。这相当于调用setVisible()
。示例:
app:isPreferenceVisible="false"
-
defaultValue
-
表示
Preference
的默认值。如果没有找到此Preference
的其他保留值,则设置并保留此值。值类型取决于关联的Preference
。示例:
app:defaultValue="true"
-
dependency
-
表示
SwitchPreferenceCompat
的键,它控制着此Preference
的状态。当对应开关关闭时,此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"