Visão geral dos recursos de app (Views)

Conceitos e implementação do Jetpack Compose

Recursos são os arquivos complementares e o conteúdo estático usado pelo seu código, como bitmaps, definições de layout, strings da interface do usuário, instruções de animação, entre outras coisas.

Sempre exteriorize os recursos do app, como imagens e strings do código, para que eles possam ser mantidos 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. No tempo de execução, o Android usa o recurso adequado com base na configuração atual. Por exemplo, forneça um outro layout de IU de acordo com o tamanho da tela ou 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 do Android. Ele também mostra como fornecer recursos alternativos para configurações específicas do dispositivo e acessá-los no código do app ou em 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.java
    res/
        drawable/
            graphic.png
        layout/
            main.xml
            info.xml
        mipmap/
            icon.png
        values/
            strings.xml

O diretório res/ contém todos os recursos nos subdiretórios: um recurso de imagem, dois recursos de layout, 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.

Tabela 1. Diretórios de recursos compatíveis dentro do diretório res/ do projeto.

Diretório

Tipo de recurso

animator/

Arquivos XML que definem as animações de propriedade.

anim/

Arquivos XML que definem as animações intermediárias. As animações de propriedade também podem ser salvas neste diretório, mas o diretório animator/ é o recomendado para que elas diferenciem os dois tipos.

color/

Arquivos XML que definem uma lista de estado de cores. Para mais informações, consulte Recurso de lista de estados de cores.

drawable/

Arquivos bitmap (PNG, .9.png, JPG ou GIF) ou arquivos XML que são compilados nestes subtipos de recursos drawable:

  • Arquivos Bitmap
  • Nine-patches (bitmaps redimensionáveis)
  • Listas de estado
  • Formas
  • Drawables de animação
  • Outros drawables

Para mais informações, consulte Recursos drawables.

mipmap/

São arquivos drawable para diferentes densidades do ícone na tela de início. Para saber mais sobre como gerenciar ícones de tela de início com pastas mipmap/, consulte Colocar ícones de apps em diretórios de mipmap.

layout/

Arquivos XML que definem um layout de interface do usuário. Para mais informações, consulte Recurso de layout.

menu/

São arquivos XML que definem os menus do app, como o menu "opções", o menu de contexto ou o submenu. Para mais informações, consulte Recurso de menu.

raw/

São arquivos arbitrários para salvar na forma bruta. Para abrir esses recursos com um InputStream bruto, chame Resources.openRawResource com o ID do recurso, que é R.raw.filename.

No entanto, se você precisar de acesso aos nomes de arquivo e à hierarquia de arquivos originais, considere salvar recursos no diretório assets/ em vez de res/raw/. Os arquivos em assets/ não recebem um ID de recurso, então só podem ser lidos usando AssetManager.

values/

São arquivos XML que contêm valores simples, como strings, números inteiros e cores.

Enquanto os arquivos de recurso XML em outros subdiretórios res/ definem um único recurso com base no nome do arquivo XML, os arquivos no diretório values/ descrevem vários recursos. Para cada arquivo neste diretório, cada filho do elemento define um único recurso. Por exemplo, um elemento cria um recurso R.string, e um elemento cria um recurso R.color.

Como cada recurso é definido com seu próprio elemento XML, é possível nomear o arquivo da forma que quiser e colocar tipos de recurso variados em um arquivo. No entanto, para fins de esclarecimento, coloque tipos de recursos únicos em arquivos diferentes. Por exemplo, confira algumas convenções de nome de arquivo para recursos que podem ser criados neste diretório:

Para mais informações, consulte Recursos de string, Recurso de estilo e Mais tipos de recursos.

xml/

Arquivos XML arbitrários que podem ser lidos durante a execução chamando Resources.getXML(). Vários arquivos de configuração XML precisam ser salvos aqui.

font/

São arquivos de fonte com extensões como TTF, OTF ou TTC ou arquivos XML que incluem um elemento . Para mais informações sobre fontes como recursos, consulte Adicionar uma fonte como um recurso XML.

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 recursos de layout diferentes para dispositivos que têm telas maiores que o normal para aproveitar o espaço extra. Você também pode fornecer diferentes recursos de string que traduzem o texto na interface do usuário com base na configuração de idioma do dispositivo. Para fornecer esses diferentes recursos para configurações de dispositivo diferentes, você precisa fornecer recursos alternativos, além dos recursos padrão.

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 diferentes densidades de tela e recursos alternativos de string para diferentes idiomas. Durante o tempo de execução, o Android detecta a configuração atual do dispositivo e carrega os recursos adequados para o app.

