Preference

Preference

用户指南  代码示例

API 参考文档
androidx.preference

无需与设备存储空间交互，也不需要管理界面，便能构建交互式设置画面。

最近更新时间	稳定版	候选版	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")
}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 1.2

版本 1.2.1

2023 年 7 月 26 日

发布了 androidx.preference:preference:1.2.1。版本 1.2.1 中包含这些提交内容。

bug 修复

• 在 ComponentDialog 中使用或使用封装 Fragment 的 Context 的 Hilt 的 @AndroidEntryPoint 等库时，PreferenceHeaderFragmentCompat 现在可以正确处理系统返回按钮。
• Preference 现在依赖于 Activity 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> 都会导致该 fragment 出现在第二个详情窗格中。可以通过替换 onCreateInitialDetailFragment()，自定义应在手动选择任何偏好设置之前显示的初始详情 fragment。默认实现会返回第一个已定义 fragment 的偏好设置。

class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

• 为许多以前未指定 @NonNull 或 @Nullable 的 API 添加了是否可为 null 注解。如果您在 Kotlin 代码中选择的是否可为 null 性与当前定义的是否可为 null 性不一致，可能会使此更改成为一种 Kotlin 源代码破坏性更改。

• PreferenceFragmentCompat 现在会先在父 fragment 上查找 OnPreferenceStartFragmentCallback、OnNavigateToScreenListener 和 OnDisplayPreferenceDialogListener 接口的实现，然后再查看托管 Context 或 Activity 是否实现了这些接口。

版本 1.2.0-rc01

2021 年 12 月 15 日

发布了 androidx.preference:preference:1.2.0-rc01 和 androidx.preference:preference-ktx:1.2.0-rc01，这两个版本与 1.2.0-beta01 相比没有变化。版本 1.2.0-rc01 中包含这些提交内容。

版本 1.2.0-beta01

2021 年 11 月 17 日

发布了 androidx.preference:preference:1.2.0-beta01 和 androidx.preference:preference-ktx:1.2.0-beta01，这两个版本与 Preference 1.2.0-alpha02 相比没有变化。版本 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 添加了是否可为 null 注解。（I04252、Ie2cc0）
• 从 PreferenceHeaderFragmentCompat 中移除了 openPreference() API - 系统会为您调用该方法，您不应手动调用它。(Ia6989)

行为变更

• 针对 OnNavigateToScreenListener 和 OnDisplayPreferenceDialogListener 的 PreferenceFragmentCompat 回调现在遵循与 OnPreferenceTreeClickListener 相同的模式，并在查看托管 Context 或 Activity 是否实现了这些接口之前查找有效监听器的父 fragment 层次结构。(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)

行为变更

• 现在可以在非 activity 上下文中实现 OnPreferenceDisplayDialogCallback、OnPreferenceStartScreenCallback 和 OnPreferenceStartFragmentCallback 的偏好设置回调。系统会在检查 getActivity() 之前检查 getContext()，查看其是否实现了这些回调。如果 getContext() 返回 activity（常见情况），则行为没有变化。

