Biblioteca de compatibilidad

Nota: Con el lanzamiento de Android 9.0 (nivel de API 28), hay una nueva versión de la biblioteca de compatibilidad, denominada AndroidX, que es parte de Jetpack. La biblioteca de AndroidX contiene la biblioteca de compatibilidad existente e incluye los últimos componentes de Jetpack.

Puedes seguir usando la biblioteca de compatibilidad. Los artefactos históricos (aquellos con versiones 27 y anteriores, y empaquetados como android.support.*) seguirán estando disponibles en Google Maven. Sin embargo, todo el desarrollo de bibliotecas nuevas se llevará a cabo en la biblioteca de AndroidX.

Recomendamos usar las bibliotecas de AndroidX en todos los proyectos nuevos. Otra opción es migrar los proyectos existentes a AndroidX también.

Cuando desarrollas apps que admitan varias versiones de API, usa una forma estándar de proporcionar funciones nuevas en las versiones anteriores de Android o recurrir a funcionalidades equivalentes. En lugar de crear código para admitir versiones anteriores de la plataforma, puedes aprovechar estas bibliotecas para proporcionar esa capa de compatibilidad. Además, las bibliotecas de compatibilidad brindan clases de conveniencia adicionales y características que no están disponibles en la API de framework estándar para facilitar el desarrollo y la compatibilidad en más dispositivos.

La biblioteca de compatibilidad de Android originalmente era una única biblioteca binaria para apps y se ha convertido en un conjunto de bibliotecas para el desarrollo de apps. Muchas de estas bibliotecas ahora son un elemento muy recomendable, o hasta esencial, del desarrollo de apps.

Este documento proporciona una descripción general de la biblioteca de compatibilidad que ayuda a comprender sus componentes y cómo usarla de manera efectiva en una app.

Precaución: A partir de la versión 26.0.0 de la biblioteca de compatibilidad (julio de 2017), el nivel mínimo de API admitido en la mayoría de las bibliotecas de compatibilidad pasó a Android 4.0 (nivel de API 14) para la mayoría de los paquetes de bibliotecas. Para para obtener más información, consulta Compatibilidad con versiones y Paquete Nombres en esta página.

Usos de las bibliotecas de compatibilidad

Hay diversos usos para las bibliotecas de compatibilidad. Un ejemplo son las clases de retrocompatibilidad para versiones previas de la plataforma. Aquí hay una lista más completa de las formas en que se pueden usar las bibliotecas de compatibilidad en una app:

• Retrocompatibilidad para las API más nuevas: una gran cantidad de bibliotecas de compatibilidad ofrecen retrocompatibilidad para las clases de framework y métodos posteriores. Por ejemplo, la clase de compatibilidad Fragment permite usar fragmentos en dispositivos que ejecutan versiones anteriores a Android 3.0 (nivel de API 11).
• Clases de conveniencia y ayuda: las bibliotecas de compatibilidad proporcionan varias clases de ayuda, especialmente para el desarrollo de la interfaz de usuario. Para ejemplo, la clase RecyclerView le brinda a un usuario de interfaz para mostrar y administrar listas muy largas, que se puede usar en de Android a partir del nivel de API 7.
• Depuración y utilidades: hay varias funciones que proporcionan una utilidad más allá del código que incorporas en tu app, incluida la biblioteca support-annotations, que mejora el control de lint de código en entradas de métodos y brinda compatibilidad con Multidex para configurar y distribuir apps con más de 65,536 métodos.

Cómo usar la compatibilidad en lugar de API de framework

Las bibliotecas de compatibilidad proporcionan clases y métodos que se asemejan mucho a las API en el framework de Android. Esto puede llevar a preguntarse si deberías usar la versión del framework de la API o la biblioteca de compatibilidad equivalente. Estas son las pautas para identificar las situaciones en que conviene usar clases de biblioteca de compatibilidad en lugar de API de framework:

• Compatibilidad para una característica específica: si deseas admitir una característica reciente de una plataforma en dispositivos que ejecutan versiones anteriores de esa plataforma, usa las clases y los métodos equivalentes de la biblioteca de compatibilidad.
• Compatibilidad con funciones de biblioteca relacionadas: las clases de biblioteca de compatibilidad más complejas pueden depender de una o más clases adicionales, por lo que debes usar clases de biblioteca de compatibilidad para cumplir esas dependencias. Por ejemplo, se debe usar la clase de compatibilidad ViewPager con FragmentPagerAdapter o con las clases de compatibilidad FragmentStatePagerAdapter.
• Compatibilidad general del dispositivo: Aunque no haya una función de la plataforma específica que quieras usar con tu app de una manera retrocompatible, igual se recomienda usar clases de biblioteca de compatibilidad en la app. Por ejemplo, puedes usar ActivityCompat en lugar de la clase Activity del framework para aprovechar las funciones más recientes en otro momento, como la incorporación del nuevo modelo de permisos introducido en Android 6.0 (nivel de API 23).

