Visão geral dos recursos de aplicativo

Os recursos são os arquivos complementares e o conteúdo estático usados pelo seu código, como bitmaps, strings da interface do usuário, instruções de animação, entre outros.

Sempre exteriorize os recursos do app, como imagens e strings do código, para que a manutenção deles possa ser feita de forma independente. Além disso, forneça recursos alternativos para configurações específicas do dispositivo agrupando-os em diretórios de recursos especialmente nomeados. Durante a execução, o Android usa o recurso adequado com base na configuração atual. Por exemplo, forneça strings diferentes dependendo da configuração de idioma.

Ao exteriorizar os recursos do app, eles podem ser acessados com IDs de recurso gerados na classe R do projeto. Este documento mostra como agrupar os recursos no seu projeto Android. Ele também mostra como fornecer recursos alternativos para configurações específicas do dispositivo e, em seguida, acessá-los no código do app ou de outros arquivos XML.

Tipos de recurso de grupo

Coloque cada tipo de recurso em um subdiretório específico do diretório res/ do projeto. Por exemplo, abaixo mostramos a hierarquia de arquivos para um projeto simples:

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

O diretório res/ contém todos os recursos nos subdiretórios: um recurso de imagem, um diretório mipmap/ para ícones na tela de início e um arquivo de recurso de string. Os nomes dos diretórios de recursos são importantes e estão descritos na Tabela 1.

Observação: para mais informações sobre o uso de pastas de mipmap, consulte Colocar ícones de apps em diretórios de mipmap.

Tabela 1. Diretórios de recursos que têm suporte dentro do diretório res/ do projeto.

Cuidado: nunca salve arquivos de recurso diretamente no diretório res/. Isso causa um erro do compilador.

Os recursos salvos nos subdiretórios definidos na tabela 1 são os recursos padrão. Ou seja, esses recursos definem o design e o conteúdo padrão do seu app. No entanto, diferentes tipos de dispositivos Android podem precisar de diferentes tipos de recursos.

Por exemplo, você pode fornecer diferentes recursos de string que traduzem o texto na interface do usuário com base na configuração de idioma do dispositivo.

Observação:no Compose, as UIs, animações e cores controladas por estado são declaradas em Kotlin. Portanto, os diretórios layout/, menu/, anim/, animator/ e color/ estão obsoletos para apps modernos. Para mais informações, consulte Animações no Compose e Anatomia de um tema no Compose.

Fornecer recursos alternativos

A maioria dos apps oferece recursos alternativos para oferecer suporte a configurações específicas do dispositivo. Por exemplo, inclua recursos drawable alternativos para densidades de tela diferentes e recursos alternativos de string para idiomas diferentes. Durante a execução, o Android detecta a configuração atual do dispositivo e carrega os recursos adequados para o app.

Para especificar alternativas específicas de configuração para um conjunto de recursos, faça o seguinte:

1. Crie um novo diretório no res/ nomeado na forma de <resources_name>-<qualifier>.
   • <resources_name> é o nome do diretório dos recursos padrão correspondentes (definido na Tabela 1).
   • <qualifier> é um nome que especifica uma configuração individual a que esses recursos se destinam (definido na Tabela 2).

   É possível anexar mais de um <qualifier>. Separe cada um com um travessão.

   Cuidado:ao anexar vários qualificadores, coloque-os na mesma ordem em que foram listados na Tabela 2. Se os qualificadores estiverem ordenados de forma incorreta, os recursos serão ignorados.

2. Salve os respectivos recursos alternativos neste novo diretório. Os arquivos de recurso precisam ter exatamente os mesmos nomes dos arquivos de recurso padrão.

No exemplo abaixo há alguns recursos alternativos e outros padrão:

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

O qualificador hdpi indica que os recursos neste diretório são destinados a dispositivos com telas de alta densidade. As imagens nesses diretórios drawable são dimensionadas para densidades de tela específicas, mas os nomes dos arquivos são exatamente os mesmos. Dessa forma, o ID do recurso usado para fazer referência à imagem icon.png ou background.png é sempre o mesmo. O Android seleciona a versão de cada recurso que melhor corresponde ao dispositivo atual comparando as informações de configuração do dispositivo com os qualificadores no nome do diretório de recursos.

Cuidado: ao definir um recurso alternativo, verifique se você também definiu o recurso em uma configuração padrão. Caso contrário, o app pode encontrar exceções de execução quando o dispositivo mudar uma configuração. Por exemplo, se você adicionar uma string apenas para values-en, e não para values, o app pode encontrar uma exceção Resource Not Found quando o usuário mudar o idioma padrão do sistema.

A tabela 2 lista os qualificadores de configuração em ordem de precedência. É possível adicionar vários qualificadores a um nome de diretório separando cada qualificador com um traço. Se você usar vários qualificadores para um diretório de recursos, será necessário adicioná-los ao nome do diretório na ordem em que estão listados na tabela.

