Ustawienie

Twórz interaktywne ekrany z ustawieniami bez konieczności korzystania z pamięci urządzenia czy zarządzania interfejsem.
Najnowsza aktualizacja Wersja stabilna Kandydat do publikacji Wersja Beta Wersja alfa
26 lipca 2023 r. 1.2.1 - - -

Deklarowanie zależności

Aby dodać zależność od preferencji, musisz dodać do projektu repozytorium Google Maven. Więcej informacji znajdziesz w repozytorium Google Maven.

W pliku build.gradle aplikacji lub modułu dodaj zależności artefaktów, których potrzebujesz:

Odlotowy

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

Więcej informacji o zależnościach znajdziesz w artykule Dodawanie zależności kompilacji.

Opinia

Twoja opinia pomoże nam ulepszyć Jetpack. Daj nam znać, jeśli znajdziesz nowe wydania lub masz pomysły na ulepszenie tej biblioteki. Zanim utworzysz nową bibliotekę, przejrzyj problemy z tą biblioteką. Możesz oddać głos w ramach istniejącego problemu, klikając przycisk gwiazdki.

Utwórz nowy numer

Więcej informacji znajdziesz w dokumentacji narzędzia Issue Tracker.

Wersja 1.2

Wersja 1.2.1

26 lipca 2023 r.

Aplikacja androidx.preference:preference:1.2.1 została zwolniona. Wersja 1.2.1 zawiera te zatwierdzenia.

Poprawki błędów

  • PreferenceHeaderFragmentCompat teraz prawidłowo obsługuje systemowy przycisk Wstecz, gdy jest używany w obrębie ComponentDialog lub podczas korzystania z bibliotek takich jak @AndroidEntryPoint Hilt, które opakowują obiekt Context fragmentu.
  • Ustawienia zależą teraz od Aktywności 1.5.1. (Ie5d22)
  • PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment propaguje teraz header.extras jako argumenty Fragment.

Wersja 1.2.0

26 stycznia 2022 r.

Opublikowano androidx.preference:preference:1.2.0 i androidx.preference:preference-ktx:1.2.0. Wersja 1.2.0 zawiera te zatwierdzenia.

Ważne zmiany od wersji 1.1.0

  • Dodano PreferenceHeaderFragmentCompat w ustawieniach dla 2 paneli, które automatycznie dostosowują się do rozmiaru używanego urządzenia. Dzięki temu można używać go na telefonach, urządzeniach składanych i tabletach. Panel nagłówka jest udostępniany przez zastąpienie metody onCreatePreferenceHeader() w tabeli PreferenceHeaderFragmentCompat. Każdy element <Preference> w nagłówku PreferenceFragmentCompat, który zawiera ciąg app:fragment, spowoduje, że dany fragment pojawi się w drugim panelu szczegółów. Początkowy fragment szczegółów, który powinien być wyświetlany przed ręcznym wybraniem dowolnego ustawienia, można dostosować, zastępując atrybut onCreateInitialDetailFragment(). Implementacja domyślna zwraca pierwsze ustawienie, które ma zdefiniowany fragment.
class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

  • Do wielu interfejsów API, które wcześniej nie określały @NonNull ani @Nullable, dodano adnotacje dotyczące wartości null. Jest to potencjalnie zmiana powodująca niezgodność źródła w Kotlin, jeśli wartość null wybrana w kodzie Kotlin nie pasuje do obecnie zdefiniowanej wartości null.

  • Mechanizm PreferenceFragmentCompat wyszukuje teraz implementacje interfejsu OnPreferenceStartFragmentCallback, OnNavigateToScreenListener i OnDisplayPreferenceDialogListener we fragmentach nadrzędnych, a następnie sprawdza, czy kontekst hostowania lub aktywność je implementują.

Wersja 1.2.0-rc01

15 grudnia 2021 roku

androidx.preference:preference:1.2.0-rc01 i androidx.preference:preference-ktx:1.2.0-rc01 są dostępne bez zmian od 1.2.0-beta01. Wersja 1.2.0-rc01 zawiera te zatwierdzenia.