Figura 1. Dois dispositivos que usam recursos de layout diferentes com base no tamanho da tela.

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

  1. Crie um novo diretório em res/ nomeado na forma <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 para que esses recursos serão usados (definido na tabela 2).

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

  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.

A tabela 2 lista os qualificadores de configuração válidos 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, adicione-os ao nome do diretório na ordem em que estão listados na tabela.

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

Configuração

Valores do qualificador

Descrição

MCC e MNC

Exemplos:

mcc310

mcc310-mnc004

mcc208-mnc00

O código de país para dispositivos móveis (MCC), opcionalmente seguido do código de rede móvel (MNC) do chip no dispositivo. Por exemplo, mcc310 é o código dos EUA em qualquer operadora, mcc310-mnc004 é dos EUA na Verizon e mcc208-mnc00 é da França na Orange.

Se o dispositivo usar uma conexão de rádio (ou seja, se for um aparelho GSM), os valores MCC e MNC serão os do chip.

Você também pode usar somente o MCC para, por exemplo, incluir recursos legais específicos do país no seu app. Se você precisar especificar com base apenas no idioma, use o qualificador de idioma, script (opcional) e região (opcional). Se você usar o qualificador MCC e MNC, tome cuidado e teste o funcionamento.

Consulte também os campos de configuração mcc e mnc, que indicam o código de país para dispositivos móveis atual e o código de rede móvel, respectivamente.

Idioma, script (opcional) e região (opcional)

Exemplos:

en

fr

en-rUS

fr-rFR

fr-rCA

b+en

b+en+US

b+es+419

b+zh+Hant

b+sr+Latn+RS

O idioma é definido por um código de idioma ISO 639-2{:.external} de duas letras, opcionalmente seguido por um código da região ISO 3166-1-alpha-2{:.external} de duas letras, que começa com um r minúsculo.

Os códigos não diferenciam maiúsculas de minúsculas. O prefixo r é usado para distinguir a parte da região. Não é possível especificar uma região sozinha.

O Android 7.0 (nível 24 da API) lançou o suporte a tags de idioma BCP 47{:.external}, que podem ser usadas para qualificar recursos específicos de idioma e região. As tags de idiomas são compostas pela sequência de uma ou mais subtags, sendo que cada uma delas refina ou limita o intervalo do idioma identificado pela tag geral. Para mais informações sobre tags de idioma, consulte Tags para identificar idiomas{:.external} (em inglês).

Para usar uma tag de idioma BCP 47, concatene b+ e um código de idioma de duas letras ISO 639-2{:.external}, opcionalmente seguido de subtags separadas por +.

A tag de idioma pode mudar durante a vida útil do seu app, caso os usuários mudem o idioma nas configurações do sistema. Para saber mais sobre como isso pode afetar seu app durante a execução, consulte Processar mudanças de configuração.

Para acessar um guia completo de localização do app para outros idiomas, consulte Localizar o app.

Consulte também o método getLocales, que fornece a lista definida de localidades. Essa lista inclui a localidade primária.
Gênero gramatical masculine
feminine
neuter

O gênero gramatical do usuário. Usado para idiomas com gênero gramatical.

Por exemplo, se você precisar fornecer recursos diferentes para usuários que falam francês, use diretórios como estes:

res/
  values-fr/
    strings.xml (strings padrão com gênero não especificado)
  values-fr-masculine/
    strings.xml (strings com gênero masculino)
  values-fr-feminine/
    strings.xml (strings com gênero feminino)
  values-fr-neuter/
    strings.xml (strings com gênero neutro)

Consulte: Flexão gramatical no Android.

Consulte também o método de configuração getGrammaticalGender(), que indica o gênero gramatical.

Adicionado no nível 34 da API.

Direção do layout

ldrtl

ldltr

É a direção do layout do app. ldrtl significa "direção do layout da direita para a esquerda" (na sigla em inglês). ldltr significa "direção do layout da esquerda para a direita" (na sigla em inglês) e é o valor implícito padrão.

Isso pode ser aplicado a qualquer recurso, como layouts, drawables ou valores.

Por exemplo, se você quiser fornecer um layout específico para o idioma árabe e um layout genérico para qualquer outro idioma "da direita para a esquerda", como persa ou hebraico, use diretórios como estes:

res/
layout/
main.xml (layout padrão)
layout-ar/
main.xml (layout específico para o árabe)
layout-ldrtl/
main.xml (qualquer idioma da direita para a esquerda, exceto o árabe, porque o qualificador de idioma "ar" tem uma precedência maior)

Observação: para ativar recursos de layout da direita para a esquerda no app, defina SupportsRtl como "true" e TargetSdkVersion como 17 ou mais recente.

Adicionado no nível 17 da API.