Tabela 2. Nomes de qualificadores de configuração.

Observação: nem todas as versões do Android oferecem suporte a todos os qualificadores. O uso de um novo qualificador adiciona implicitamente o qualificador de versão de plataforma para que dispositivos mais antigos possam ignorá-lo. Para evitar problemas, sempre inclua um conjunto de recursos padrão (um conjunto de recursos sem qualificadores). Para mais informações, consulte a seção sobre como fornecer a melhor compatibilidade de dispositivo com recursos.

Em apps do Compose, não são necessários qualificadores de configuração relacionados a layout e dimensão. Enquanto eles ainda existem, são excluídos da Tabela 2. Esses qualificadores incluem: direção do layout, menor largura, largura disponível, altura disponível, tamanho da tela, proporção da tela, tela redonda e orientação da tela. Para conferir a tabela completa de qualificadores de configuração por ordem de precedência, consulte Visão geral dos recursos de app (visualizações).

Regras de nome do qualificador

Confira abaixo algumas regras sobre como usar nomes de qualificador de configuração:

• É possível especificar vários qualificadores para um único conjunto de recursos, separados por travessões. Por exemplo, drawable-en-rUS-night é aplicado aos dispositivos em inglês dos EUA no modo noturno.
• Os qualificadores precisam estar na ordem listada na Tabela 2.
  • Errado: drawable-hdpi-night/
  • Correto: drawable-night-hdpi/
• Diretórios de recursos alternativos não podem ser aninhados. Por exemplo, não é possível usar res/drawable/drawable-en/.
• Os valores não diferenciam letras maiúsculas e minúsculas. O compilador de recursos converte nomes de diretório para letras minúsculas antes de fazer o processamento para evitar problemas nos sistemas de arquivo que não diferenciam maiúsculas de minúsculas. Qualquer letra maiúscula nos nomes é só para o benefício da leitura.
• Há suporte a apenas um valor para cada tipo de qualificador. Por exemplo, se você quiser usar os mesmos arquivos drawable para a Espanha e a França, não será possível ter um diretório chamado drawable-es-fr/. Em vez disso, você vai precisar de dois diretórios de recursos, como drawable-es/ e drawable-fr/, que contêm os arquivos adequados.

Após salvar os recursos alternativos nos diretórios nomeados com esses qualificadores, o Android vai aplicar automaticamente os recursos no app com base na configuração atual do dispositivo. Sempre que um recurso é solicitado, o Android verifica diretórios de recursos alternativos que contenham o arquivo de recurso solicitado e, em seguida, encontra o melhor recurso correspondente.

Se não houver recursos alternativos que correspondam a uma configuração de dispositivo específica, o Android vai usar os recursos padrão correspondentes (o conjunto de recursos para um tipo de recurso específico que não inclua um qualificador de configuração).

Criar recursos de alias

Quando você tem um recurso que quer usar para mais de uma configuração de dispositivo, mas não quer que ele seja um recurso padrão, não precisa usar o mesmo recurso em mais de um diretório de recursos alternativos. Em vez disso, é possível criar um recurso alternativo que atue como um alias para um recurso salvo no diretório de recursos padrão.

Drawables

Por exemplo: você tem um ícone do app, icon.png, e precisa da versão exclusiva para diferentes localidades. No entanto, duas localidades, inglês canadense e francês canadense, precisam usar a mesma versão. Não é necessário copiar a mesma imagem para o diretório de recursos do inglês canadense e do francês canadense. Em vez disso, você pode salvar a imagem usada para ambos usando qualquer nome diferente de icon.png, como icon_ca.png e colocá-la no diretório res/drawable/ padrão. Em seguida, crie um arquivo icon.xml em res/drawable-en-rCA/ e res/drawable-fr-rCA/ que referencie o recurso icon_ca.png usando o elemento <bitmap>.

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

Isso permite que você armazene somente uma versão do arquivo PNG e dois arquivos XML pequenos que apontam para ele. Em seguida, use painterResource(R.drawable.icon), e o sistema vai escolher o arquivo apropriado quando detectar a localidade.

Strings e outros valores simples

Para criar um alias para uma string já existente, use o ID de recurso da string desejada como o valor da nova string:

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

O recurso R.string.hi é agora um alias de R.string.hello.

Outros valores simples funcionam da mesma maneira, como cores:

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

Acessar os recursos do app

Depois que um recurso é fornecido no app, ele pode ser aplicado referenciando o ID do recurso. Todos os IDs de recursos são definidos na classe R do projeto que a ferramenta aapt gera automaticamente.

