Preference

Crie telas de configurações interativas sem precisar interagir com o armazenamento do dispositivo ou gerenciar a IU.
Atualização mais recente Versão estável Versão candidata a lançamento Versão Beta Versão Alfa
26 de julho de 2023 1.2.1 - - -

Declarar dependências

Para adicionar uma dependência à Preference, é preciso adicionar o repositório Maven do Google ao seu projeto. Leia Repositório Maven do Google para ver mais informações.

Adicione as dependências dos artefatos necessários no arquivo build.gradle para seu app ou módulo:

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

Para ver mais informações sobre dependências, consulte Adicionar dependências de build.

Feedback

Seu feedback ajuda a melhorar o Jetpack. Avise se você descobrir novos problemas ou tiver ideias para melhorar esta biblioteca. Consulte os problemas conhecidos nesta biblioteca antes de criar um novo. Adicione seu voto a um problema clicando no botão de estrela.

Criar novo problema

Consulte a documentação do Issue Tracker para saber mais.

Versão 1.2

Versão 1.2.1

26 de julho de 2023

Lançamento de androidx.preference:preference:1.2.1. A versão 1.2.1 contém estas confirmações.

Correções de bugs

  • PreferenceHeaderFragmentCompat agora lida corretamente com o botão "Voltar" do sistema quando usado em um ComponentDialog ou ao usar bibliotecas como a @AndroidEntryPoint do Hilt, que unem o Context do fragmento
  • A preferência agora depende da Atividade 1.5.1. (Ie5d22).
  • PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment agora propaga header.extras como os argumentos Fragment.

Versão 1.2.0

26 de janeiro de 2022

Lançamento de androidx.preference:preference:1.2.0 e androidx.preference:preference-ktx:1.2.0. A versão 1.2.0 contém estas confirmações.

Mudanças importantes desde a 1.1.0

  • O elemento PreferenceHeaderFragmentCompat foi adicionado para a preferência de dois painéis que se adaptam automaticamente com base no tamanho do dispositivo usado, o que o torna adequado para uso em smartphones, dispositivos dobráveis e tablets. O painel de cabeçalho é fornecido substituindo o método onCreatePreferenceHeader() em PreferenceHeaderFragmentCompat. Qualquer <Preference> no cabeçalho PreferenceFragmentCompat que use app:fragment faz com que esse fragmento seja exibido no segundo painel de detalhes. O fragmento de detalhes inicial que precisa ser exibido antes de qualquer preferência ser selecionada manualmente pode ser personalizado substituindo onCreateInitialDetailFragment(). A implementação padrão retorna a primeira preferência que tem um fragmento definido.
class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

  • Foram adicionadas anotações de nulidade a várias das APIs que não especificavam @NonNull ou @Nullable Essa é uma alteração interruptiva da origem do Kotlin se a nulidade que você escolheu no código Kotlin não corresponder à nulidade que agora está definida.

  • O PreferenceFragmentCompat agora procura implementações da interface OnPreferenceStartFragmentCallback, OnNavigateToScreenListener e OnDisplayPreferenceDialogListener em fragmentos pai antes de verificar se o contexto de hospedagem ou a atividade implementam essas interfaces.

Versão 1.2.0-rc01

15 de dezembro de 2021

Lançamento de androidx.preference:preference:1.2.0-rc01 e androidx.preference:preference-ktx:1.2.0-rc01, sem mudanças desde a 1.2.0-beta01. A versão 1.2.0-rc01 contém estas confirmações.

Versão 1.2.0-beta01

17 de novembro de 2021

Lançamento de androidx.preference:preference:1.2.0-beta01 e androidx.preference:preference-ktx:1.2.0-beta01, sem mudanças desde a versão Preference 1.2.0-alpha02. A versão 1.2.0-beta01 contém estas confirmações.

Versão 1.2.0-alpha02

3 novembro de 2021

Lançamento de androidx.preference:preference:1.2.0-alpha02 e androidx.preference:preference-ktx:1.2.0-alpha02. A versão 1.2.0-alpha02 contém estas confirmações.

Mudanças na API

  • Foram adicionadas anotações de nulidade a várias das APIs que não especificavam @NonNull ou @Nullable (I04252, Ie2cc0).
  • A API openPreference() foi removida da PreferenceHeaderFragmentCompat. Esse método é chamado automaticamente e não pode ser chamado de forma manual (Ia6989).