Es posible que las clases de biblioteca de compatibilidad que permiten una implementación compatible de las clases de API de la plataforma no puedan proporcionar todas las funciones disponibles en la versión más reciente, debido a las limitaciones de la versión de la plataforma del dispositivo host. En esos casos, las clases de biblioteca de compatibilidad están diseñadas para degradarse sin inconvenientes, y es posible que no proporcionen todas las funciones o los datos de la API de la plataforma actual. Por este motivo, se recomienda revisar la documentación de referencia correspondiente a las clases de biblioteca y los métodos que utilizas, así como hacer pruebas exhaustivas en los dispositivos que ejecutan la versión más antigua de la plataforma compatible con la app.

Nota: Las bibliotecas de compatibilidad no proporcionan clases y métodos equivalentes para cada API de framework. En algunos casos, puede ser necesario unir una llamada de método de framework con una versión de SDK explícita y proporcionar un código alternativo para procesar los métodos que no están disponibles en un dispositivo. Si quieres obtener más información sobre el uso de controles de versión en el código, consulta Cómo brindar compatibilidad con diferentes versiones de la plataforma.

Compatibilidad con versiones y nombres de paquetes

Algunos de los paquetes de la biblioteca de compatibilidad tienen nombres para indicar el nivel mínimo de API que originalmente admitían, que se identifica con notación v#, por ejemplo, el paquete support-v4. A partir de la versión 26.0.0 de la biblioteca de compatibilidad (lanzada en julio de 2017), el nivel mínimo de API admitido pasó a Android 4.0 (nivel de API 14) para todos los paquetes de biblioteca de compatibilidad. Por este motivo, al trabajar con cualquier versión reciente de la biblioteca de compatibilidad, no se debe asumir que la notación del paquete v# indica compatibilidad con un nivel de API mínimo. Este cambio en las versiones recientes también significa que los paquetes de bibliotecas marcados como v4 y v7 son equivalentes en el nivel mínimo de API que admiten. Por ejemplo, los paquetes support-v4 y support-v7 admiten un nivel mínimo de API 14 para las versiones de la biblioteca de compatibilidad 26.0.0 y superiores.

Versiones de actualizaciones de la biblioteca de compatibilidad

La versión de actualización de la biblioteca de compatibilidad, como 24.2.0 o 25.0.1, es diferente del nivel de API mínimo admitido por cualquier biblioteca de esa actualización. El número de actualización indica con qué versión de API de la plataforma se creó y, por lo tanto, qué API más recientes pueden incluirse en esa versión de las bibliotecas.

Específicamente, la primera sección del número de versión de actualización, por ejemplo, el 24 en la versión 24.2.0, suele corresponder a la versión de la API de la plataforma disponible cuando se lanzó. El nivel de versión de actualización de la biblioteca de compatibilidad indica que incorpora algunas características de ese nivel de API, pero no necesariamente que proporciona compatibilidad con todas las características incluidas en la nueva versión de API de la plataforma.

Dependencias de bibliotecas

La mayoría de las bibliotecas del conjunto de bibliotecas de compatibilidad de Android tienen cierta dependencia de una o más bibliotecas. Por ejemplo, casi todas las bibliotecas de compatibilidad dependen del paquete support-compat. En general, no es necesario preocuparse por las dependencias de la biblioteca de compatibilidad, ya que la herramienta de compilación Gradle administra las dependencias de la biblioteca incluyendo automáticamente las bibliotecas dependientes.

Para ver qué bibliotecas y dependencias incluye tu app, ejecuta el siguiente comando en la raíz de compilación del proyecto de desarrollo de la app a fin de obtener un informe de las dependencias de ese proyecto, incluidas las bibliotecas de compatibilidad de Android y otras bibliotecas:

gradle -q dependencies your-app-project:dependencies

Para obtener más información sobre cómo agregar bibliotecas de compatibilidad a tu desarrollo proyecto con Gradle, consulta Compatibilidad Configuración de la biblioteca Para obtener más información sobre cómo trabajar con Gradle, consulta Configurar Tu compilación.

Ten en cuenta que todas las bibliotecas de compatibilidad de Android también dependen de algún nivel base de la plataforma en versiones recientes, es decir, Android 4.0 (nivel de API 14) o versiones posteriores.