Quando o aplicativo é compilado, o aapt gera a classe R, que contém IDs de recursos para todos os recursos no diretório res/. Para cada tipo de recurso, há uma subclasse R, como R.drawable para todos os recursos drawable. E para cada recurso desse tipo, há um número inteiro estático, por exemplo, R.drawable.icon. Esse número inteiro é o ID do recurso que pode ser usado para extraí-lo.

Embora a classe R seja o local onde os IDs de recursos são especificados, não é necessário verificá-la para localizar um ID de recurso. Um ID de recurso é sempre composto pelo seguinte:

• O tipo de recurso: cada recurso é agrupado em um "tipo", como string ou drawable.
• O nome do recurso, que é o nome do arquivo sem a extensão.

Acessar recursos no Compose

O Jetpack Compose oferece funções integradas e compatíveis com elementos combináveis para acessar recursos com segurança.

• Strings:

  stringResource(id = R.string.hello)

• Drawables:

  painterResource(id = R.drawable.my_icon)

Acessar recursos em código sem interface

Se você precisar acessar recursos fora da hierarquia da interface, como em um ViewModel, um Repository ou um Service do sistema, poderá resolvê-los usando o Context.

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

Você pode extrair recursos individuais usando métodos em Resources. É possível acessar uma instância desses métodos com getResources.

Sintaxe

Esta é a sintaxe para referenciar um recurso no código:

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

• <package_name> é o nome do pacote em que o recurso está localizado (não é obrigatório ao referenciar recursos do seu pacote).
• <resource_type> é a subclasse R do tipo de recurso.
• <resource_name> é o nome do arquivo do recurso sem a extensão ou o valor do atributo android:name no elemento XML, para valores simples.

Para mais informações sobre cada tipo de recurso e como referenciá-los, consulte Recursos no Compose.

Acessar arquivos originais

Apesar de ser incomum, pode ser necessário acessar os arquivos e os diretórios originais. Nesse caso, salvar os arquivos em res/ não vai funcionar, porque a única forma de ler um recurso de res/ é com o ID do recurso. Em vez disso, você pode salvar os recursos no diretório assets/.

Arquivos salvos no diretório assets/ não recebem nenhum ID de recurso, portanto, não é possível fazer referência a eles com a classe R nem com recursos XML. Em vez disso, é possível consultar arquivos no diretório assets/ como um sistema de arquivos normal e ler dados brutos usando o AssetManager.

Se você só precisar da capacidade de ler dados brutos (como um arquivo de vídeo ou áudio), salve o arquivo no diretório res/raw/ e leia um stream de bytes usando openRawResource.

Acessar recursos da plataforma

O Android contém vários recursos padrão, como estilos e temas do sistema. Para acessar esses recursos, qualifique a referência com a classe de pacote android. Por exemplo: painterResource(android.R.drawable.ic_menu_info_details)

Fornecer a melhor compatibilidade de dispositivo com recursos

Para que o app ofereça suporte a várias configurações de dispositivo, é muito importante que você sempre forneça recursos padrão para cada tipo de recurso que o app usar.

Por exemplo: se o app oferecer suporte a vários idiomas, sempre inclua um diretório values/ (em que as strings sejam salvas) sem qualificadores de região e idioma. Se você colocar todos os arquivos de string em diretórios que têm qualificadores de região e idioma, o app vai apresentar erros ao ser executado em um dispositivo configurado para um idioma que as strings não reconheçam.

Se você fornecer recursos values/ padrão, o app será executado corretamente, mesmo que o usuário não entenda o idioma apresentado. Isso é melhor do que uma falha.

Fornecer recursos padrão é importante não só porque o app pode ser executado em uma configuração que você não tenha previsto, mas também porque as novas versões do Android, às vezes, adicionam qualificadores de configuração que não têm suporte em versões mais antigas. Se você usar um novo qualificador de recurso, mas mantiver a compatibilidade do código com versões mais antigas do Android, quando uma versão mais antiga do Android executar seu app, ele falhará se você não fornecer recursos padrão, porque ele não pode usar os recursos nomeados com o novo qualificador.

Por exemplo, se a minSdkVersion estiver definida como 4 e você qualificar todos os recursos drawable usando o modo noturno (night ou notnight, que foram adicionados no nível 8 da API), o dispositivo com o nível 4 não poderá acessar os recursos drawable e irá falhar. Nesse caso, você provavelmente vai querer que notnight seja seu recurso padrão, então exclua esse qualificador e coloque os recursos drawable em drawable/ ou drawable-night/.

Resumindo, para oferecer a melhor compatibilidade entre dispositivos, sempre forneça os recursos padrão para que o app funcione como esperado. Em seguida, crie recursos alternativos para configurações específicas de dispositivo usando os qualificadores de configuração.

