偏好设置

构建交互式设置屏幕，无需与设备存储交互或管理 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 版本包含这些提交。

错误修复

PreferenceHeaderFragmentCompat现在可以在ComponentDialog中使用或使用像 Hilt 的@AndroidEntryPoint这样的包装 Fragment 的Context的库时正确处理系统后退按钮。
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() 方法来提供。在使用 app:fragment 的标题 PreferenceFragmentCompat 中的任何 <Preference> 将导致该片段出现在第二个详细信息面板中。可以通过覆盖 onCreateInitialDetailFragment() 来自定义在手动选择任何首选项之前应显示的初始详细信息片段。默认实现返回第一个在其上定义了片段的首选项。

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

为许多以前未指定 @NonNull 或 @Nullable 的 API 添加了可空性注解。如果在 Kotlin 代码中选择的可空性与现在定义的可空性不匹配，则这可能是 Kotlin 源代码的重大更改。
现在，PreferenceFragmentCompat 会在查看托管 Context 或 Activity 是否实现这些接口之前，先在其父片段中查找 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 是否实现这些接口之前，先查找父片段层次结构中有效的侦听器。（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 Context 中实现 OnPreferenceDisplayDialogCallback、OnPreferenceStartScreenCallback 和 OnPreferenceStartFragmentCallback 的首选项回调。在检查 getActivity() 之前，会检查 getContext() 是否实现了这些回调。如果 getContext() 返回 Activity（常见情况），则行为不会发生变化。
现在，PreferenceFragmentCompat 对 onPreferenceTreeClick 的调用会在考虑 Activity 的实现之前，先在其父片段中查找 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 版本包含这些提交。

错误修复

当从 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 Dev Summit 演讲有用。

自 1.0.0 版本以来的重要更改

PreferenceFragment 和其他使用框架片段的类已被弃用；您应该改用 PreferenceFragmentCompat 和其他 *compat 类。
您现在可以在 Preference 上设置 SummaryProvider，以便在更新 Preference 或 Preference 对用户可见时动态配置其摘要。有关更多信息，请参阅指南。
添加了 EditTextPreference.OnBindEditTextListener 接口。这允许在对话框绑定后自定义在相应对话框中显示的 EditText。这是直接替换在 EditTextPreference 上直接使用属性（例如 android:inputType）的方法，这在 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 Dev Summit 演讲有用。

PreferenceFragment 和其他使用框架片段的类已被弃用 - 您应该改用 PreferenceFragmentCompat 和其他 *compat 类。
您现在可以在 Preference 上设置 SummaryProvider，以便在更新 Preference 或 Preference 对用户可见时动态配置其摘要。有关更多信息，请参阅指南。
添加了 EditTextPreference.OnBindEditTextListener 接口。这允许在对话框绑定后自定义在相应对话框中显示的 EditText。这是直接替换在 EditTextPreference 上直接使用属性（例如 android:inputType）的方法，这在 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。此版本包含的提交可以在此处找到。

新功能

更新了不可选择的 Preferences 的样式 - 标题和摘要现在共享相同的颜色，以便清楚地表明它们无法交互，仅用于显示信息。
注意：您可能需要考虑向不可选择的 Preferences 添加 enableCopying="true"，以便您可以长按复制摘要。

错误修复

修复了 PreferenceCategory 和其他不可选择的 Preferences 在选中时会出现波纹效果的回归问题。
修复了 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 在拖动 SeekBar 时更新其保存的值。这可以通过 XML 或编程方式启用，使用 app:updatesContinuously="true" 或 setUpdatesContinuously(true)。这将在屏幕上 SeekBar 的位置发生变化时触发。

API 变更

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

错误修复

修复了如果未启用复制，则上下文菜单侦听器未正确移除的错误。

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，并进行了以下更改。

错误修复

修复了复制/粘贴弹出窗口有时不会在 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 现在应用于活动主题。这意味着，当从代码创建 Preference 时，您不再需要使用 PreferenceManager#getContext() 中的上下文 - 您只需使用您的 Fragment/Activity 上下文即可。

API 变更

重构了 findPreference() 以返回 <T extends Preference>。这意味着在使用 findPreference() 时，您无需显式转换 Preferences。例如，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 变更

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

错误修复

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