Mudanças de comportamento

  • Os callbacks de PreferenceFragmentCompat para OnNavigateToScreenListener e OnDisplayPreferenceDialogListener agora seguem o mesmo padrão de OnPreferenceTreeClickListener e procuram a hierarquia de fragmentos pai para detectar listeners válidos antes de ver se o contexto ou a atividade de hospedagem implementam essas interfaces (I7ae6c).

Versão 1.2.0-alpha01

27 de outubro de 2021

Lançamento de androidx.preference:preference:1.2.0-alpha01 e androidx.preference:preference-ktx:1.2.0-alpha01. A versão 1.2.0-alpha01 contém estas confirmações.

Novos recursos

  • O PreferenceHeaderFragmentCompat foi adicionado para preferência de dois painéis (I9a2d8).

Mudanças de comportamento

  • Os callbacks de preferências para os métodos OnPreferenceDisplayDialogCallback, OnPreferenceStartScreenCallback e OnPreferenceStartFragmentCallback agora podem ser implementados em um contexto não relacionado à atividade. getContext() é verificado para confirmar se ele implementa esses callbacks antes de verificar getActivity(). Se o método getContext() retornar uma atividade (o caso comum), não haverá mudança de comportamento.

  • A chamada de PreferenceFragmentCompat para onPreferenceTreeClick agora procura implementações da interface OnPreferenceStartFragmentCallback em fragmentos pai antes de considerar a implementação da atividade (c64eed).

Versão 1.1

Versão 1.1.1

15 de abril de 2020

Lançamento de androidx.preference:preference:1.1.1 e androidx.preference:preference-ktx:1.1.1. A versão 1.1.1 contém estas confirmações.

Correções de bugs

  • PreferenceDialogFragmentCompat não gerará mais um IllegalStateException ao inflar um FragmentContainerView do XML (b/150051716, links do issue tracker em inglês).

Atualizações de dependência

  • A preferência agora depende do Fragment 1.2.4 (aosp/1277317).
  • A dependência preference-ktx agora depende de androidx.core:core-ktx:1.1.0 e androidx.fragment:fragment-ktx:1.2.4, espelhando as dependências do artefato preference principal e garantindo que o upgrade de preference-ktx atualize os artefatos principal e -ktx das dependências transitivas (aosp/1277319, links do AOSP em inglês).

Versão 1.1.0

5 de setembro de 2019

Lançamento de androidx.preference:preference:1.1.0 e androidx.preference:preference-ktx:1.1.0. As confirmações incluídas nessa versão podem ser encontradas neste link.

Se esta é a primeira vez que você atualiza para uma versão 1.1.*, veja esta lista concisa das principais alterações desde a última versão estável, 1.0.0. O Guia de configurações, o app de amostra e a palestra da Conferência de Desenvolvedores Android (vídeo em inglês) também podem ser úteis.

Mudanças importantes desde a versão 1.0.0

  • Suspensão do uso de PreferenceFragment e de outras classes que usavam Fragments de framework. Use PreferenceFragmentCompat e outras classes *compatíveis.
  • Agora você pode definir um SummaryProvider em uma Preference para configurar dinamicamente o resumo relacionado sempre que a Preference for atualizada ou se tornar visível para o usuário. Para ver mais informações, consulte o guia.
  • Adicionada interface EditTextPreference.OnBindEditTextListener Essa ação permite personalizar o EditText exibido na caixa de diálogo correspondente, depois que essa caixa é vinculada. Essa é uma substituição direta para o uso de atributos como android:inputType diretamente no EditTextPreference, que não é compatível com a biblioteca do AndroidX. Para ver mais informações, consulte o guia.
  • Adicionado Preference.setCopyingEnabled(). Quando definido, a ação de tocar na Preference e mantê-la pressionada mostrará um menu de contexto que permite copiar o resumo da Preference.
  • Atualizado estilo SeekBarPreference para corresponder às especificações do Material Design. Consulte o registro de mudanças detalhado para ver outras mudanças em SeekBarPreference.
  • Várias correções de bugs, atualizações de estilo, correções de compatibilidade com o nível da API e melhorias gerais de qualidade de vida.

Versão 1.1.0-rc01

2 de julho de 2019

Lançamento de androidx.preference:preference:1.1.0-rc01 e androidx.preference:preference-ktx:1.1.0-rc01. As confirmações incluídas nessa versão podem ser encontradas neste link.