Wersja 1.2.0-beta01

17 listopada 2021 r.

Wprowadzono androidx.preference:preference:1.2.0-beta01 i androidx.preference:preference-ktx:1.2.0-beta01 bez zmian w preferencjach 1.2.0-alfa02. Wersja 1.2.0-beta01 zawiera te zatwierdzenia.

Wersja 1.2.0-alfa02

3 listopada 2021 r.

Opublikowano androidx.preference:preference:1.2.0-alpha02 i androidx.preference:preference-ktx:1.2.0-alpha02. Wersja 1.2.0-alpha02 zawiera te zatwierdzenia.

Zmiany w interfejsie API

  • Do wielu interfejsów API, które wcześniej nie określały @NonNull ani @Nullable, dodano adnotacje dotyczące wartości null. (I04252, Ie2cc0)
  • Usunięto interfejs openPreference() API z metody PreferenceHeaderFragmentCompat – ta metoda jest wywoływana za Ciebie i nie należy jej wywoływać ręcznie. (Ia6989)

Zmiany w działaniu

  • Wywołania zwrotne PreferenceFragmentCompat dla interfejsu OnNavigateToScreenListener i OnDisplayPreferenceDialogListener mają teraz taki sam wzór jak w przypadku OnPreferenceTreeClickListener. Zanim sprawdzisz, czy kontekst hostingu lub Aktywność implementuje te interfejsy, przeszukaj hierarchię fragmentów nadrzędnych pod kątem prawidłowych odbiorników. (I7ae6c)

Wersja 1.2.0-alfa01

27 października 2021 roku

Opublikowano androidx.preference:preference:1.2.0-alpha01 i androidx.preference:preference-ktx:1.2.0-alpha01. Wersja 1.2.0-alpha01 zawiera te zatwierdzenia.

Nowe funkcje

  • Dodano element PreferenceHeaderFragmentCompat dla ustawienia 2 paneli (I9a2d8)

Zmiany w działaniu

  • Wywołania zwrotne preferencji dla OnPreferenceDisplayDialogCallback, OnPreferenceStartScreenCallback i OnPreferenceStartFragmentCallback można teraz implementować w kontekście innym niż aktywność. Metoda getContext() jest sprawdzana przed sprawdzeniem, czy implementuje te wywołania zwrotne, przed zaznaczeniem getActivity(). Jeśli getContext() zwraca aktywność (typowy przypadek), nie zmienia się zachowanie.

  • Wywołanie funkcji onPreferenceTreeClick przez funkcję PreferenceFragmentCompat szuka teraz implementacji interfejsu OnPreferenceStartFragmentCallback we fragmentach nadrzędnych przed rozważeniem implementacji działania. (c64eed)

Wersja 1.1

Wersja 1.1.1

15 kwietnia 2020 roku

Opublikowano androidx.preference:preference:1.1.1 i androidx.preference:preference-ktx:1.1.1. Wersja 1.1.1 zawiera te zatwierdzenia.

Poprawki błędów

  • PreferenceDialogFragmentCompat nie będzie już generować błędu IllegalStateException podczas zawyżania wartości FragmentContainerView z pliku XML. (b/150051716)

Aktualizacje zależności

  • Preferencje zależą teraz od fragmentu 1.2.4. (Aosp/1277317)
  • Zależność preference-ktx zależy teraz od androidx.core:core-ktx:1.1.0 i androidx.fragment:fragment-ktx:1.2.4, powielając zależności głównego artefaktu preference i upewniając się, że uaktualnienie preference-ktx aktualizuje zarówno główne artefakty, jak i -ktx artefakty zależności przechodnich. (Aosp/1277319)

Wersja 1.1.0

5 września 2019 r.

Opublikowano androidx.preference:preference:1.1.0 i androidx.preference:preference-ktx:1.1.0. Zatwierdzenia zawarte w tej wersji znajdziesz tutaj.

