Información general sobre los recursos de las aplicaciones

Los recursos son los archivos adicionales y el contenido estático que usa tu código, como mapas de bits, cadenas de interfaz de usuario, instrucciones de animación, etcétera.

Siempre debes externalizar los recursos para apps, como imágenes y cadenas de tu código, para que puedas mantenerlos de forma independiente. Además, debes proporcionar recursos alternativos para configuraciones de dispositivos específicas agrupándolos en directorios de recursos con un nombre especial. En el tiempo de ejecución, Android utiliza el recurso adecuado según la configuración actual. Por ejemplo, puedes proporcionar diferentes cadenas según la configuración de idioma.

Una vez que externalizas los recursos para tu app, puedes acceder a ellos mediante los IDs de recursos que se generan en la clase R de tu proyecto. En este documento, se muestra cómo puedes agrupar los recursos en tu proyecto de Android. También se muestra cómo proporcionar recursos alternativos para configuraciones de dispositivos específicos y acceder a ellos desde el código de tu app u otros archivos en formato XML posteriormente.

Agrupa los recursos según su tipo

Debes colocar cada tipo de recurso en un subdirectorio específico del directorio res/ de tu proyecto. Por ejemplo, esta es la jerarquía de archivos de un proyecto simple:

MyProject/
    src/
        MyActivity.kt
    res/
        drawable/
            graphic.png
        mipmap/
            icon.png
        values/
            strings.xml

El directorio res/ contiene todos los recursos en sus subdirectorios: un recurso de imagen, un directorio mipmap/ para los íconos de selector y un archivo de recursos de cadenas. Los nombres de los directorios de recursos son importantes y se describen en la tabla 1.

Nota: Para obtener más información sobre el uso de las carpetas mipmap, consulta Cómo agregar íconos de apps en directorios mipmap.

Tabla 1: Directorios de recursos admitidos dentro del directorio res/ del proyecto.

Advertencia: Nunca guardes archivos de recursos directamente dentro del directorio res/; si lo haces, se producirá un error en el compilador.

Los recursos que guardes en los subdirectorios definidos en la tabla 1 son tus recursos predeterminados. Es decir, estos recursos definen el diseño y el contenido predeterminados de tu app. Sin embargo, es posible que los diferentes tipos de dispositivos con tecnología Android necesiten distintos tipos de recursos.

Por ejemplo, puedes proporcionar diferentes recursos de cadenas que traduzcan el texto en la interfaz de usuario según la configuración de idioma del dispositivo.

Nota: En Compose, las IU, las animaciones y los colores controlados por el estado se declaran en Kotlin, por lo que los directorios layout/, menu/, anim/, animator/ y color/ están obsoletos para las apps modernas. Para obtener más información, consulta Animaciones en Compose y Anatomía de un tema en Compose.

Cómo ofrecer recursos alternativos

Casi todas las apps proporcionan recursos alternativos para admitir configuraciones de dispositivos específicas. Por ejemplo, debes incluir recursos de elementos de diseño alternativos para diferentes densidades de pantallas y recursos de cadenas alternativos para diferentes idiomas. En el tiempo de ejecución, Android detecta la configuración del dispositivo actual y carga los recursos adecuados para tu app.

Si quieres definir alternativas de configuraciones específicas para un conjunto de recursos, haz lo siguiente:

1. Crea en res/ un directorio nuevo cuyo nombre tenga el formato <resources_name>-<qualifier>.
   • <resources_name> es el nombre del directorio de los recursos predeterminados correspondientes (definidos en la tabla 1).
   • <qualifier> es un nombre que especifica una configuración individual para la cual se deben usar estos recursos (que se definen en la tabla 2).

   Puedes agregar más de un <qualifier>. Separa cada uno con un guion.

   Advertencia: Cuando agregues varios calificadores, debes disponerlos en el mismo orden en el que se enumeran en la Tabla 2. Si los calificadores no están ordenados correctamente, los recursos se ignoran.

2. Guarda los recursos alternativos correspondientes en este nuevo directorio. Los archivos de recursos deben llevar exactamente el mismo nombre que los archivos de recursos predeterminados.

Por ejemplo, estos son algunos recursos predeterminados y alternativos:

res/
    drawable/
        icon.png
        background.png
    drawable-hdpi/
        icon.png
        background.png