Há uma exceção a essa regra: se a minSdkVersion do seu app é 4 ou mais recente, você não precisa de recursos drawable padrão ao fornecer recursos drawable alternativos com o qualificador de densidade de tela. Mesmo sem os recursos drawable padrão, o Android pode encontrar a melhor correspondência entre as densidades de tela alternativas e dimensionar os bitmaps conforme necessário. No entanto, para ter a melhor experiência em todos os tipos de dispositivo, forneça drawables alternativos para os três tipos de densidade.

Como o Android encontra o melhor recurso correspondente

Ao solicitar um recurso a que você fornece alternativas, o Android seleciona quais recursos usar durante a execução, dependendo da configuração atual do dispositivo. Para demonstrar como o Android seleciona um recurso alternativo, presuma que os diretórios de drawable abaixo contenham versões diferentes das mesmas imagens:

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

E presuma que a configuração do dispositivo seja esta:

Localidade = en-GB
Modo noturno = night
Densidade de pixels da tela = hdpi
Tipo de tela touchscreen = notouch
Método de entrada de texto principal = 12key

Ao comparar a configuração do dispositivo com os recursos alternativos disponíveis, o Android seleciona drawables de drawable-en-night.

O sistema chega à conclusão de que recursos usar com esta lógica:

Figura 2. Fluxograma de como o Android encontra o melhor recurso correspondente.

1. Elimine os arquivos de recurso que contradizem a configuração do dispositivo.

   O diretório drawable-fr-rCA/ é eliminado, porque contradiz a localidade en-GB.

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

   Exceção: a densidade de pixel da tela é a que o qualificador não eliminou devido a uma contradição. Apesar da densidade da tela do dispositivo ser hdpi, drawable-night-ldpi/ não é eliminado, porque todas as densidades de tela são consideradas uma correspondência neste ponto. Para mais informações, consulte a Visão geral da compatibilidade da tela.

2. Encontre o próximo qualificador de maior precedência na lista (Tabela 2). Comece com o MCC.
3. Algum dos diretórios de recurso incluem este qualificador?
   • Em caso negativo, volte à Etapa 2 e confira o próximo qualificador. No exemplo, a resposta é "não" até chegar no qualificador de idioma.
   • Em caso afirmativo, prossiga para a etapa quatro.
4. Elimine os diretórios de recurso que não incluem esse qualificador. Neste exemplo, o sistema elimina todos os diretórios que não incluem um qualificador de idioma:

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

   Exceção: se o qualificador em questão for a densidade de pixels da tela, o Android selecionará a opção mais próxima da densidade de tela do dispositivo. Geralmente, o Android prefere reduzir a escala vertical de uma imagem original maior em vez de usar uma menor. Para mais informações, consulte a Visão geral da compatibilidade da tela.

5. Repita as etapas dois, três e quatro até que apenas um diretório permaneça. Neste exemplo, o modo noturno é o próximo qualificador em que há correspondências. Os recursos que não especificarem o modo noturno serão eliminados:

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

   O diretório que sobra é drawable-en-night.

Embora esse procedimento seja executado para cada recurso solicitado, o sistema otimiza alguns aspectos dele. Esse tipo de otimização, quando a configuração do dispositivo é conhecida, pode eliminar os recursos alternativos que nunca têm uma correspondência. Por exemplo, se o idioma da configuração for inglês, nenhum diretório de recurso que tiver um qualificador de idioma definido para outro idioma que não seja inglês vai ser incluído no conjunto de recursos verificados (apesar de um diretório de recursos sem o qualificador de idioma ainda ser incluído).

Ao selecionar os recursos com base nos qualificadores de tamanho da tela, o sistema vai usar os recursos criados para uma tela menor do que a atual, caso não tenha recursos com melhor correspondência. Por exemplo, uma tela de tamanho grande vai usar os recursos de tela de tamanho normal, se necessário.

No entanto, se os únicos recursos disponíveis forem maiores que a tela atual, eles não serão usados pelo sistema, e o app vai falhar se nenhum outro recurso corresponder à configuração do dispositivo. Isso acontece, por exemplo, se todos os recursos de layout estiverem com a tag do qualificador xlarge, mas o dispositivo tiver uma tela de tamanho normal.

Observação:a precedência do qualificador (na Tabela 2) é mais importante do que o número de qualificadores que correspondem exatamente ao dispositivo. No exemplo anterior, na quarta etapa, a última opção na lista inclui três qualificadores que correspondem exatamente ao dispositivo (modo noturno, tipo de tela touchscreen e método de entrada), enquanto drawable-en tem apenas um parâmetro correspondente (idioma). No entanto, o idioma tem uma precedência maior que esses outros qualificadores, então drawable-night-notouch-12key é eliminado.

Outros recursos

Para saber mais sobre recursos de app, consulte os seguintes recursos extras:

Documentação

• Recursos no Compose

Visualiza conteúdo

• Visão geral dos recursos do app (visualizações)