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

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

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

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

Последнее обновление	Стабильный релиз	Предварительная версия релиза	Бета-версия	Альфа-версия
26 июля 2023 г.	1.2.1	-	-	-

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

Чтобы добавить зависимость от Preference, необходимо добавить репозиторий Google Maven в ваш проект. Для получения дополнительной информации ознакомьтесь с информацией в репозитории Google Maven .

Добавьте зависимости для необходимых артефактов в файл build.gradle вашего приложения или модуля:

классный

dependencies {
    def preference_version = "1.2.1"

    // Java language implementation
    implementation "androidx.preference:preference:$preference_version"
    // Kotlin
    implementation "androidx.preference:preference-ktx:$preference_version"
}

Котлин

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()
    }
}

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

Версия 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-beta01

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-alpha02

3 ноября 2021 г.

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

Изменения в API

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

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

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

Версия 1.2.0-alpha01

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 могут быть реализованы в контексте, отличном от Activity. Перед проверкой getActivity() проверяется, реализует ли getContext() эти колбэки. Если getContext() возвращает Activity (распространенный случай), то никаких изменений в поведении не происходит.
Теперь вызов метода onPreferenceTreeClick из класса PreferenceFragmentCompat ищет реализации интерфейса OnPreferenceStartFragmentCallback в родительских фрагментах, прежде чем рассматривать реализацию в Activity. ( 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. ( b/150051716 )

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

Теперь предпочтения зависят от фрагмента 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

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

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

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 Dev Summit .

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

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

Удаляет функцию getOnBindEditTextListener из публичного API; вам потребуется использовать setOnBindEditTextListener только при взаимодействии с этим API.

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

Версия 1.1.0-alpha05

7 мая 2019 г.

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

Новые функции

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

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

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

Версия 1.1.0-alpha04

13 марта 2019 г.

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

Новые функции

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

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

изменения API

Добавляет отсутствующие аннотации, указывающие на возможность значения null, в функцию findPreference()

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

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

Версия 1.1.0-alpha03

7 февраля 2019 г.

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

17 декабря 2018 г.

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

Новые функции

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

изменения API

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

Версия 1.1.0-alpha01

5 ноября 2018 г.

Новые функции

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

изменения API

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

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

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