El calificador hdpi indica que los recursos de ese directorio son para dispositivos con pantalla de alta densidad. Las imágenes de estos directorios de elementos de diseño están dimensionadas para densidades de pantalla específicas, pero los nombres de archivo son exactamente iguales. De esta manera, el ID de recurso que usas para hacer referencia a la imagen icon.png o background.png es siempre el mismo. Android selecciona la versión de cada recurso que mejor se ajusta al dispositivo actual comparando la información de configuración del dispositivo con los calificadores del nombre del directorio de recursos.

Advertencia: Cuando definas un recurso alternativo, asegúrate de definirlo también en una configuración predeterminada. De lo contrario, tu app podría encontrar excepciones en el tiempo de ejecución cuando el dispositivo cambie una configuración. Por ejemplo, si agregas una cadena solo a values-en y no a values, es posible que se genere una excepción Resource Not Found en tu app cuando el usuario cambie el idioma predeterminado del sistema.

En la tabla 2, se enumeran los calificadores de configuración en orden de precedencia. Puedes agregar varios calificadores a un nombre de directorio separando cada calificador con un guion. Si utilizas varios calificadores para un directorio de recursos, debes agregarlos al nombre del directorio en el orden en el que se enumeran en la tabla.

Tabla 2: Nombres de calificadores de configuración.

Nota: No todas las versiones de Android admiten todos los calificadores. Cuando se utiliza un nuevo calificador, se agrega de forma implícita el calificador de la versión de la plataforma, de modo que los dispositivos anteriores lo ignoren. Para evitar problemas, siempre incluye un conjunto de recursos predeterminados (un conjunto de recursos sin calificadores). Para obtener más información, consulta la sección Provisión de la mejor compatibilidad de dispositivos con recursos.

En las apps de Compose, no se necesitan los calificadores de configuración relacionados con el diseño y las dimensiones. Si bien aún existen, se excluyen de la Tabla 2. Estos calificadores incluyen: dirección del diseño, ancho más pequeño, ancho disponible, altura disponible, tamaño de pantalla, relación de aspecto de la pantalla, pantalla redonda y orientación de la pantalla. Para ver la tabla completa de calificadores de configuración en orden de precedencia, consulta Información general sobre los recursos de las aplicaciones (vistas).

Reglas de nombres de calificadores

A continuación se incluyen algunas reglas acerca del uso de los nombres de calificadores de configuración:

• Puedes especificar varios calificadores, separados por guiones, para un solo conjunto de recursos. Por ejemplo, drawable-en-rUS-night se aplica a dispositivos en inglés (Estados Unidos) en modo nocturno.
• Los calificadores deben estar en el orden enumerado en la tabla 2.
  • Incorrecto: drawable-hdpi-night/
  • Correcto: drawable-night-hdpi/
• No se pueden anidar los directorios de recursos alternativos. Por ejemplo, no puedes tener res/drawable/drawable-en/.
• Los valores no distinguen mayúsculas de minúsculas. Los compiladores de recursos convierten los nombres de directorios a minúsculas antes del procesamiento para evitar problemas en los sistemas de archivos que no distinguen mayúsculas de minúsculas. Cualquier uso de mayúsculas en los nombres es solo para facilitar la lectura.
• Se admite un solo valor para cada tipo de calificador. Por ejemplo, si deseas usar los mismos archivos de elementos de diseño para España y Francia, no puedes tener un directorio llamado drawable-es-fr/. En cambio, necesitas dos directorios de recursos que contengan los archivos correspondientes, como drawable-es/ y drawable-fr/.

Una vez que guardas los recursos alternativos en directorios denominados con estos calificadores, Android aplica automáticamente los recursos en tu app de acuerdo con la configuración del dispositivo actual. Cada vez que se solicita un recurso, Android busca directorios de recursos alternativos que contengan el archivo de recursos solicitado y, luego, encuentra el recurso de coincidencia óptima.

Si no existen recursos alternativos que coincidan con una configuración de dispositivo determinada, Android utiliza los recursos predeterminados correspondientes (el conjunto de recursos para un tipo de recurso determinado que no incluye un calificador de configuración).

Cómo crear recursos de alias

Cuando tienes un recurso que deseas utilizar para más de una configuración de dispositivo (pero no deseas proporcionarlo como un recurso predeterminado), no necesitas colocar el mismo recurso en más de un directorio de recursos alternativos. En cambio, puedes crear un recurso alternativo que actúe como un alias para un recurso guardado en tu directorio de recursos predeterminados.

