Preference

构建交互式设置屏幕，无需与设备存储交互或管理 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。如果您发现新问题或有改进此库的想法，请告诉我们。在创建新问题之前，请查看此库中的现有问题。您可以通过点击星形按钮为您关注的现有问题添加投票。

创建新问题

有关更多信息，请参阅问题跟踪器文档。

版本 1.2

版本 1.2.1

2023 年 7 月 26 日

androidx.preference:preference:1.2.1 已发布。版本 1.2.1 包含以下提交。

Bug 修复

当在 ComponentDialog 中使用时，或在使用 Hilt 的 @AndroidEntryPoint 等包装 Fragment Context 的库时，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 添加了可空性注解。如果您的 Kotlin 代码中选择的可空性与现在定义的可空性不匹配，这可能会导致 Kotlin 源中断性变更。
PreferenceFragmentCompat 现在会在检查托管 Context 或 Activity 是否实现这些接口之前，先在父级 fragment 上查找 OnPreferenceStartFragmentCallback、OnNavigateToScreenListener 和 OnDisplayPreferenceDialogListener 接口的实现。

版本 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 添加了可空性注解。（I04252，Ie2cc0）
从 PreferenceHeaderFragmentCompat 中移除了 openPreference() API - 此方法会自动为您调用，不应手动调用。（Ia6989）

行为变更

PreferenceFragmentCompat 的 OnNavigateToScreenListener 和 OnDisplayPreferenceDialogListener 回调现在遵循与 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）

行为变更

OnPreferenceDisplayDialogCallback、OnPreferenceStartScreenCallback 和 OnPreferenceStartFragmentCallback 的偏好设置回调现在可以在非 Activity Context 中实现。在检查 getActivity() 之前，会先检查 getContext() 是否实现了这些回调。如果 getContext() 返回一个 Activity（常见情况），则行为没有变化。
PreferenceFragmentCompat 对 onPreferenceTreeClick 的调用现在会在考虑 Activity 的实现之前，先在父级 fragment 上查找 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 包含以下提交。

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。这是直接在 EditTextPreference 上使用 android:inputType 等属性的直接替代方案，而 AndroidX 库不支持后者。有关更多信息，请参阅指南。
添加了 Preference.setCopyingEnabled()。设置后，长按 Preference 将显示一个上下文菜单，允许复制 Preference 的摘要。
更新了 SeekBarPreference 样式以匹配 Material 规范。有关 SeekBarPreference 的其他更改，请参阅详细的更新日志。
大量的 bug 修复、样式更新、API 级别兼容性修复和通用生活质量改进。

版本 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。这是直接在 EditTextPreference 上使用 android:inputType 等属性的直接替代方案，而 AndroidX 库不支持后者。有关更多信息，请参阅指南。
添加了 Preference.setCopyingEnabled()。设置后，长按 Preference 将显示一个上下文菜单，允许复制 Preference 的摘要。
更新了 SeekBarPreference 样式以匹配 Material 规范。有关 SeekBarPreference 的其他更改，请参阅详细的更新日志。
大量的 bug 修复、样式更新、API 级别兼容性修复和通用生活质量改进。

自 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 中的一些可空注解以匹配 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 的摘要以反映其保存的值，如果未保存任何值则显示“未设置”。这些可以通过 app:useSimpleSummaryProvider=”true” 进行设置。
添加了 PreferenceGroup#removePreferenceRecursively，它递归地从组或层次结构中更深层的嵌套组中查找并移除 Preference。

API 变更

PreferenceFragment 和其他使用框架 Fragment 的类已被弃用 - 您应该改用 PreferenceFragmentCompat 和其他兼容类。

Bug 修复

修复了 iconSpaceReserved 在 PreferenceCategories 中无法正常工作的问题。
修复了在 API 21 以下 PreferenceCategories 未使用 colorAccent 作为其标题颜色的问题。
修复了在 API 21 以下 SeekBarPreference 布局的一些不一致问题。