Menor largura

swdp

Exemplos:

sw320dp

sw600dp

sw720dp

etc.

É a menor dimensão da área da tela disponível para um app. Especificamente, a smallestWidth da janela do app é a menor altura e largura disponíveis da janela. Ela também pode ser interpretada como a "menor largura possível" da janela. Você pode usar esse qualificador para garantir que seu app tenha pelo menos dp de largura disponível para a interface.

Por exemplo, se o layout exigir que a menor dimensão da área da tela seja de pelo menos 600 dp, é possível usar esse qualificador para criar os recursos do layout em um diretório res/layout-sw600dp/. O sistema usa esses recursos somente quando a menor dimensão da tela disponível é de pelo menos 600 dp, independente do lado de 600 dp ser a altura ou a largura percebida pelo usuário. A menor largura pode mudar se a janela for redimensionada, mudando a largura/altura disponível, ou reposicionada, possivelmente mudando os encartes do sistema.

Usar a menor largura para determinar o tamanho geral da tela é útil, porque a largura é frequentemente o fator determinante para o design de um layout. Muitas vezes, uma interface rola verticalmente, mas tem restrições bastante rígidas no espaço mínimo de que precisa horizontalmente.

A largura disponível também é o fator principal para determinar se um layout de um painel será usado para smartphones ou um layout de vários painéis para tablets. Você provavelmente precisa se preocupar mais com a menor largura possível em cada dispositivo.

A menor largura de um dispositivo considera decorações de tela e a interface do sistema. Por exemplo, se o dispositivo tiver elementos de interface persistentes na tela que ocupam espaço ao longo do eixo da menor largura, o sistema vai declarar que a menor largura é menor do que o tamanho real da tela, porque esses são pixels de tela não disponíveis para a interface.

Alguns dos valores que você pode usar para tamanhos de tela comuns:

  • 320, para dispositivos com configurações de tela como:
    • 240 x 320 ldpi (celular QVGA)
    • 320 x 480 mdpi (celular)
    • 480 x 800 hdpi (celular de alta densidade)
  • 480, para telas como 480 x 800 mdpi (tablet/celular)
  • 600, para telas como 600 x 1024 mdpi (tablet de 7 polegadas)
  • 720, para telas como 720 x 1280 mdpi (tablet de 10 polegadas)

Quando o app fornece vários diretórios de recursos com valores diferentes para o qualificador smallestWidth, o sistema usa o valor mais próximo ao da smallestWidth do dispositivo, sem o exceder.

Adicionado no nível 13 da API.

Consulte também o atributo android:requiresSmallestWidthDp, que declara a smallestWidth mínima compatível com o app, e o campo de configuração smallestScreenWidthDp, que retém o valor de smallestWidth do dispositivo.

Para mais informações sobre como criar apps para telas diferentes usando esse qualificador, consulte Design responsivo/adaptável com visualizações.

Largura e altura disponíveis

wdp

hdp

Exemplos:

w720dp

w1024dp

h720dp

h1024dp

etc.

Especifica a largura ou altura mínima disponível da tela (em unidades dp definidas pelo valor ) em que o recurso é usado. Esses valores de configuração são comparados à largura e altura da tela atual conforme a orientação do dispositivo muda entre retrato e paisagem, o dispositivo dobra ou desdobra ou o sistema entra ou sai do modo de várias janelas. No modo de várias janelas, os valores refletem a largura e a altura da janela que contém o app, não a largura e altura da tela do dispositivo. Da mesma forma, para atividades incorporadas, os valores se referem à largura e altura das atividades individuais, não à largura e altura da tela. Para mais informações, consulte Incorporação de atividades.

A largura e a altura disponíveis geralmente são úteis para determinar o uso de um layout de vários painéis porque, mesmo em um tablet, geralmente não é recomendável usar o mesmo layout de vários painéis para a orientação retrato e paisagem. Você pode usar os valores disponíveis para especificar a largura e/ou altura mínimas necessárias para o layout, em vez de usar os qualificadores de tamanho e orientação da tela juntos.

Quando o app fornece vários diretórios de recursos com valores diferentes para essas configurações, o sistema usa o mais próximo da largura atual da tela do dispositivo (sem o exceder). O valor mais próximo é determinado adicionando as diferenças entre a largura real da tela e a largura especificada com a diferença entre a altura real da tela e a altura especificada, com alturas e larguras não especificadas com o valor 0.

Os valores excluem a área ocupada por encartes de janela. Portanto, se o dispositivo tiver elementos de interface persistentes nas bordas da tela, os valores de largura e altura serão menores do que as dimensões reais da tela, mesmo quando o app for mostrado de ponta a ponta usando Window.setDecorFitsSystemWindows ou WindowCompat.setDecorFitsSystemWindows.