Jeśli jest to pierwsza wersja 1.1.*, do której przeprowadzasz aktualizację, oto zwięzła lista większych zmian od czasu ostatniej stabilnej wersji (1.0.0). Mogą Ci się też przydać informacje z przewodnika po ustawieniach, przykładowej aplikacji i prezentacji na temat Androida Dev Summit.

Ważne zmiany od wersji 1.0.0

  • Klasy PreferenceFragment i inne korzystające z fragmentów platformy zostały wycofane. Zamiast nich używaj klas PreferenceFragmentCompat i innych klas *compat.
  • Możesz teraz ustawić element SummaryProvider w preferencji, aby dynamicznie konfigurować jego podsumowanie po każdej aktualizacji preferencji lub gdy staje się widoczne dla użytkownika. Więcej informacji znajdziesz w przewodniku.
  • Dodano interfejs EditTextPreference.OnBindEditTextListener. Umożliwia to dostosowanie elementu EditText wyświetlanego w odpowiednim oknie po powiązaniu tego okna. To bezpośredni zamiennik używania atrybutów takich jak android:inputType bezpośrednio w EditTextPreference, który nie jest obsługiwany w bibliotece AndroidaX. Więcej informacji znajdziesz w przewodniku.
  • Dodano Preference.setCopyingEnabled() Po ustawieniu włączonego długiego przytrzymania Preferencji wyświetli się menu kontekstowe, które umożliwia skopiowanie podsumowania ustawień.
  • Zaktualizowano styl elementu SeekBarPreference, aby był zgodny ze specyfikacją Material. Informacje o innych zmianach w SeekBarPreference znajdziesz w szczegółowej historii zmian.
  • Duża liczba poprawek błędów, zmian stylu, poprawek zwiększających zgodność z poziomem interfejsu API oraz ogólne ulepszenia QOL.

Wersja 1.1.0-rc01

2 lipca 2019 r.

Opublikowano androidx.preference:preference:1.1.0-rc01 i androidx.preference:preference-ktx:1.1.0-rc01. Zatwierdzenia zawarte w tej wersji znajdziesz tutaj.

Zmiany w interfejsie API

  • Zrezygnuj z umowy Preference#onInitializeAccessibilityNodeInfo
  • Ta metoda korzysta z informacji o węźle ułatwień dostępu przez serwer proxy dla określonej preferencji, ale to niewłaściwa warstwa do tego dostosowania. Jeśli chcesz dostosować informacje o ułatwieniach dostępu, zastąp te informacje wartością onBindViewHolder i dodaj informacje o ułatwieniach dostępu bezpośrednio do widoku.

Wersja 1.1.0-beta01

5 czerwca 2019 r.

Opublikowano androidx.preference:preference:1.1.0-beta01 i androidx.preference:preference-ktx:1.1.0-beta01. Zatwierdzenia zawarte w tej wersji znajdziesz tutaj.

Ważne zmiany od wersji 1.1.0

Jeśli jest to pierwsza wersja 1.1.*, do której przeprowadzasz aktualizację, oto zwięzła lista większych zmian od momentu opublikowania ostatniej stabilnej wersji 1.1.0. Mogą Ci się też przydać informacje z przewodnika po ustawieniach, przykładowej aplikacji i prezentacji na temat Androida Dev Summit.

  • Klasy PreferenceFragment i inne klasy korzystające z fragmentów platformy zostały wycofane. Zamiast nich użyj klas PreferenceFragmentCompat i innych klas *compat.
  • Możesz teraz ustawić komponent PodsumowanieProvider na preferencji, aby dynamicznie konfigurować jego podsumowanie po każdej zmianie preferencji lub gdy staje się ono widoczne dla użytkownika. Więcej informacji znajdziesz w przewodniku.
  • Dodano interfejs EditTextPreference.OnBindEditTextListener. Umożliwia to dostosowanie tekstu EditText wyświetlanego w odpowiednim oknie po jego powiązaniu. Zastąpi on korzystanie z atrybutów takich jak android:inputType bezpośrednio w EditTextPreference, który nie jest obsługiwany w bibliotece AndroidX. Więcej informacji znajdziesz w przewodniku.
  • Dodano Preference.setCopyingEnabled() Po ustawieniu włączonego długiego przytrzymania Preferencji wyświetli się menu kontekstowe, które umożliwia skopiowanie podsumowania ustawień.
  • Zaktualizowano styl SeekBarPreference, aby dopasować go do specyfikacji Material. Informacje o innych zmianach w SeekBarPreference znajdziesz w szczegółowym historii zmian.
  • Duża liczba poprawek błędów, zmian stylu, poprawek zwiększających zgodność z poziomem interfejsu API oraz ogólne ulepszenia QOL.