Mudanças na API

  • O uso de Preference#onInitializeAccessibilityNodeInfo foi suspenso
  • Esse método colocou informações do nó de acessibilidade em proxy para uma Preference específica, mas essa é a camada incorreta para essa personalização. Se você quer ajustar as informações de acessibilidade, modifique onBindViewHolder e adicione as informações de acessibilidade diretamente à visualização.

Versão 1.1.0-beta01

5 de junho de 2019

Lançamento de androidx.preference:preference:1.1.0-beta01 e androidx.preference:preference-ktx:1.1.0-beta01. As confirmações incluídas nessa versão podem ser encontradas aqui (link em inglês).

Mudanças importantes desde a 1.1.0

Se esta é a primeira vez que você atualiza para uma versão 1.1.*, veja esta lista concisa das principais alterações desde a última versão estável, 1.1.0. O Guia de configurações, o app de amostra e a palestra da Conferência de Desenvolvedores Android (vídeo em inglês) também podem ser úteis.

  • Suspensão do uso de PreferenceFragment e de outras classes que usavam Fragments de framework. Use PreferenceFragmentCompat e outras classes *compatíveis.
  • Agora você pode definir um SummaryProvider em uma Preference para configurar dinamicamente o resumo relacionado sempre que a Preference for atualizada ou se tornar visível para o usuário. Para ver mais informações, consulte o guia.
  • Adicionada interface EditTextPreference.OnBindEditTextListener Essa ação permite personalizar o EditText exibido na caixa de diálogo correspondente, depois que essa caixa é vinculada. Essa é uma substituição direta para o uso de atributos como android:inputType diretamente no EditTextPreference, que não é compatível com a biblioteca do AndroidX. Para ver mais informações, consulte o guia.
  • Adicionado Preference.setCopyingEnabled(). Quando definido, a ação de tocar na Preference e mantê-la pressionada mostrará um menu de contexto que permite copiar o resumo da Preference.
  • Atualizado estilo SeekBarPreference para corresponder às especificações do Material Design. Consulte o registro de alterações detalhado para ver outras mudanças em SeekBarPreference.
  • Várias correções de bugs, atualizações de estilo, correções de compatibilidade com o nível da API e melhorias gerais de qualidade de vida.

Mudanças na API desde 1.1.0-alpha05

  • Remoção de getOnBindEditTextListener da API pública. Basta usar setOnBindEditTextListener ao interagir com essa API.

Informe os bugs neste link caso você encontre algum problema ou tenha sugestões para novos recursos.

Versão 1.1.0-alpha05

7 de maio de 2019

Lançamento de androidx.preference:preference:1.1.0-alpha05 e androidx.preference:preference-ktx:1.1.0-alpha05. As confirmações incluídas nessa versão podem ser encontradas neste link.

Novos recursos

  • Atualizado estilo para Preferences não selecionáveis. O título e o resumo agora compartilham a mesma cor para deixar claro que não é possível interagir com eles e que são usados apenas para exibir informações.
  • Observação: você pode adicionar enableCopying="true" a preferências não selecionáveis. Assim, será possível usar a ação de tocar e manter pressionado para copiar o resumo.

Correções de bugs

  • Correção de uma regressão em que PreferenceCategory e outras Preferences não selecionáveis tinham um efeito de ondulação quando selecionadas.
  • Correção de um problema de acessibilidade em que o TalkBack não via DropDownPreference como clicável.
  • Correção de alguns problemas de layout RTL.
  • Atualização de algumas anotações anuláveis em PreferenceFragmentCompat para corresponder ao Fragment.

Versão 1.1.0-alpha04

13 de março de 2019

Lançamento de androidx.preference:preference:1.1.0-alpha04 e androidx.preference:preference-ktx:1.1.0-alpha04. A lista completa de confirmações incluídas nessa versão pode ser encontrada aqui (link em inglês).

Novos recursos