Elementos de diseño

Por ejemplo, imagina que tienes un ícono de la app, icon.png, y necesitas una versión única de ese ícono para diferentes configuraciones regionales. Sin embargo, dos configuraciones regionales, inglés (Canadá) y francés (Canadá), necesitan utilizar la misma versión. No es necesario que copies la misma imagen en el directorio de recursos para inglés (Canadá) y francés (Canadá). En cambio, puedes guardar la imagen que se usa para ambos y utilizar cualquier nombre que no sea icon.png, como icon_ca.png, y disponerla en el directorio res/drawable/ predeterminado. Luego, crea un archivo icon.xml en res/drawable-en-rCA/ y res/drawable-fr-rCA/ que haga referencia al recurso icon_ca.png con el elemento <bitmap>.

<?xml version="1.0" encoding="utf-8"?>
<bitmap xmlns:android="http://schemas.android.com/apk/res/android" android:src="@drawable/icon_ca" />

Esto te permite almacenar una sola versión del archivo PNG y dos archivos en formato XML pequeños que apuntan a dicho archivo PNG. Luego, puedes usar painterResource(R.drawable.icon) y el sistema elegirá el archivo adecuado una vez que detecte la configuración regional.

Strings y otros valores simples

Si deseas crear un alias para una cadena existente, utiliza el ID de recurso de la cadena deseada como el valor de la nueva cadena.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello</string>
    <string name="hi">@string/hello</string>
</resources>

El recurso R.string.hi ahora es un alias para R.string.hello.

Otros valores simples funcionan de la misma manera, como los colores:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="red">#f00</color>
    <color name="highlight">@color/red</color>
</resources>

Cómo acceder a los recursos de tu app

Una vez que proporciones un recurso en tu aplicación, podrás aplicarlo haciendo referencia a su ID de recurso. Todos los IDs de recursos se definen en la clase R de tu proyecto, que la herramienta aapt genera automáticamente.

Cuando se compila tu aplicación, aapt genera la clase R, que contiene los IDs de recurso de todos los recursos de tu directorio res/. Para cada tipo de recurso, hay una subclase R, como R.drawable para todos los recursos de elementos de diseño. Para cada recurso de ese tipo, hay un número entero estático, por ejemplo, R.drawable.icon. Ese valor entero es el ID del recurso que puedes usar para recuperar tu recurso.

Si bien en la clase R se especifican los IDs de recursos, no necesitas buscar en ella para hallar uno. Un ID de recurso siempre está compuesto por lo siguiente:

• El tipo de recurso: Cada recurso se agrupa en un "tipo", como string o drawable.
• El nombre del recurso, que es el nombre del archivo sin la extensión

Cómo acceder a los recursos en Compose

Jetpack Compose proporciona funciones integradas y compatibles con la composición para acceder a los recursos de forma segura.

• Cadenas:

  stringResource(id = R.string.hello)

• Drawables:

  painterResource(id = R.drawable.my_icon)

Accede a recursos en código sin IU

Si necesitas acceder a recursos fuera de tu jerarquía de IU, como en un ViewModel, un Repository o un Service del sistema, puedes resolverlos con Context.

// Retrieve a localized string resource
val greeting = context.getString(R.string.hello_world)

También puedes recuperar recursos individuales con métodos en Resources, del cual puedes obtener una instancia con getResources.

Sintaxis

Esta es la sintaxis que necesitas para hacer referencia a un recurso en código:

[<package_name>.]R.<resource_type>.<resource_name>

• <package_name> es el nombre del paquete en el que se ubica el recurso (no es necesario cuando haces referencia a recursos desde tu paquete).
• <resource_type> es la subclase R para el tipo de recurso.
• <resource_name> es el nombre de archivo del recurso sin la extensión ni el valor del atributo android:name en el elemento XML (para valores simples).

Para obtener más información sobre cada tipo de recurso y cómo hacer referencia a ellos, consulta Recursos en Compose.

Cómo acceder a los archivos originales

Si bien es poco común, podrías necesitar acceder a tus archivos y directorios originales. Si es así, no podrás guardar tus archivos en res/, ya que el único elemento que permite leer un recurso desde res/ es el ID de recurso. Como alternativa, puedes guardar tus recursos en el directorio assets/.