• 现在，PreferenceFragmentCompat 在调用 onPreferenceTreeClick 时会先查找父 fragment 中 OnPreferenceStartFragmentCallback 接口的实现，然后再考虑该 activity 的实现。(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 中包含这些提交内容。

bug 修复

• 从 xml 膨胀 FragmentContainerView 时，PreferenceDialogFragmentCompat 不再抛出 IllegalStateException。(b/150051716)

依赖项更新

• Preference 现在依赖于 Fragment 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 及其他使用框架 Fragment 的类。您应改为使用 PreferenceFragmentCompat 和其他 *compat 类。
• 您现在可以在 Preference 上设置 SummaryProvider，以便能够在 Preference 更新或变为对用户可见时动态配置其摘要。如需了解详情，请参阅指南。
• 添加了 EditTextPreference.OnBindEditTextListener 接口。这将允许在对话框绑定之后，自定义该对话框中显示的 EditText。这直接替代了将 android:inputType 等属性直接用于 EditTextPreference 的做法，后者在 AndroidX 库中不受支持。如需了解详情，请参阅指南。
• 添加了 Preference.setCopyingEnabled()。设置后，长按 Preference 会显示上下文菜单，以便于您复制 Preference 的摘要。
• 更新了 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
• 此方法代理了特定 Preference 的无障碍功能节点信息，但对这种自定义来说，这是错误的层。如果您要调整无障碍功能信息，您应该替换 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 及其他使用框架 Fragment 的类。您应改为使用 PreferenceFragmentCompat 和其他 *compat 类。
• 您现在可以在 Preference 上设置 SummaryProvider，以便能够在 Preference 更新或变为对用户可见时动态配置其摘要。如需了解详情，请参阅指南。
• 添加了 EditTextPreference.OnBindEditTextListener 接口。这将允许在对话框绑定之后，自定义该对话框中显示的 EditText。这直接替代了将 android:inputType 等属性直接用于 EditTextPreference 的做法，后者在 AndroidX 库中不受支持。如需了解详情，请参阅指南。
• 添加了 Preference.setCopyingEnabled()。设置后，长按 Preference 会显示上下文菜单，以便于您复制 Preference 的摘要。
• 更新了 SeekBarPreference 样式，以符合 Material 规范。要了解 SeekBarPreference 的其他变更，请参阅详细的更改日志。
• 大量的问题修复、样式更新、API 级兼容性修复和一般性的 QOL 改进。

自 1.1.0-alpha05 以来的 API 变更

• 从公共 API 中移除了 getOnBindEditTextListener。现在，与此 API 互动时，您只需要使用 setOnBindEditTextListener。

如果您遇到任何问题，或者对新功能有任何建议，请在此处提交 bug 报告。

版本 1.1.0-alpha05

2019 年 5 月 7 日

发布了 androidx.preference:preference:1.1.0-alpha05 和 androidx.preference:preference-ktx:1.1.0-alpha05。点击此处可查看此版本中包含的提交内容。

新功能

• 更新了不可选择的 Preference 的样式，标题和摘要现在共享同一种颜色，以表明不能与它们互动，并且它们仅用于显示信息。
• 注意：您不妨考虑将 enableCopying="true" 添加到不可选择的 Preference 中，以便能够通过长按来复制摘要。

bug 修复

• 修复了选择 PreferenceCategory 和其他不可选择的 Preference 时会出现连锁反应的回归问题
• 修复了 TalkBack 无法将 DropDownPreference 视为可点击项的无障碍功能问题
• 修复了 RTL 布局问题
• 更新了 PreferenceFragmentCompat 中的某些可为 null 的注释，以便与 Fragment 匹配

版本 1.1.0-alpha04

2019 年 3 月 13 日

发布了 androidx.preference:preference:1.1.0-alpha04 和 androidx.preference:preference-ktx:1.1.0-alpha04。点击此处可查看此版本中包含的完整提交内容列表。

新功能

SeekBarPreference 更新！

• 更新了样式，使之符合 Material 规范
  • 现在，默认情况下，值标签处于隐藏状态，但可通过 app:showSeekBarValue="true" 或 setShowSeekBarValue(true) 显示。此标签不属于 Material 规范的一部分，但我们知道该标签的使用率很高，因此我们会继续支持它，尽管我们不推荐使用。
  • 现在，值标签会在 SeekBar 被拖动时（而不是被释放时）更新。请注意，这并不表示会在内部更新值，请参见下文来了解启用该功能的新 API。
  • 注意：尽管受支持，但您应该避免在 SeekBarPreference 上设置摘要，因为这不是预期的做法，也不符合 Material 规范。
• 增加了对连续更新的支持，允许 SeekBar 在被拖动时更新其保存的值。这可以通过 XML 或编程方式使用 app:updatesContinuously="true" 或 setUpdatesContinuously(true) 来启用。每当 SeekBar 在屏幕上的位置发生变化时就会触发此事件。

API 变更

• 向 findPreference() 添加了缺少的可空性注释。

bug 修复

• 修复了当未启用复制时无法正确移除上下文菜单监听器的 bug

版本 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 及以下变更。

bug 修复

• 修复了 EditTextPreference 对话框中有时不显示复制/粘贴弹出窗口的问题
• 修复了基础适配器无法正确取消注册的问题，该问题可在特定条件下造成内存泄漏 (b/121006469)
• 修复了配置更改期间发生的一些与对话框有关的崩溃问题 (b/122167543)
• 修复了 SummaryProvider 无法用于 MultiSelectListPreference 的问题 (b/123022772)

版本 1.1.0-alpha02

2018 年 12 月 17 日

另请查看最近更新的设置指南和示例应用。

新功能

• 添加了 EditTextPreference.OnBindEditTextListener 接口。这将允许在对话框绑定之后，自定义该对话框中显示的 EditText。例如，设置自定义输入类型/长度或添加 TextWatcher。

• 添加了 Preference.setCopyingEnabled()。设置后，长按 Preference 会显示上下文菜单，以便于您复制 Preference 的摘要。这可用于允许复制静态信息，例如特定于用户的 ID/应用版本信息。

• preferenceTheme 现在应用于 Activity 主题。这意味着，当您从代码创建 Preference 时，不需要再使用来自 PreferenceManager#getContext() 的上下文，而只需使用您的 Fragment/Activity 上下文即可。

API 变更

• 重构了 findPreference() 以返回 <T extends Preference>。这意味着，在使用 findPreference() 时不需要显式转换 Preference。例如，EditTextPreference preference = findPreference(“edit_text”) 现在是有效的代码。

版本 1.1.0-alpha01

2018 年 11 月 5 日

新功能

• 您现在可以在 Preference 上设置 SummaryProvider，以便能够在 Preference 更新或变为对用户可见时动态配置其摘要。
• 添加了 ListPreference 和 EditTextPreference 的默认 SummaryProvider 实现。设置后，这两个实现会自动更新 Preference 的摘要，以反映其保存的值，若未保存值，则显示“Not Set”。可以通过 app:useSimpleSummaryProvider=”true” 设置这两个实现
• 添加了 PreferenceGroup#removePreferenceRecursively，这会以递归方式在组中或层次结构中较低层级上的嵌套组中查找和移除 Preference。

API 变更

• 弃用了 PreferenceFragment 及其他使用框架 Fragment 的类。您应改为使用 PreferenceFragmentCompat 和其他 compat 类。

bug 修复

• 修复了 iconSpaceReserved 无法搭配 PreferenceCategory 正常工作的问题。
• 修复了当 API 级别低于 21 时，PreferenceCategory 无法将 colorAccent 用于其标题颜色的问题。
• 修复了当 API 级别低于 21 时，一些 SeekBarPreference 布局不一致的问题。