Algumas decorações de tela vertical que não são fixas (como uma barra de status do smartphone que pode ser ocultada quando a tela cheia está ativada) não são consideradas aqui, nem as decorações de janela, como a barra de título ou de ações. Portanto, os apps precisam estar preparados para lidar com um espaço um pouco menor do que o especificado.

Observação: o sistema escolhe o recurso que corresponde à largura e à altura. Portanto, é preferível ter um recurso que especifique ambos em vez de um que especifique apenas um ou outro. Por exemplo, se a tela tiver 720 dp de largura por 1.280 dp de altura e um recurso for qualificado com w720 dp, e outro for qualificado como w700dp-h1200 dp, o último será escolhido mesmo que o primeiro seja uma correspondência exata para o que ele especifica.

Adicionado no nível 13 da API.

Consulte também os campos de configuração screenWidthDp e screenHeightDp, que contêm a largura e a altura atuais da tela.

Para mais informações sobre como criar apps para telas diferentes usando esse qualificador, consulte Design responsivo/adaptável com visualizações.

Tamanho da tela

small

normal

large

xlarge
  • small: telas de tamanho semelhante a uma tela de baixa densidade QVGA. O tamanho mínimo do layout para uma tela pequena é de aproximadamente 320 x 426 unidades dp. Exemplos são QVGA de baixa densidade e VGA de alta densidade.
  • normal: telas de tamanho semelhante a uma tela de média densidade HVGA. O tamanho mínimo do layout para uma tela normal é de aproximadamente 320 x 470 unidades dp. Exemplos dessas telas são: WQVGA de baixa densidade, HVGA de média densidade e WVGA de alta densidade.
  • large: telas de tamanho semelhante a uma tela VGA de média densidade. O tamanho mínimo do layout para uma tela grande é de aproximadamente 480 x 640 unidades dp. Exemplos são as telas de densidade média VGA e WVGA.
  • xlarge: telas que são consideravelmente maiores do que a tela tradicional de média densidade HVGA. O tamanho mínimo do layout para uma tela muito grande é de aproximadamente 720 x 960 unidades dp. Na maioria dos casos, dispositivos com telas muito grandes são grandes demais para serem carregados em bolsos e, provavelmente, são dispositivos no estilo tablet. Adicionado no nível 9 da API.

Observação: o uso de um qualificador de tamanho não implica que os recursos sejam apenas para telas desse tamanho. Caso não forneça recursos alternativos com qualificadores que melhor correspondem à configuração atual do dispositivo, o sistema poderá usar quaisquer recursos que representem a melhor correspondência.

Atenção: se todos os seus recursos usarem um qualificador de tamanho maior que a tela atual, o sistema não os utilizará, e o app vai falhar durante o tempo de execução. Isso acontece, por exemplo, se todos os recursos de layout forem marcados com o qualificador xlarge, mas o dispositivo tiver uma tela de tamanho normal.

Adicionado no nível 4 da API.

Consulte também o campo de configuração screenLayout, que indica se a tela é pequena, normal ou grande.

Para mais informações, consulte Visão geral da compatibilidade de tela.

Aspecto da tela

long

notlong
  • long: telas grandes, como WQVGA, WVGA, FWVGA
  • notlong: telas que não são grandes, como QVGA, HVGA e VGA

Adicionado no nível 4 da API.

Isso se baseia puramente na relação de aspecto da tela (uma tela long é mais larga). Isso não tem relação com a orientação da tela.

Consulte também o campo de configuração screenLayout, que indica se a tela é grande.

Tela redonda

round

notround
  • round: telas redondas, como em dispositivos wearable redondos
  • notround: telas retangulares, como em celulares ou tablets

Adicionado no nível 23 da API.

Consulte também o método de configuração isScreenRound, que indica se a tela é redonda.

Gama ampla de cores

widecg

nowidecg
  • widecg: telas com uma gama ampla de cores, como Display P3 ou AdobeRGB
  • nowidecg: telas com uma gama estreita de cores, como sRGB

Adicionado no nível 26 da API.

Consulte também o método de configuração isScreenWideColorGamut, que indica se a tela tem uma ampla gama de cores.

High Dynamic Range (HDR)

highdr

lowdr
  • highdr: telas com High Dynamic Range
  • lowdr: telas com alcance dinâmico baixo ou padrão

Adicionado no nível 26 da API.

Consulte também o método de configuração isScreenHdr, que indica se a tela tem recursos HDR.

Orientação da tela

port

land
  • port: o dispositivo está na orientação retrato (vertical)
  • land: o dispositivo está na orientação paisagem (horizontal)