Zmiany w interfejsie API od wersji 1.1.0-alfa05

  • Usuwa metodę getOnBindEditTextListener z publicznego interfejsu API. Podczas interakcji z tym interfejsem API należy używać tylko funkcji setOnBindEditTextListener.

Jeśli napotkasz problemy lub masz sugestie dotyczące nowych funkcji, możesz zgłaszać je tutaj.

Wersja 1.1.0-alfa05

7 maja 2019 r.

Opublikowano androidx.preference:preference:1.1.0-alpha05 i androidx.preference:preference-ktx:1.1.0-alpha05. Zatwierdzenia zawarte w tej wersji znajdziesz tutaj.

Nowe funkcje

  • Zmieniliśmy styl ustawień, których nie można wybrać. Tytuł i podsumowanie mają teraz ten sam kolor, aby było jasne, że nie można ich używać w internecie i są używane tylko do wyświetlania informacji.
  • Uwaga: możesz też dodać element enableCopying="true" do ustawień, których nie można wybrać, aby przytrzymać przycisk, aby skopiować podsumowanie.

Poprawki błędów

  • Naprawiono regresję, w której PreferenceCategory i inne niewybrane ustawienia miały efekt fali po wybraniu.
  • Rozwiązaliśmy problem z ułatwieniami dostępu, który powodował, że funkcja TalkBack nie widziała elementu DropDownPreference jako klikalnego.
  • Usunięto niektóre błędy układu od prawej do lewej.
  • Zaktualizowano niektóre adnotacje z możliwością wartości null w elemencie PreferenceFragmentCompat, aby dopasować je do fragmentu Fragment.

Wersja 1.1.0-alfa04

13 marca 2019 r.

Opublikowano androidx.preference:preference:1.1.0-alpha04 i androidx.preference:preference-ktx:1.1.0-alpha04. Pełną listę zatwierdzeń zawartych w tej wersji znajdziesz tutaj.

Nowe funkcje

Aktualizacja SeekBarPreference

  • Styl został zaktualizowany, aby dopasować go do specyfikacji materiału
    • Etykieta wartości jest teraz domyślnie ukryta, ale nadal można ją wyświetlać za pomocą app:showSeekBarValue="true" i setShowSeekBarValue(true). Ta etykieta nie jest częścią specyfikacji Material, ale zdajemy sobie sprawę, że jest ona intensywnie wykorzystywana, więc nadal będziemy ją wspierać, mimo że nie zalecamy jej używania.
    • Etykieta wartości jest teraz aktualizowana podczas przeciągania paska SeekBar, a nie po jego zwolnieniu. Pamiętaj, że nie oznacza to, że wartość jest aktualizowana wewnętrznie. Poniżej znajdziesz nowy interfejs API, który udostępnia tę funkcję.
    • Uwaga: chociaż ta funkcja jest obsługiwana, nie należy ustawiać podsumowania na podstawie właściwości SeekBarPreference, ponieważ nie jest to zamierzone i nie jest częścią specyfikacji Material.
  • Dodano obsługę ciągłych aktualizacji, dzięki czemu pasek SeekBar może aktualizować zapisaną wartość podczas przeciągania paska SeekBar. Można to włączyć za pomocą pliku XML lub automatycznie za pomocą funkcji app:updatesContinuously="true" lub setUpdatesContinuously(true). Jest on uruchamiany przy każdej zmianie pozycji paska SeekBar na ekranie.

Zmiany w interfejsie API

  • Dodaje brakujące adnotacje wartości null do elementu findPreference()

