Support Library

Observação: com o lançamento do Android 9.0 (API de nível 28), há uma nova versão da Biblioteca de Suporte denominada AndroidX, que faz parte do Jetpack. O AndroidX contém a Biblioteca de Suporte existente e inclui os componentes mais recentes do Jetpack.

Você pode continuar usando a Biblioteca de Suporte. Os artefatos históricos com versões 27 e anteriores, e empacotados como android.support.*, permanecerão disponíveis no Google Maven. No entanto, todo o desenvolvimento da nova biblioteca ocorrerá na biblioteca AndroidX.

Recomendamos o uso das bibliotecas AndroidX em todos os novos projetos. Considere também migrar os projetos existentes para o AndroidX.

Ao desenvolver apps compatíveis com várias versões da API, você pode querer uma maneira padrão de fornecer recursos mais novos a versões anteriores do Android ou de retornar a uma funcionalidade equivalente. Em vez de criar código para lidar com versões anteriores da plataforma, use essas bibliotecas para fornecer essa camada de compatibilidade. Além disso, as Bibliotecas de Suporte fornecem outras classes de conveniência e recursos não disponíveis na API de framework padrão para facilitar o desenvolvimento e a compatibilidade com mais dispositivos.

Originalmente uma única biblioteca binária para apps, a Biblioteca de Suporte do Android evoluiu para um pacote de bibliotecas para o desenvolvimento de apps. Muitas dessas bibliotecas são agora uma parte altamente recomendável, se não essencial, do desenvolvimento de apps.

Este documento fornece uma visão geral da Biblioteca de Suporte para ajudar você a entender os componentes e como usá-la efetivamente no seu app.

Cuidado: desde a versão 26.0.0 (julho de 2017) da Biblioteca de Suporte, o nível mínimo de API compatível com a maioria das bibliotecas de suporte aumentou para o Android 4.0 (API de nível 14) para a maioria dos pacotes de bibliotecas. Para mais informações, consulte Suporte de versão e pacote nomes nesta página.

Usos para as bibliotecas de suporte

Existem alguns usos distintos para as bibliotecas de suporte. Classes de compatibilidade para versões anteriores da plataforma são apenas um deles. Veja uma lista mais completa de maneiras de usar as bibliotecas de suporte no seu app:

• Compatibilidade retroativa para APIs mais recentes: uma grande quantidade das bibliotecas de suporte fornecem compatibilidade com versões anteriores para classes e métodos de framework mais recentes. Por exemplo, a classe de suporte Fragment oferece compatibilidade com fragmentos em dispositivos com versões anteriores ao Android 3.0 (API de nível 11).
• Conveniência e classes auxiliares: as bibliotecas de suporte fornecem várias classes auxiliares, especialmente para o desenvolvimento da interface do usuário. Para Exemplo: a classe RecyclerView fornece ao usuário de interface de usuário para exibir e gerenciar listas muito longas, utilizáveis em versões do Android do nível 7 da API e mais recentes.
• Depuração e utilitários: há vários recursos que oferecem utilidade além do código que você incorpora ao app, incluindo a biblioteca support-annotations para verificações lint avançadas em entradas de método e compatibilidade com Multidex para configurar e distribuir apps com mais de 65.536 métodos.

Uso de APIs de suporte em comparação a APIs de framework

As Bibliotecas de Suporte fornecem classes e métodos se assemelham às APIs no framework do Android. Ao descobrir isso, você pode se perguntar se precisa usar a versão de framework da API ou o equivalente da Biblioteca de Suporte. Aqui estão as diretrizes sobre quando usar classes de biblioteca de suporte, em vez das APIs de framework:

• Compatibilidade com um recurso específico: se você quer oferecer compatibilidade com um recurso de plataforma recente em dispositivos que executam versões anteriores da plataforma, use as classes e métodos equivalentes da Biblioteca de Suporte.
• Compatibilidade com recursos de biblioteca relacionados: classes de biblioteca de suporte mais sofisticadas dependem de uma ou mais classes de biblioteca de suporte diferentes, portanto, use-as para essas dependências. Por exemplo, a classe de suporte ViewPager precisa ser usada com as classes de suporte FragmentPagerAdapter ou FragmentStatePagerAdapter.
• Compatibilidade geral com dispositivos: mesmo se você não tiver um recurso de plataforma específico que pretenda usar com seu app de forma compatível com versões anteriores, ainda é uma boa ideia usar as classes de biblioteca de suporte no app. Por exemplo, você pode usar ActivityCompat no lugar da classe de framework Activity, para aproveitar os recursos mais recentes mais tarde, como incorporar o novo modelo de permissões introduzido no Android 6.0 (API de nível 23).