Isso pode mudar durante a vida útil do app se o usuário girar a tela. Para saber mais sobre como isso afeta seu app durante a execução, consulte Processar mudanças de configuração.

Consulte também o campo de configuração orientation, que indica a orientação atual do dispositivo.

Modo de interface

car

desk

television

appliance

watch

vrheadset
  • car: o dispositivo está sendo usado em uma base para carro
  • desk: o dispositivo está sendo usado em uma base para mesa
  • television: o dispositivo está sendo usado em uma televisão, fornecendo uma experiência à distância em que a interface está em uma tela grande de onde o usuário está longe, e a experiência é orientada principalmente em torno do botão direcional ou outra interação sem ponteiro
  • appliance: o dispositivo está servindo como um aparelho, sem tela.
  • watch: o dispositivo tem uma tela que é usada no pulso
  • vrheadset: o dispositivo está sendo usado como um headset de realidade virtual

Adicionado no nível 8 da API, modo televisão adicionado no nível 13 da API, modo eletrodoméstico adicionado no nível 16 da API, modo relógio adicionado no nível 20 da API e modo vrheadset adicionado no nível 26 da API.

Para informações sobre como o app pode responder quando o dispositivo é inserido ou removido de uma base, consulte Como determinar e monitorar o tipo e o estado da base.

Isso pode mudar durante a vida útil do app, se o usuário colocar o dispositivo em uma base. É possível ativar ou desativar alguns desses modos usando UiModeManager. Para saber mais sobre como isso afeta seu app durante a execução, consulte Processar mudanças de configuração.

Modo noturno

night

notnight
  • night: noite
  • notnight: dia

Adicionado no nível 8 da API.

Isso pode mudar durante a vida útil do app, se o modo noturno é deixado no automático (padrão), que muda dependendo do horário. É possível ativar ou desativar esse modo usando UiModeManager. Para saber mais sobre como isso afeta seu app durante a execução, consulte Processar mudanças de configuração.

Densidade de pixel da tela (dpi)

ldpi

mdpi

hdpi

xhdpi

xxhdpi

xxxhdpi

nodpi

tvdpi

anydpi

nnndpi
  • ldpi: são telas de baixa densidade, com aproximadamente 120 dpi.
  • mdpi: são telas de média densidade (em HVGA tradicional), com aproximadamente 160 dpi.
  • hdpi: são telas de alta densidade, com aproximadamente 240 dpi.
  • xhdpi: são telas de densidade extra-alta, com aproximadamente 320 dpi. Adicionado no nível 8 da API.
  • xxhdpi: são telas de densidade extra-extra-alta, com aproximadamente 480 dpi. Adicionado no nível 16 da API.
  • xxxhdpi: usado para telas de densidade extra-extra-extra-alta (somente ícone na tela de início. Consulte Suporte a densidades de pixel diferentes), aproximadamente 640 dpi. Adicionado no nível 18 da API.
  • nodpi: usado para recursos de bitmap que você não quer dimensionar para corresponder à densidade do dispositivo.
  • tvdpi: são telas entre mdpi e hdpi, com aproximadamente 213 dpi. Não é considerado um grupo de densidade "principal".' É destinado principalmente para televisões de 720p, e a maioria dos apps não precisa dele. Para painéis de TV de 1080p, use xhdpi e, para painéis de TV de 4K, use xxxhdpi. Adicionado no nível da API 13.
  • anydpi: corresponde a todas as densidades de tela e tem precedência sobre outros qualificadores. Isso é útil para drawables vetoriais. Adicionado no nível 21 da API.
  • nnndpi: é usado para representar densidades que não são padrão, em que nnn é uma densidade de tela de número inteiro positivo. Isso não é usado na maioria dos casos. O uso de intervalos de densidade padrão reduz bastante a sobrecarga do suporte para as várias densidades de telas de dispositivos no mercado.

Há uma razão de escalonamento de 3:4:6:8:12:16 entre as seis densidades principais (ignorando a densidade tvdpi). Um bitmap de 9 x 9 em ldpi é 12 x 12 em mdpi, 18 x 18 em hdpi, 24 x 24 em xhdpi e assim por diante.

Observação: usar um qualificador de densidade não implica que os recursos são apenas para telas dessa densidade. Caso não forneça recursos alternativos com qualificadores que melhor correspondem à configuração atual do dispositivo, o sistema vai usar quaisquer recursos que representem a melhor correspondência.

Para mais informações sobre como lidar com as diferentes densidades de tela e como o Android pode dimensionar os bitmaps para ajustá-los à densidade atual, consulte Visão geral da compatibilidade da tela.