Poprawki błędów

  • Naprawiono błąd, który powodował, że detektory menu kontekstowego nie były prawidłowo usuwane, jeśli kopiowanie było wyłączone.

Wersja 1.1.0-alfa03

7 lutego 2019 r.

androidx.preference:preference 1.1.0-alfa03

androidx.preference:preference 1.1.0-alpha03 i androidx.preference:preference-ktx 1.1.0-alpha03 są udostępniane z następującymi zmianami.

Poprawki błędów

  • Naprawiono błąd, który powodował, że wyskakujące okienko kopiowania/wklejania czasem nie było wyświetlane w oknie EditTextPreference.
  • Rozwiązaliśmy problem, który powodował, że podstawowa karta nie była prawidłowo rejestrowana, co powodowało wyciek pamięci w określonych warunkach (b/121006469).
  • Usunięto niektóre awarie związane z oknami, które występowały podczas zmiany konfiguracji (b/122167543).
  • Naprawiony element PodsumowanieProvider nie działa w przypadku MultiSelectListPreference (b/123022772)

Wersja 1.1.0-alfa02

17 grudnia 2018 r.

Zapoznaj się też z niedawno zaktualizowanym przewodnikiem po ustawieniach i przykładową aplikacją.

Nowe funkcje

  • Dodano interfejs EditTextPreference.OnBindEditTextListener Pozwala to dostosować tekst EditText wyświetlany w odpowiednim oknie dialogowym po ograniczeniu tego okna. np. przez ustawienie niestandardowego typu lub długości danych wejściowych albo dodanie TextWatcher.

  • Dodano Preference.setCopyingEnabled() Gdy ustawienie jest ustawione, przytrzymaj Preferencję, aby wyświetlić menu kontekstowe, które umożliwia skopiowanie podsumowania ustawień. Pozwala to na kopiowanie informacji statycznych, takich jak identyfikatory użytkownika lub informacje o wersji aplikacji.

  • Preferencje są teraz stosowane do motywu aktywności. Oznacza to, że podczas tworzenia preferencji na podstawie kodu nie musisz już korzystać z kontekstu PreferenceManager#getContext() – możesz użyć kontekstu Fragment/Aktywność.

Zmiany w interfejsie API

  • Zrefaktoryzowano funkcję findPreference(), aby zwrócić <T extends Preference>. Oznacza to, że podczas korzystania z funkcji findPreference() nie musisz wyraźnie rzutować ustawień. Na przykład EditTextPreference preference = findPreference(“edit_text”) jest teraz prawidłowym kodem.

Wersja 1.1.0-alfa01

5 listopada 2018 r.

Nowe funkcje

  • Możesz teraz ustawić komponent PodsumowanieProvider na preferencji, aby dynamicznie konfigurować jego podsumowanie po każdej zmianie preferencji lub gdy staje się ono widoczne dla użytkownika.
  • Dodano domyślne implementacje interfejsuSummaryProvider dla elementów ListPreference i EditTextPreference, które po skonfigurowaniu automatycznie zaktualizują podsumowanie preferencji, aby odzwierciedlały zapisane wartości, lub „Nie ustawiono”, jeśli nie zostały zapisane. Można je ustawić za pomocą parametru app:useSimpleSummaryProvider=”true”
  • Dodano PreferenceGroup#removePreferenceRecursively, które rekurencyjnie znajdują i usuwają preferencję z grupy lub zagnieżdżoną grupę niżej w hierarchii.

Zmiany w interfejsie API

  • Klasy PreferenceFragment i inne klasy korzystające z fragmentów platformy zostały wycofane. Zamiast nich używaj klasy PreferenceFragmentCompat i innych klas compat.

Poprawki błędów

  • Naprawiono ikonę SpaceReserve nieprawidłowo działała z kategoriami preferencji.
  • Poprawiono Preferencekategorii poniżej interfejsu API 21, który nie używa parametru colorAccent w przypadku koloru tytułu.
  • Naprawiono pewne niespójności w układzie SeekBarPreference poniżej interfejsu API 21.