Los archivos guardados en el directorio assets/ no reciben un ID de recurso, por lo que no puedes hacer referencia a ellos a través de la clase R ni desde recursos XML. En cambio, puedes consultar archivos en el directorio assets/ como en un sistema de archivos normal y leer datos sin procesar usando AssetManager.

No obstante, si lo único que necesitas es la capacidad de leer datos sin procesar (como un archivo de audio o video), guarda el archivo en el directorio res/raw/ y lee un flujo de bytes usando openRawResource.

Cómo acceder a recursos de la plataforma

Android contiene una cantidad de recursos estándar, como estilos y temas del sistema. Para acceder a ellos, califica la referencia a tu recurso con la clase de paquete android. Por ejemplo: painterResource(android.R.drawable.ic_menu_info_details).

Cómo ofrecer la mejor compatibilidad de dispositivos con recursos

Para que tu app admita varias configuraciones de dispositivos, es muy importante que siempre proporciones recursos predeterminados para cada tipo de recurso utilizado por tu app.

Por ejemplo, si tu app admite varios idiomas, incluye siempre un directorio values/ (en el cual se guardan tus cadenas) sin un calificador de idioma y región. En cambio, si colocas todos tus archivos de cadenas en directorios que tienen un calificador de idioma y región, tu app fallará cuando se ejecute en un dispositivo configurado en un idioma que tus cadenas no admitan.

Siempre que proporciones recursos values/ predeterminados, tu app se ejecutará correctamente, incluso si el usuario no comprende el idioma que presenta. Es preferible esto a un bloqueo.

Proporcionar recursos predeterminados es importante no solo porque tu app podría ejecutarse en una configuración que no habías previsto, sino también porque las nuevas versiones de Android a veces agregan calificadores de configuración que las versiones anteriores no admiten. Si utilizas un nuevo calificador de recursos, pero mantienes la compatibilidad del código con versiones anteriores de Android, cuando una versión anterior de Android ejecute tu app, esta fallará si no proporcionas recursos predeterminados, ya que no podrá utilizar los recursos denominados con el nuevo calificador.

Por ejemplo, si tu minSdkVersion se establece en 4, y calificas todos tus recursos de elementos de diseño con el modo nocturno (night o notnight, que se agregaron en el nivel de API 8), un dispositivo con nivel de API 4 no podrá acceder a tus recursos de elementos de diseño y se bloqueará. En este caso, probablemente desees que notnight sean tus recursos predeterminados, por lo cual debes excluir ese calificador para que tus recursos de elementos de diseño estén en drawable/ o drawable-night/.

Por lo tanto, para ofrecer la mejor compatibilidad de dispositivo, siempre proporciona recursos predeterminados para los recursos que tu app necesita para funcionar correctamente. Luego, crea recursos alternativos para configuraciones de dispositivos específicos utilizando los calificadores de configuración.

Esta regla tiene una excepción: si la minSdkVersion de tu app es 4 o superior, no necesitas recursos de elementos de diseño predeterminados cuando proporcionas recursos de elementos de diseño alternativos con el calificador de densidad de pantalla. Incluso sin recursos de elementos de diseño predeterminados, Android puede encontrar la mejor coincidencia entre las densidades de pantalla alternativas y escalar el mapa de bits si es necesario. Sin embargo, para brindar la mejor experiencia en todos los tipos de dispositivos, debes proporcionar elementos de diseño alternativos para los tres tipos de densidad.

Cómo encuentra Android el recurso de coincidencia óptima

Cuando solicitas un recurso para el cual proporcionas alternativas, Android selecciona qué recurso alternativo utilizar en tiempo de ejecución, según la configuración del dispositivo actual. Para demostrar cómo Android selecciona un recurso alternativo, imagina que cada uno de los siguientes elementos de diseño contienen versiones diferentes de las mismas imágenes:

drawable/
drawable-en/
drawable-fr-rCA/
drawable-en-night/
drawable-en-notouch-12key/
drawable-night-ldpi/
drawable-night-notouch-12key/

Además, imagina que la configuración del dispositivo es la siguiente:

Configuración regional = en-GB
Modo nocturno = night
Densidad de píxeles de la pantalla = hdpi
Tipo de pantalla táctil = notouch
Método principal de entrada de texto = 12key

Cuando se compara la configuración del dispositivo con los recursos alternativos disponibles, Android selecciona elementos de diseño de drawable-en-night.