Tipo de touchscreen

notouch

finger
  • notouch: o dispositivo não tem uma tela touchscreen.
  • finger: o dispositivo tem uma tela touchscreen que se destina à interação direta com o dedo do usuário.

Consulte também o campo de configuração touchscreen, que indica o tipo de touchscreen no dispositivo.

Disponibilidade de teclado

keysexposed

keyshidden

keyssoft
  • keysexposed: o dispositivo tem um teclado disponível. Se o dispositivo tiver um teclado de software ativado (provavelmente tem), ele será usado mesmo quando o teclado de hardware não estiver exposto ao usuário ou se o dispositivo não tiver um teclado de hardware. Caso nenhum teclado de software seja fornecido ou ele esteja desativado, esse elemento só vai ser usado quando um teclado de hardware for exposto.
  • keyshidden: o dispositivo tem um teclado de hardware disponível, mas que está oculto e o dispositivo não tem um teclado de software ativo.
  • keyssoft: o dispositivo tem um teclado de software ativo, visível ou não.

Se você fornecer os recursos keysexposed, mas não os recursos keyssoft, o sistema vai usar os recursos keysexposed independente da visibilidade do teclado, contanto que o sistema tenha um teclado de software ativo.

Isso pode mudar durante a vida útil do app se o usuário abrir um teclado de hardware. Para saber mais sobre como isso afeta seu app durante a execução, consulte Processar mudanças de configuração.

Consulte também os campos de configuração hardKeyboardHidden e keyboardHidden, que indicam a visibilidade de um teclado de hardware e a visibilidade de qualquer tipo de teclado (inclusive de software), respectivamente.

Método principal de entrada de texto

nokeys

qwerty

12key
  • nokeys: o dispositivo não tem teclas de hardware para entradas de texto.
  • qwerty: o dispositivo tem um teclado QWERTY de hardware, esteja ele visível ao usuário ou não.
  • 12key: o dispositivo tem um teclado de hardware de 12 teclas, esteja ele visível ao usuário ou não.

Consulte também o campo de configuração keyboard, que indica o método de entrada de texto principal disponível.

Disponibilidade de teclas de navegação

navexposed

navhidden
  • navexposed: as teclas de navegação estão disponíveis para o usuário.
  • navhidden: as teclas de navegação não estão disponíveis (como as que ficam atrás de uma tampa fechada).

Isso pode mudar durante a vida útil do app se o usuário revelar as teclas de navegação. Para saber mais sobre como isso afeta seu app durante a execução, consulte Processar mudanças de configuração.

Consulte também o campo de configuração navigationHidden, que indica se as teclas de navegação estão ocultas.

Método principal de navegação sem toque

nonav

dpad

trackball

wheel
  • nonav: o dispositivo não tem recursos de navegação além da tela touchscreen.
  • dpad: o dispositivo tem um botão direcional para navegação.
  • trackball: o dispositivo tem um trackball para navegação.
  • wheel: o dispositivo tem rodas direcionais para navegação (incomum).

Consulte também o campo de configuração navigation, que indica o tipo de método de navegação disponível.

Versão da plataforma (nível da API)

Exemplos:

v3

v4

v7

etc.

O nível de API com suporte do dispositivo. Por exemplo, v1 para o nível 1 da API (dispositivos com Android 1.0 ou mais recente) e v4 para o nível 4 da API (dispositivos com Android 1.6 ou mais recente). Para mais informações sobre esses valores, consulte o documento Níveis da API do Android.

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-land é aplicado aos dispositivos em inglês dos EUA na orientação paisagem.
  • Os qualificadores precisam estar na ordem listada na tabela 2.
    • Errado: drawable-hdpi-port/
    • Correto: drawable-port-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. No entanto, não é obrigatório duplicar os arquivos em ambos os locais. Em vez disso, crie um alias para um recurso, conforme descrito na seção Criar recursos de alias.

Depois de salvar os recursos alternativos em 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 recurso mais adequado.

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 funcione como um alias para um recurso salvo no diretório de recursos padrão.

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>. Isso permite que você armazene somente uma versão do arquivo PNG e dois arquivos XML pequenos que apontam para ele. Consulte os exemplos nas próximas seções para mais detalhes.

Drawable

Para criar um alias para um drawable existente, use o elemento <drawable>:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <drawable name="icon">@drawable/icon_ca</drawable>
</resources>

Se você salvar esse arquivo como icon.xml em um diretório de recursos alternativo, como res/values-en-rCA/, ele vai ser compilado em um recurso que pode ser referenciado como R.drawable.icon, mas é um alias do recurso R.drawable.icon_ca, salvo em res/drawable/.

Layout

