Эта страница переведена с помощью Cloud Translation API.

Предпочтение

Справочник по API
androidx.preference

Создавайте интерактивные экраны настроек без необходимости взаимодействия с хранилищем устройства или управления пользовательским интерфейсом.

Последнее обновление	Стабильный выпуск	Кандидат на выпуск	Бета-версия	Альфа-релиз
26 июля 2023 г.	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

26 июля 2023 г.

androidx.preference:preference:1.2.1 выпущен. Версия 1.2.1 содержит эти коммиты.

Исправления ошибок

PreferenceHeaderFragmentCompat теперь правильно обрабатывает системную кнопку «Назад» при использовании в ComponentDialog или при использовании таких библиотек, как @AndroidEntryPoint Hilt, которые оборачивают Context фрагмента.
Предпочтение теперь зависит от действия 1.5.1. ( Ie5d22 )
PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment теперь распространяет header.extras в качестве аргументов Fragment .

Версия 1.2.0

26 января 2022 г.

androidx.preference:preference:1.2.0 и androidx.preference:preference-ktx:1.2.0 выпущены. Версия 1.2.0 содержит эти коммиты.

Важные изменения с версии 1.1.0

Добавлен PreferenceHeaderFragmentCompat для настройки двух панелей, которая автоматически адаптируется в зависимости от размера используемого устройства, что делает его пригодным для использования на телефонах, складных устройствах и планшетах. Панель заголовка создается путем переопределения метода onCreatePreferenceHeader() в PreferenceHeaderFragmentCompat . Любой <Preference> в заголовке PreferenceFragmentCompat , который использует app:fragment приведет к появлению этого фрагмента во второй области сведений. Исходный фрагмент сведений, который должен отображаться перед выбором каких-либо предпочтений вручную, можно настроить, переопределив onCreateInitialDetailFragment() . Реализация по умолчанию возвращает первое предпочтение, для которого определен фрагмент.

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

Добавлены аннотации об отсутствии значений для многих API, которые ранее не указывали @NonNull или @Nullable . Это потенциально критическое изменение исходного кода Kotlin, если допустимость значений NULL, которую вы выбрали в своем коде Kotlin, не соответствует допустимости NULL, которая теперь определена.
PreferenceFragmentCompat теперь ищет реализации интерфейсов OnPreferenceStartFragmentCallback , OnNavigateToScreenListener и OnDisplayPreferenceDialogListener в родительских фрагментах, прежде чем проверять, реализует ли контекст или действие хостинга эти интерфейсы.

Версия 1.2.0-rc01

15 декабря 2021 г.

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-бета01

17 ноября 2021 г.

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-альфа02

3 ноября 2021 г.

Выпущены androidx.preference:preference:1.2.0-alpha02 и androidx.preference:preference-ktx:1.2.0-alpha02 . Версия 1.2.0-alpha02 содержит эти коммиты.

Изменения API

Добавлены аннотации об отсутствии значений для многих API, которые ранее не указывали @NonNull или @Nullable . ( I04252 , Ie2cc0 )
Удален API openPreference() из PreferenceHeaderFragmentCompat — этот метод вызывается за вас, и его не следует вызывать вручную. ( Ia6989 )

Изменения поведения

Обратные вызовы PreferenceFragmentCompat для OnNavigateToScreenListener и OnDisplayPreferenceDialogListener теперь следуют тому же шаблону, что и OnPreferenceTreeClickListener , и просматривают иерархию родительских фрагментов для допустимых прослушивателей, прежде чем проверять, реализует ли контекст или действие размещения эти интерфейсы. ( I7ae6c )

Версия 1.2.0-альфа01

27 октября 2021 г.

Выпущены androidx.preference:preference:1.2.0-alpha01 и androidx.preference:preference-ktx:1.2.0-alpha01 . Версия 1.2.0-alpha01 содержит эти коммиты.

Новые возможности

Добавлен PreferenceHeaderFragmentCompat для настройки двух панелей ( I9a2d8 ).

Изменения поведения

Обратные вызовы предпочтений для OnPreferenceDisplayDialogCallback, OnPreferenceStartScreenCallback и OnPreferenceStartFragmentCallback теперь можно реализовать в контексте, не связанном с активностью. getContext() проверяется, реализует ли он эти обратные вызовы, прежде чем проверять getActivity(). Если getContext() возвращает Activity (обычный случай), то изменений в поведении нет.
Вызов PreferenceFragmentCompat к onPreferenceTreeClick теперь ищет реализации интерфейса OnPreferenceStartFragmentCallback в родительских фрагментах, прежде чем рассматривать реализацию действия. ( c64eed )

Версия 1.1

Версия 1.1.1

15 апреля 2020 г.

androidx.preference:preference:1.1.1 и androidx.preference:preference-ktx:1.1.1 выпущены. Версия 1.1.1 содержит эти коммиты.