As classes da Biblioteca de Suporte que fornecem uma implementação compatível das classes da API da plataforma podem não oferecer todas as funcionalidades disponíveis na última versão devido às limitações da versão da plataforma do dispositivo host. Nesses casos, as classes da Biblioteca de Suporte são projetadas para serem reduzidas normalmente e podem não fornecer todas as funcionalidades ou os dados da API da plataforma atual. Por esse motivo, consulte a documentação de referência para as classes e os métodos de biblioteca que você usa e faça um teste completo em dispositivos que executam a versão mais antiga da plataforma compatível com o app.

Observação: as bibliotecas de suporte não oferecem classes e métodos equivalentes para cada API de framework. Em alguns casos, é necessário envolver uma chamada de método de framework com uma verificação explícita da versão do SDK e fornecer um código alternativo para gerenciar os métodos não disponíveis em um dispositivo. Para mais informações sobre como usar verificações de versão no seu código, consulte Compatibilidade com diferentes versões da plataforma.

Compatibilidade com versões e nomes de pacotes

Alguns dos pacotes da Biblioteca de Suporte têm nomes para indicar o nível mínimo da API com compatibilidade original, usando a notação vnº, como o pacote support-v4. Desde a versão 26.0.0 da Biblioteca de Suporte (lançada em julho de 2017), o nível mínimo de API compatível foi mudado para Android 4.0 (API de nível 14) para todos os pacotes de biblioteca de suporte. Por esse motivo, ao trabalhar com qualquer versão recente da Biblioteca de Suporte, não presuma que a notação do pacote vnº indique um nível mínimo de compatibilidade com a API. Essa mudança nas versões recentes também significa que os pacotes de biblioteca com v4 e v7 são essencialmente equivalentes quanto ao nível mínimo de API com que são compatíveis. Por exemplo, os pacotes support-v4 e support-v7 são compatíveis com um nível mínimo de API de 14, para as versões da Biblioteca de Suporte 26.0.0 e mais recentes.

Versões da Biblioteca de Suporte

A versão de lançamento da Biblioteca de Suporte, como 24.2.0 ou 25.0.1, é diferente do nível mínimo de API compatível com qualquer biblioteca nessa versão. O número indica em qual versão da API da plataforma ela foi criada e, portanto, quais APIs mais recentes podem ser incluídas nessa versão das bibliotecas.

Especificamente, a primeira seção do número da versão de lançamento, por exemplo, o 24 na versão 24.2.0, geralmente corresponde à versão da API de plataforma disponível quando foi lançada. O nível da versão de lançamento da Biblioteca de Suporte indica que ela incorpora alguns recursos desse nível de API, mas não é possível presumir que ela ofereça compatibilidade com todos os recursos lançados na nova versão da API de plataforma.

Dependências de biblioteca

A maioria das bibliotecas no pacote da Biblioteca de Suporte do Android tem alguma dependência em uma ou mais bibliotecas. Por exemplo, quase todas as Bibliotecas de Suporte dependem do pacote support-compat. Em geral, não é preciso se preocupar com as dependências da Biblioteca de Suporte, porque a ferramenta de compilação Gradle as gerencia para você ao incluir automaticamente as bibliotecas dependentes.

Se você quiser ver quais bibliotecas e dependências estão incluídas no seu app, execute o seguinte comando na raiz da versão do projeto de desenvolvimento do app para ver um relatório das dependências desse projeto, incluindo Bibliotecas de Suporte do Android e outras:

gradle -q dependencies your-app-project:dependencies

Para mais informações sobre como adicionar Bibliotecas de Suporte ao seu projeto de desenvolvimento usando o Gradle, consulte Configuração da Biblioteca de Suporte. Para ver mais informações sobre como trabalhar com o Gradle, consulte Configurar sua versão.

Observe que todas as Bibliotecas de Suporte do Android também dependem de algum nível básico da plataforma para versões recentes, que é o Android 4.0 (API de nível 14) ou mais recentes.