Para criar um alias para um layout existente, use o elemento <include>, agrupado em um <merge>:

<?xml version="1.0" encoding="utf-8"?>
<merge>
  <include layout="@layout/main_ltr"/>
</merge>

Se você salvar esse arquivo como main.xml, ele vai ser compilado em um recurso que pode ser referenciado como R.layout.main, mas é um alias do recurso R.layout.main_ltr.

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. Ele é sempre composto do seguinte:

  • O tipo de recurso: cada recurso é agrupado em um "tipo", como string, drawable e layout. Para mais informações sobre os diferentes tipos, consulte Visão geral dos tipos de recursos.
  • O nome do recurso, que é o nome do arquivo sem a extensão ou o valor no atributo android:name do XML, se o recurso for um valor simples, como uma string.

Há duas formas de acessar um recurso:

  • No código: usando um número inteiro estático de uma subclasse da sua classe R, como: R.string.hello string é o tipo de recurso e hello é o nome do recurso. Há muitas APIs do Android que podem acessar seus recursos quando você fornece um ID de recurso nesse formato. Para mais informações, consulte a seção Acessar recursos em código.
  • Em XML: usando uma sintaxe XML especial que corresponde ao ID de recurso definido na sua classe R, como: @string/hello string é o tipo de recurso e hello é o nome do recurso. Você pode usar essa sintaxe em um recurso XML em qualquer lugar em que um valor é esperado e que seja fornecido em um recurso. Para mais informações, consulte a seção Acessar recursos do XML.

Acessar recursos no código

Você pode usar um recurso no código transmitindo o ID do recurso como parâmetro do método. Por exemplo, é possível definir um ImageView para usar o recurso res/drawable/myimage.png usando setImageResource:

Kotlin

val imageView = findViewById(R.id.myimageview) as ImageView
imageView.setImageResource(R.drawable.myimage)

Java

ImageView imageView = (ImageView) findViewById(R.id.myimageview);

imageView.setImageResource(R.drawable.myimage);

Você também pode extrair recursos individuais usando métodos em Resources, que podem ser acessados 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.

Casos de uso

Há muitos métodos que aceitam um parâmetro de ID de recurso, e você pode extrair recursos usando métodos em Resources. É possível acessar uma instância de Resources usando Context.getResources.

Veja abaixo alguns exemplos de como acessar recursos no código.

Kotlin

// Load a background for the current screen from a drawable resource.
window.setBackgroundDrawableResource(R.drawable.my_background_image)

// Set the Activity title by getting a string from the Resources object, because
//  this method requires a CharSequence rather than a resource ID.
window.setTitle(resources.getText(R.string.main_title))

// Load a custom layout for the current screen.
setContentView(R.layout.main_screen)

// Set a slide in animation by getting an Animation from the Resources object.
flipper.setInAnimation(AnimationUtils.loadAnimation(this,
        R.anim.hyperspace_in))

// Set the text on a TextView object using a resource ID.
val msgTextView = findViewById(R.id.msg) as TextView
msgTextView.setText(R.string.hello_message)

Java

// Load a background for the current screen from a drawable resource.
getWindow().setBackgroundDrawableResource(R.drawable.my_background_image) ;

// Set the Activity title by getting a string from the Resources object, because
//  this method requires a CharSequence rather than a resource ID.
getWindow().setTitle(getResources().getText(R.string.main_title));

// Load a custom layout for the current screen.
setContentView(R.layout.main_screen);

// Set a slide in animation by getting an Animation from the Resources object.
flipper.setInAnimation(AnimationUtils.loadAnimation(this,
        R.anim.hyperspace_in));

// Set the text on a TextView object using a resource ID.
TextView msgTextView = (TextView) findViewById(R.id.msg);
msgTextView.setText(R.string.hello_message);

Acessar recursos no XML

Você pode definir valores para alguns atributos e elementos XML usando uma referência a um recurso existente. Isso costuma ser feito com frequência ao criar arquivos de layout para fornecer strings e imagens para os widgets.

Por exemplo, se você adicionar um Button ao layout, use um recurso de string para o texto do botão:

<Button
  android:layout_width="fill_parent"
  android:layout_height="wrap_content"
  android:text="@string/submit" />

Sintaxe

Esta é a sintaxe para referenciar um recurso em um recurso XML:

