首选项组件和属性   Part of 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

提示 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"