Исправления ошибок

PreferenceDialogFragmentCompat больше не будет вызывать исключение IllegalStateException при раздувании FragmentContainerView из xml. ( б / 150051716 )

Обновления зависимостей

Предпочтение теперь зависит от фрагмента 1.2.4 . ( аосп/1277317 )
Зависимость preference-ktx теперь зависит от androidx.core:core-ktx:1.1.0 и androidx.fragment:fragment-ktx:1.2.4 , отражая зависимости основного артефакта preference и гарантируя, что обновление preference-ktx обновит как артефакты main и -ktx транзитивных зависимостей. ( аосп/1277319 )

Версия 1.1.0

5 сентября 2019 г.

androidx.preference:preference:1.1.0 и androidx.preference:preference-ktx:1.1.0 выпущены. Коммиты, включенные в эту версию, можно найти здесь .

Если это первая 1.1.* , которую вы обновляете, вот краткий список более крупных изменений со времени последней стабильной версии 1.0.0 . Вам также могут пригодиться руководство по настройкам , пример приложения и доклад на саммите разработчиков Android .

Важные изменения с версии 1.0.0

PreferenceFragment и другие классы, использующие фрагменты фреймворка, устарели; вместо этого вам следует использовать PreferenceFragmentCompat и другие классы *compat.
Теперь вы можете настроить SummaryProvider для предпочтения, чтобы динамически настраивать его сводку всякий раз, когда предпочтение обновляется или становится видимым для пользователя. Дополнительную информацию смотрите в руководстве .
Добавлен интерфейс EditTextPreference.OnBindEditTextListener . Это позволяет настроить EditText , отображаемый в соответствующем диалоговом окне после его привязки. Это прямая замена использования таких атрибутов, как android:inputType , непосредственно в EditTextPreference , что не поддерживается в библиотеке AndroidX. Дополнительную информацию смотрите в руководстве .
Добавлен Preference.setCopyingEnabled() Если этот параметр установлен, при длительном нажатии на Предпочтение отобразится контекстное меню, позволяющее скопировать сводку Предпочтения.
Обновлен стиль SeekBarPreference в соответствии со спецификациями материалов. См. подробный журнал изменений , чтобы узнать о других изменениях в SeekBarPreference .
Большое количество исправлений ошибок, обновлений стилей, исправлений совместимости на уровне API и общих улучшений качества жизни.

Версия 1.1.0-rc01

2 июля 2019 г.

androidx.preference:preference:1.1.0-rc01 и androidx.preference:preference-ktx:1.1.0-rc01 выпущены. Коммиты, включенные в эту версию, можно найти здесь .

Изменения API

Устаревшее Preference#onInitializeAccessibilityNodeInfo
Этот метод проксировал информацию об узле доступности для определенного предпочтения, но это неправильный уровень для этой настройки. Если вы хотите настроить информацию о доступности, вам следует вместо этого переопределить onBindViewHolder и добавить информацию о доступности непосредственно в представление.

Версия 1.1.0-бета01

5 июня 2019 г.

Выпущены 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 и другие классы, использующие фрагменты инфраструктуры, устарели — вместо этого вам следует использовать PreferenceFragmentCompat и другие классы *compat.
Теперь вы можете настроить SummaryProvider для предпочтения, чтобы динамически настраивать его сводку всякий раз, когда предпочтение обновляется или становится видимым для пользователя. Дополнительную информацию смотрите в руководстве .
Добавлен интерфейс EditTextPreference.OnBindEditTextListener . Это позволяет настроить EditText, отображаемый в соответствующем диалоговом окне после его привязки. Это прямая замена использования таких атрибутов, как android:inputType, непосредственно в EditTextPreference, что не поддерживается в библиотеке AndroidX. Дополнительную информацию смотрите в руководстве .
Добавлен Preference.setCopyingEnabled() Если этот параметр установлен, при длительном нажатии на Предпочтение отобразится контекстное меню, позволяющее скопировать сводку Предпочтения.
Обновлен стиль SeekBarPreference в соответствии со спецификациями материалов. См. подробный журнал изменений , чтобы узнать о других изменениях в SeekBarPreference.
Большое количество исправлений ошибок, обновлений стилей, исправлений совместимости на уровне API и общих улучшений качества жизни.

Изменения API с версии 1.1.0-alpha05

Удаляет getOnBindEditTextListener из общедоступного API, вам нужно будет использовать только setOnBindEditTextListener при взаимодействии с этим API.

Пожалуйста, сообщайте об ошибках здесь, если у вас возникнут какие-либо проблемы или если у вас есть предложения по новым функциям!

Версия 1.1.0-альфа05

7 мая 2019 г.

Выпущены androidx.preference:preference:1.1.0-alpha05 и androidx.preference:preference-ktx:1.1.0-alpha05 . Коммиты, включенные в эту версию, можно найти здесь .

Новые возможности