Atualização de SeekBarPreference.

  • Atualizado estilo para corresponder às especificações do Material Design.
    • O rótulo de valor agora fica oculto por padrão, embora ainda possa ser exibido com app:showSeekBarValue="true"ou setShowSeekBarValue(true). Esse rótulo não faz parte das especificações do Material Design, mas entendemos que ele é muito usado. Por isso, a compatibilidade será mantida, mesmo que não seja recomendável usá-lo.
    • O rótulo de valor agora é atualizado enquanto a SeekBar é arrastada, em vez de ao soltá-la. Isso não significa que o valor seja atualizado internamente. Veja abaixo uma nova API que ativa essa funcionalidade.
    • Observação: embora seja possível, evite definir um resumo em uma SeekBarPreference, uma vez que essa ação não visa as especificações do Material Design nem faz parte delas.
  • Adicionada compatibilidade para atualizações contínuas, permitindo que a SeekBar atualize o valor salvo enquanto estiver sendo arrastada. Essa opção pode ser ativada no XML ou programaticamente, com app:updatesContinuously="true" ou setUpdatesContinuously(true). Ela será acionada sempre que a posição da SeekBar na tela mudar.

Mudanças na API

  • Adição de anotações de anulação ausentes a findPreference()

Correções de bugs

  • Correção de um bug em que os listeners do menu de contexto não eram removidos corretamente se a cópia não estivesse ativada.

Versão 1.1.0-alpha03

7 de fevereiro de 2019

androidx.preference:preference 1.1.0-alpha03

Lançamento de androidx.preference:preference 1.1.0-alpha03 e androidx.preference:preference-ktx 1.1.0-alpha03 com as seguintes mudanças.

Correções de bugs

  • Correção de um problema em que o pop-up copiar/colar nem sempre aparecia na caixa de diálogo de EditTextPreference.
  • Correção de um problema em que o adaptador subjacente não era registrado corretamente, causando vazamentos de memória em condições específicas. (b/121006469)
  • Correção de algumas falhas relacionadas a caixas de diálogo que ocorreram durante alterações de configuração. (b/122167543)
  • Correção de SummaryProvider, que não funcionava para MultiSelectListPreference. (b/123022772)

Versão 1.1.0-alpha02

17 de dezembro de 2018

Confira também o Guia de configurações e o app de amostra atualizados recentemente.

Novos recursos

  • Adicionada interface EditTextPreference.OnBindEditTextListener. Essa ação permite personalizar o EditText exibido na caixa de diálogo correspondente, depois que essa caixa é vinculada. Por exemplo, definindo um tipo/comprimento de entrada personalizado ou adicionando um TextWatcher.

  • Adicionado Preference.setCopyingEnabled(). Quando definido, a ação de tocar na Preference e mantê-la pressionada mostrará um menu de contexto que permite copiar o resumo da Preference. Essa opção pode ser usada para permitir a cópia de informações estáticas, como IDs de usuários específicos ou informações da versão do aplicativo.

  • preferenceTheme agora é aplicado ao tema da atividade. Isso significa que, ao criar uma Preference a partir do código, você não precisa mais usar o contexto de PreferenceManager#getContext(). Basta usar o contexto do Fragment/Activity.

Mudanças na API

  • Refatoração de findPreference() para retornar <T extends Preference>. Isso significa que você não precisa transmitir Preferences explicitamente ao usar findPreference(). Por exemplo, EditTextPreference preference = findPreference(“edit_text”) agora é um código válido.

Versão 1.1.0-alpha01

5 de novembro de 2018

Novos recursos

  • Agora você pode definir um SummaryProvider em uma Preference para configurar dinamicamente o resumo relacionado sempre que a Preference for atualizada ou se tornar visível para o usuário.
  • Adicionadas implementações padrão de SummaryProvider para ListPreference e EditTextPreference, que, quando definidas, atualizam automaticamente o resumo da Preference para refletir o valor salvo ou "Not Set", se nenhum valor tiver sido salvo. Elas podem ser configuradas com app:useSimpleSummaryProvider=”true”.
  • Adicionada PreferenceGroup#removePreferenceRecursively, que localiza e remove recursivamente uma Preference do grupo ou um grupo aninhado mais abaixo na hierarquia.

Mudanças na API

  • Suspensão do uso de PreferenceFragment e de outras classes que usavam Fragments de framework. Use PreferenceFragmentCompat e outras classes compatíveis.

Correções de bugs

  • Correção de iconSpaceReserved, que não funcionava corretamente com PreferenceCategories.
  • Correção de PreferenceCategories, que não usavam colorAccent para a cor do título em APIs de níveis anteriores ao 21.
  • Corrigidas algumas inconsistências no layout de SeekBarPreference em APIs de níveis anteriores ao 21.