@[<package_name>:]<resource_type>/<resource_name>

  • <package_name> é o nome do pacote em que o recurso está localizado (não é obrigatório ao referenciar recursos do mesmo 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.

Casos de uso

Em alguns casos, é preciso usar um recurso para um valor em XML, como para aplicar uma imagem drawable a um widget, mas você também pode usar um recurso em XML em qualquer lugar que aceite um valor simples. Por exemplo, se você tiver o arquivo de recursos abaixo que inclui um recurso de cor e um recurso de string:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <color name="opaque_red">#f00</color>
  <string name="hello">Hello!</string>
</resources>

É possível usar esses recursos no arquivo de layout abaixo para definir a cor e a string do texto:

<?xml version="1.0" encoding="utf-8"?>
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
  android:layout_width="fill_parent"
  android:layout_height="fill_parent"
  android:textColor="@color/opaque_red"
  android:text="@string/hello" />

Nesse caso, não é preciso especificar o nome do pacote na referência do recurso porque os recursos estão no seu pacote. Para fazer referência a um recurso do sistema, é necessário incluir o nome do pacote, como mostrado no exemplo a seguir:

<?xml version="1.0" encoding="utf-8"?>
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
  android:layout_width="fill_parent"
  android:layout_height="fill_parent"
  android:textColor="@android:color/secondary_text_dark"
  android:text="@string/hello" />

Você pode até mesmo usar recursos em XML para criar alias. Por exemplo, é possível criar um recurso drawable que seja um alias de outro recurso drawable:

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

Isso parece redundante, mas pode ser muito útil ao usar um recurso alternativo. Para mais informações, consulte a seção sobre como criar recursos de alias.

Atributos de estilo de referência

Um recurso de atributo de estilo permite referenciar o valor de um atributo no tema atualmente aplicado. Referenciar um atributo de estilo permite personalizar a aparência de elementos da interface aplicando um estilo a eles para corresponder às variações padrão fornecidas pelo tema atual, em vez de fornecer um valor fixado no código. Referenciar um atributo de estilo basicamente significa "Use o estilo definido por esse atributo no tema atual".

Para referenciar um atributo de estilo, a sintaxe do nome é quase idêntica ao formato normal de recurso, mas, em vez do símbolo arroba (@), use um ponto de interrogação (?). A parte do tipo de recurso é opcional. A sintaxe de referência é a seguinte:

?[<package_name>:][<resource_type>/]<resource_name>

Por exemplo, confira como referenciar um atributo para definir a cor do texto para combinar com a cor de texto secundária do tema do sistema:

<EditText id="text"
  android:layout_width="fill_parent"
  android:layout_height="wrap_content"
  android:textColor="?android:textColorSecondary"
  android:text="@string/hello_world" />

Aqui o atributo android:textColor especifica o nome de um atributo de estilo no tema atual. O Android agora usa o valor aplicado ao atributo de estilo android:textColorSecondary como o valor para android:textColor nesse widget. Como a ferramenta de recursos do sistema sabe que um recurso de atributo é esperado nesse contexto, não é necessário declarar explicitamente o tipo, que é ?android:attr/textColorSecondary. Você pode excluir o tipo attr.

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 um ID de recurso, então 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 AssetManager.

No entanto, 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 uma série de recursos padrão, como estilos, temas e layouts. Para acessar esses recursos, qualifique a referência de recurso com o nome do pacote android. Por exemplo, o Android fornece um recurso de layout que pode ser usado para itens de lista em um ListAdapter:

Kotlin

listAdapter = ArrayAdapter(this, android.R.layout.simple_list_item_1, myarray)

Java

setListAdapter(new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, myarray));

Neste exemplo, simple_list_item_1 é um recurso de layout definido pela plataforma para itens em uma ListView. Você pode usá-lo em vez de criar o próprio layout para itens de lista.

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 usa.

Por exemplo, se o app oferecer suporte a vários idiomas, sempre inclua um diretório values/ (em que as strings são salvas) sem um qualificador 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.

Do mesmo modo, se você fornecer recursos de layout diferentes com base na orientação da tela, escolha uma orientação como a padrão. Por exemplo, em vez de fornecer recursos de layout em layout-land/ para paisagem e layout-port/ para retrato, deixe uma como padrão, por exemplo, layout/ para paisagem e layout-port/ para retrato.

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 versões anteriores não aceitam. Se você usar um novo qualificador de recurso, mas mantiver a compatibilidade do código com versões anteriores do Android, quando uma versão anterior do Android executar seu app, ele vai falhar se você não fornecer recursos padrão, porque ele não poderá 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), um dispositivo com o nível 4 da API não poderá acessar os recursos drawable e vai falhar. Nesse caso, você provavelmente vai querer que notnight seja seu recurso padrão. Portanto, 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 qualificadores de configuração.

Há uma exceção a essa regra: se a minSdkVersion do seu app for 4 ou mais recente, você não precisará de recursos drawable padrão ao fornecer recursos drawable alternativos com o qualificador de densidade de tela. Mesmo sem 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.