Обновлен стиль для невыбираемых настроек: заголовок и сводка теперь имеют один и тот же цвет, чтобы было понятно, что с ними нельзя взаимодействовать и они используются только для отображения информации.
Примечание. Возможно, вы захотите добавить enableCopying="true" в невыбираемые настройки, чтобы вы могли долго нажимать, чтобы скопировать сводку.

Исправления ошибок

Исправлена регрессия, из-за которой PreferenceCategory и другие невыбираемые настройки имели волновой эффект при выборе.
Исправлена проблема с доступностью, из-за которой TalkBack не считал DropDownPreference доступным для нажатия.
Исправлены некоторые проблемы с макетом RTL.
Обновлены некоторые аннотации, допускающие значение NULL, в PreferenceFragmentCompat для соответствия Fragment.

Версия 1.1.0-альфа04

13 марта 2019 г.

Выпущены androidx.preference:preference:1.1.0-alpha04 и androidx.preference:preference-ktx:1.1.0-alpha04 . Полный список коммитов, включённых в эту версию, можно найти здесь .

Новые возможности

Обновление SeekBarPreference !

Стиль обновлен в соответствии со спецификациями материалов.
- Метка значения теперь по умолчанию скрыта, хотя ее все еще можно отобразить с помощью app:showSeekBarValue="true" или setShowSeekBarValue(true) . Этот ярлык не является частью спецификации материала, но мы понимаем, что он активно используется, поэтому продолжим его поддерживать, хотя и не рекомендуем его использовать.
- Метка значения теперь обновляется во время перетаскивания SeekBar, а не при его отпускании. Обратите внимание, что это не означает, что значение обновляется внутри: см. ниже новый API, который включает эту функцию.
- Примечание. Несмотря на то, что это поддерживается, вам следует избегать установки сводки для SeekBarPreference, поскольку она не предназначена и не является частью спецификации материала.
Добавляет поддержку непрерывных обновлений, позволяя SeekBar обновлять сохраненное значение во время перетаскивания SeekBar. Это можно включить из XML или программно, с помощью app:updatesContinuously="true" или setUpdatesContinuously(true) . Это сработает всякий раз, когда изменится положение SeekBar на экране.

Изменения API

Добавляет отсутствующие аннотации об отсутствии значений в findPreference()

Исправления ошибок

Исправлена ошибка, из-за которой прослушиватели контекстного меню не удалялись корректно, если копирование не включено.

Версия 1.1.0-альфа03

7 февраля 2019 г.

androidx.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-альфа02

17 декабря 2018 г.

Также ознакомьтесь с недавно обновленным руководством по настройкам и примером приложения .

Новые возможности

Добавлен интерфейс EditTextPreference.OnBindEditTextListener Это позволяет настраивать EditText, отображаемый в соответствующем диалоговом окне после его привязки. Например, установка пользовательского типа/длины ввода или добавление TextWatcher.
Добавлен Preference.setCopyingEnabled() Если этот параметр установлен, при длительном нажатии на Предпочтение отобразится контекстное меню, позволяющее скопировать сводку Предпочтения. Это можно использовать для копирования статической информации, такой как идентификаторы пользователя или информация о версии приложения.
PreferenceTheme теперь применяется к теме активности. Это означает, что при создании предпочтения из кода вам больше не нужно использовать контекст из PreferenceManager#getContext() — вы можете просто использовать контекст фрагмента/активности.

Изменения API

Переработан findPreference() теперь он возвращает <T extends Preference> Это означает, что вам не нужно явно указывать Preferences при использовании findPreference(). Например, EditTextPreference preference = findPreference(“edit_text”) теперь является допустимым кодом.

Версия 1.1.0-альфа01

5 ноября 2018 г.

Новые возможности

Теперь вы можете настроить SummaryProvider для предпочтения, чтобы динамически настраивать его сводку всякий раз, когда предпочтение обновляется или становится видимым для пользователя.
Добавлены реализации SummaryProvider по умолчанию для ListPreference и EditTextPreference, которые при установке автоматически обновляют сводку предпочтения, чтобы отразить его сохраненное значение, или «Не установлено», если значение не было сохранено. Их можно установить с помощью app:useSimpleSummaryProvider="true"
Добавлен PreferenceGroup#removePreferenceRecursily, который рекурсивно находит и удаляет предпочтение из группы или вложенной группы ниже в иерархии.

Изменения API

PreferenceFragment и другие классы, использующие фрагменты инфраструктуры, устарели — вместо этого вам следует использовать PreferenceFragmentCompat и другие совместимые классы.

Исправления ошибок

Исправлена ошибка, из-за которой iconSpaceReserved некорректно работал с PreferenceCategories.
Исправлена ошибка, из-за которой PreferenceCategories не использовала colorAccent для цвета заголовка ниже API 21.
Исправлены некоторые несоответствия макета SeekBarPreference ниже API 21.