偏好设置

构建交互式设置屏幕，无需与设备存储交互或管理 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() 方法来提供标题面板。在标题 PreferenceFragmentCompat 中的任何使用 app:fragment 的 <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 包含这些提交。

错误修复

  • PreferenceDialogFragmentCompat 在从 xml 中加载 FragmentContainerView 时将不再抛出 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 类。
  • 您现在可以在首选项上设置 SummaryProvider，以便在首选项更新或对用户可见时动态配置其摘要。有关更多信息，请参阅 指南。
  • 添加了 EditTextPreference.OnBindEditTextListener 接口。这允许在对话框绑定后自定义在相应对话框中显示的 EditText。这是使用 EditTextPreference 上的 android:inputType 等属性的直接替代方法，这些属性在 AndroidX 库中不受支持。有关更多信息，请参阅 指南。
  • 添加了 Preference.setCopyingEnabled() 当设置后，长按首选项将显示一个上下文菜单，允许复制首选项的摘要。
  • 更新了 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
  • 此方法代理了特定首选项的可访问性节点信息 - 但这不是此自定义的正确层。如果您想调整可访问性信息，则应改为覆盖 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 类。
  • 您现在可以在首选项上设置 SummaryProvider，以便在首选项更新或对用户可见时动态配置其摘要。有关更多信息，请参阅 指南。
  • 添加了 EditTextPreference.OnBindEditTextListener 接口。这允许在对话框绑定后自定义在相应对话框中显示的 EditText。这是使用 EditTextPreference 上的 android:inputType 等属性的直接替代方法，这些属性在 AndroidX 库中不受支持。有关更多信息，请参阅 指南。
  • 添加了 Preference.setCopyingEnabled() 当设置后，长按首选项将显示一个上下文菜单，允许复制首选项的摘要。
  • 更新了 SeekBarPreference 样式以匹配 Material 规范。有关 SeekBarPreference 的其他更改，请参阅详细的 更改日志。
  • 大量的错误修复、样式更新、API 级别兼容性修复和常规 QOL 改进。

自 1.1.0-alpha05 以来 API 更改

  • 从公共 API 中删除 getOnBindEditTextListener，在与该 API 交互时，您只需要使用 setOnBindEditTextListener。

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

版本 1.1.0-alpha05

2019 年 5 月 7 日

androidx.preference:preference:1.1.0-alpha05 和 androidx.preference:preference-ktx:1.1.0-alpha05 发布。此版本中包含的提交可以在 此处 找到。

新功能

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

错误修复

  • 修复了 PreferenceCategory 和其他不可选择首选项在选中时会出现波纹效果的回归问题
  • 修复了 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() 添加了缺少的可空性注释。

错误修复

  • 修复了一个错误，如果未启用复制，则上下文菜单侦听器不会被正确删除。

版本 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）。
  • 修复了 MultiSelectListPreference 中 SummaryProvider 不起作用的问题（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 更改

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

错误修复

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