Para decidir qué recursos utilizar, el sistema se basa en la siguiente lógica:

Figura 2: Diagrama de flujo de la forma en la que Android encuentra el{}recurso de coincidencia óptima.

1. Eliminar los archivos de recursos que se contradicen con la configuración del dispositivo.

   El directorio drawable-fr-rCA/ se elimina porque se contradice con la configuración regional en-GB.

   drawable/
   drawable-en/
   drawable-fr-rCA/
   drawable-en-night/
   drawable-en-notouch-12key/
   drawable-night-ldpi/
   drawable-night-notouch-12key/
   

   Excepción: La densidad de píxeles de la pantalla es el único calificador que no se elimina debido a una contradicción. Aunque la densidad de la pantalla del dispositivo es hdpi, drawable-night-ldpi/ no se elimina, ya que todas las densidades de pantalla se consideran como una coincidencia en este punto. Para obtener más información, consulta Descripción general de la compatibilidad de pantallas.

2. Elegir el próximo calificador de mayor precedencia de la lista (Tabla 2). (Comienza con MCC).
3. ¿Alguno de los directorios de recursos incluye este calificador?
   • Si la respuesta es no, vuelve al paso 2 y examina el siguiente calificador. En el ejemplo, la respuesta es "no" hasta que se alcanza el calificador de idioma.
   • Si es así, continúa con el paso cuatro.
4. Eliminar directorios de recursos que no incluyen este calificador. En el ejemplo, el sistema elimina todos los directorios que no incluyen un calificador de idioma:

   drawable/
   drawable-en/
   drawable-en-night/
   drawable-en-notouch-12key/
   drawable-night-ldpi/
   drawable-night-notouch-12key/
   

   Excepción: Si el calificador en cuestión es la densidad de píxeles de la pantalla, Android selecciona la opción que más coincide con la densidad de la pantalla del dispositivo. En general, Android prefiere reducir una imagen original más grande que ampliar una imagen original más pequeña. Para obtener más información, consulta la descripción general de la compatibilidad de pantallas.

5. Repite los pasos dos, tres y cuatro hasta que quede un solo directorio. En este ejemplo, el modo nocturno es el próximo calificador para el cual existen coincidencias. Por lo tanto, se eliminan los recursos que no especifican el modo nocturno:

   drawable-en/
   drawable-en-night/
   drawable-en-notouch-12key/
   

   El directorio que queda es drawable-en-night.

Si bien este procedimiento se ejecuta para cada recurso solicitado, el sistema optimiza aún más algunos aspectos. Un ejemplo de esta optimización es que, una vez que se conoce la configuración del dispositivo, es posible que el sistema elimine los recursos alternativos que nunca coinciden. Por ejemplo, si el idioma de configuración es inglés, los directorios de recursos que tienen un calificador de idioma establecido en otro idioma que no sea inglés nunca se incluyen en el conjunto de recursos comprobados (sin embargo, un directorio de recursos sin el calificador de idioma sí se incluye).

Cuando se seleccionan recursos según los calificadores del tamaño de la pantalla, el sistema utiliza los recursos diseñados para una pantalla más pequeña que la pantalla actual si no existen recursos que coincidan mejor (por ejemplo, una pantalla de tamaño grande utiliza recursos de una pantalla de tamaño normal si es necesario).

Sin embargo, si los únicos recursos disponibles presentan un tamaño superior al de la pantalla actual, el sistema no los usa y tu app falla si ningún otro recurso coincide con la configuración del dispositivo (por ejemplo, si todos los recursos de diseño están etiquetados con el calificador xlarge, pero el dispositivo tiene una pantalla de tamaño normal).

Nota: La precedencia del calificador (en la tabla 2) es más importante que la cantidad de calificadores que coinciden exactamente con el dispositivo. En el ejemplo anterior, en el paso cuatro, la última opción de la lista incluye tres calificadores que coinciden exactamente con el dispositivo (modo nocturno, tipo de pantalla táctil y método de entrada), mientras que drawable-en solo tiene un parámetro que coincide (idioma). Sin embargo, el idioma tiene mayor precedencia que estos otros calificadores; por lo tanto, drawable-night-notouch-12key se elimina.

Recursos adicionales

Para obtener más información sobre los recursos de la app, consulta los siguientes recursos adicionales:

Documentación

• Recursos en Compose

Mira contenido

• Descripción general de los recursos de la app (vistas)