lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey

Fornecimento de recursos

Deve-se sempre exteriorizar os recursos do aplicativo, como imagens e strings do código, para que você possa mantê-los independentemente. Deve-se também fornecer recursos alternativos para configurações específicas do dispositivo, agrupando-os em diretórios de recursos especialmente nomeados. Em tempo de execução, o Android usa o recurso adequado com base na configuração atual. Por exemplo, você pode querer fornecer um layout de IU diferente dependendo do tamanho da tela ou strings diferentes dependendo da configuração de idioma.

Ao exteriorizar os recursos do aplicativo, é possível acessá-los usando códigos de recurso que são gerados na classe R do projeto. O procedimento para usar recursos no aplicativo é discutido em Acesso aos recursos. Este documento mostra como agrupar os recursos no projeto do Android e fornecer recursos alternativos para configurações específicas do dispositivo.

Agrupamento de tipos de recursos

Você deve posicionar cada tipo de recurso em um subdiretório específico do diretório res/ do projeto. Por exemplo, abaixo está 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  

Como se pode ver neste exemplo, o diretório res/ contém todos os recursos (em subdiretórios): um recurso de imagem, dois recursos de layout, diretórios mipmap/ para ícones de inicialização e um arquivo de recurso de string. Os nomes dos diretórios de recursos são importantes e são descritos na tabela 1.

Observação: Para obter mais informações sobre o uso de pastas mipmap, consulte Visão geral do gerenciamento de projetos.

Tabela 1. Os 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 da 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 preferencial para animações de propriedade para distinguir os dois tipos.)
color/ Arquivos XML que definem uma lista de estado de cores. Consulte Recurso de lista de estado de cores
drawable/

Os arquivos Bitmap (.png, .9.png, .jpg, .gif) ou arquivos XML são compilados nos seguintes subtipos de recurso drawable:

  • Arquivos Bitmap
  • Nine-Patch (bitmaps redimensionáveis)
  • Listas de estado
  • Formatos
  • Desenháveis de animação
  • Outros desenháveis

Veja Recursos desenháveis.

mipmap/ Arquivos drawable para diferentes densidades do ícone do inicializador. Para obter mais informações sobre o gerenciamento de ícones do inicializador com pastas mipmap/, consulte Visão geral do gerenciamento de projetos.
layout/ Arquivos XML que definem um layout de interface do usuário. Consulte Recurso de layout.
menu/ Arquivos XML que definem os menus do aplicativo, como menu de opções, menu de contexto ou submenu. Consulte Recurso de menu.
raw/

Arquivos arbitrários para salvar na forma bruta. Para abrir esses recursos com InputStream bruto, chame Resources.openRawResource() com o código do recurso, que é R.raw.filename.

No entanto, se precisar de acesso aos nomes e à hierarquia dos arquivos originais, considere salvar alguns recursos no diretório assets/ (em vez de res/raw/). Os arquivos em assets/ não recebem um código de recurso, portanto é possível lê-los usando apenas o AssetManager.

values/

Arquivos XML que contêm valores simples, como strings, números inteiros e cores.

Enquanto os arquivos de recurso XML estiverem em outros subdiretórios res/, defina 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 <resources> define um único recurso. Por exemplo: um elemento <string> cria um recurso R.string e um elemento <color> 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 esclarecer, você pode querer colocar tipos de recursos únicos em arquivos diferentes. Por exemplo, eis algumas convenções de nome de arquivo para recursos que podem ser criados neste diretório:

Consulte Recursos de string, Recurso de estilo e Mais tipos de recursos.

xml/ Arquivos arbitrários XML que podem ser lidos em tempo de execução chamando Resources.getXML(). Vários arquivos de configuração XML devem ser salvos aqui, como uma configuração buscável.

Atenção: Nunca salve arquivos de recurso diretamente no diretório res/ — isso causará um erro de compilador.

Para obter mais informações sobre determinados tipos de recursos, consulte a documentação Tipos de recursos.

Os recursos salvos nos subdiretórios definidos na tabela 1 são os recursos "padrão". Ou seja, esses recursos definem projeto e conteúdo padrão para o aplicativo. No entanto, tipos diferentes de dispositivos com Android podem chamar diferentes tipos de recursos. Por exemplo, se um dispositivo tiver uma tela maior do que o normal, deverão ser fornecidos recursos de layout diferentes que aproveitem o espaço extra na tela. Ou, se um dispositivo tiver uma configuração de idioma diferente, deve-se fornecer recursos de string diferentes que traduzam o texto na interface do usuário. Para fornecer esses diferentes recursos para configurações de dispositivo diferentes, você precisa fornecer recursos alternativos, além dos recursos padrão.

Fornecimento de recursos alternativos

Figura 1. Dois dispositivos diferentes, cada um usando recursos diferentes de layout.

Quase todos os aplicativos devem fornecer recursos alternativos para suportar configurações específicas do dispositivo. Por exemplo, deve-se incluir recursos desenháveis alternativos para densidades de tela diferentes e recursos alternativos de string para idiomas diferentes. Em tempo de execução, o Android detecta a configuração atual do dispositivo e carrega os recursos adequados para o aplicativo.

Para especificar as alternativas de configuração específica para um conjunto de recursos:

  1. Crie um novo diretório no res/ nomeado na forma de <resources_name>-<config_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 a qual esses recursos destinam-se (definido na tabela 2).

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

    Atenção: Ao anexar vários qualificadores, deve-se colocá-los na mesma ordem em que foram listados na tabela 2. Se os qualificadores estiverem na ordem incorreta, os recursos serão ignorados.

  2. Salve os respectivos recursos alternativos neste novo diretório. Os arquivos de recurso devem ser nomeados exatamente da mesma forma que os arquivos de recurso padrão.

Por exemplo, a seguir 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 tela de alta densidade. As imagens em cada um desses diretórios desenháveis são dimensionadas para uma densidade de tela específica, mas os nomes dos arquivos são exatamente os mesmos. Assim, o código de recurso usado para referenciar icon.png ou a imagem background.png será sempre o mesmo, mas o Android selecionará a versão de cada arquivo que melhor corresponder ao dispositivo atual, comparando as informações de configuração com os qualificadores no nome do diretório do recurso.

O Android é compatível com vários qualificadores de configuração e é possível adicionar vários qualificadores a um nome de diretório separando cada qualificador com um travessão. A tabela 2 lista os qualificadores de configuração válidos, em ordem de precedência — caso use vários qualificadores para um diretório de recursos, você deve adicioná-los ao nome do diretório na ordem que foram 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
etc.

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

Se o dispositivo usar uma conexão de rádio (telefone GSM), os valores MCC e MNC serão os do cartão SIM.

Você também pode usar somente o MCC (por exemplo, para incluir recursos legais específicos do país no aplicativo). Caso precise especificar com base somente no idioma, use o qualificador de idioma e região (discutido a seguir). Caso decida usar o qualificador de MCC e MNC, tome cuidado e teste seu funcionamento.

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

Idioma e região Exemplos:
en
fr
en-rUS
fr-rFR
fr-rCA
etc.

O idioma é definido por um código de idiomaISO 639-1 de duas letras, opcionalmente seguido por um código da região ISO 3166-1-alpha-2 (precedido de "r" em minúsculo).

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

Isso pode mudar durante a vida útil do aplicativo se o usuário mudar o idioma nas configurações do sistema. Consulte Processamento de alterações em tempo de execução para obter informações sobre como isso pode afetar o aplicativo em tempo de execução.

Consulte Localização para obter um guia completo para localizar os aplicativos para outros idiomas.

Veja também o campo de configuração locale, que indica a localidade atual.

Direção do layout ldrtl
ldltr

A direção do layout do aplicativo. ldrtl significa "layout-direction-right-to-left" (direção do layout da direita para a esquerda). ldltr significa "layout-direction-left-to-right" (direção do layout da esquerda para a direita) e é o valor implícito padrão.

Isso pode se aplicar a qualquer recurso, como layouts, desenháveis ou valores.

Por exemplo, caso queira fornecer um layout específico para o idioma árabe e layouts genéricos para outros idiomas que seguem a leitura da direita para a esquerda, como os idiomas hebraico e persa, você teria:

res/
    layout/   
        main.xml  (Default layout)
    layout-ar/  
        main.xml  (Specific layout for Arabic)
    layout-ldrtl/  
        main.xml  (Any "right-to-left" language, except
                  for Arabic, because the "ar" language qualifier
                  has a higher precedence.)

Observação: Para ativar recursos de layout de leitura da direita para a esquerda para o aplicativo, você deve definir supportsRtl como "true" e targetSdkVersion como 17 ou maior.

Adicionado à API de nível 17.

smallestWidth sw<N>dp

Exemplos:
sw320dp
sw600dp
sw720dp
etc.

O tamanho fundamental de uma tela, como indicado pela menor dimensão da área da tela disponível. Especificamente, o valor smallestWidth do dispositivo é o menor da altura e largura da tela (pode-se também interpretar isso como a "menor largura possível" da tela). É possível usar esse qualificador para garantir que, independentemente da orientação atual da tela, o aplicativo tenha ao menos <N> dps de largura disponível para a IU.

Por exemplo: se o layout exigir que a menor dimensão da área da tela seja de pelo menos 600 dp, será possível usar o seguinte qualificador para criar os recursos do layout: res/layout-sw600dp/. O sistema usará esses recursos somente quando a menor dimensão da tela disponível for de pelo menos 600 dp, independentemente se o lado de 600 dp é a altura ou a largura percebida pelo usuário. O valor smallestWidth é uma característica fixa do tamanho da tela do dispositivo;o valor smallestWidth do dispositivo não altera quando a orientação da tela muda.

O valor smallestWidth de um dispositivo leva em consideração decorações de tela e a IU do sistema. Por exemplo, se o dispositivo tiver alguns elementos de IU persistentes na tela que consideram o espaço ao longo do eixo de smallestWidth, o sistema declarará que smallestWidth é menor do que o tamanho atual da tela, pois são pixels de tela não disponíveis para a IU. Portanto, o valor usado deve ser a dimensão real menor necessária para o layout (geralmente, esse valor é a "menor largura" compatível com o layout, independente da orientação atual da tela).

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 aplicativo fornece vários diretórios de recursos com valores diferentes para o qualificador smallestWidth, o sistema usa o mais próximo (sem exceder) ao de smallestWidth do dispositivo.

Adicionado na API de nível 13.

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

Para obter mais informações sobre como projetar para telas diferentes e usar esse qualificador, consulte o guia do desenvolvedor Compatibilidade com várias telas.

Largura disponível w<N>dp

Exemplos:
w720dp
w1024dp
etc.

Especifica uma largura mínima disponível da tela, em unidades dp em que o recurso deve ser usado — definido pelo valor <N>. Esse valor de configuração mudará quando a orientação alternar entre paisagem e retrato para corresponder à largura atual.

Quando o aplicativo fornece vários diretórios de recurso com valores diferentes para essa configuração, o sistema usa o mais próximo (sem exceder) da largura atual da tela do dispositivo. O valor aqui considera as decorações da tela. Portanto, se o dispositivo tiver alguns elementos de IU persistentes na borda esquerda ou direita da tela, ele usará um valor para a largura menor do que o tamanho atual da tela, considerando esses elementos de IU e reduzindo o espaço disponível do aplicativo.

Adicionado na API de nível 13.

Veja também o campo de configuração screenWidthDp, que tem a largura atual da tela.

Para obter mais informações sobre como projetar para telas diferentes e usar esse qualificador, consulte o guia do desenvolvedor Compatibilidade com várias telas.

Altura disponível h<N>dp

Exemplos:
h720dp
h1024dp
etc.

Especifica uma altura mínima disponível da tela, em unidades "dp" em que o recurso deve ser usado — definido pelo valor <N>. Esse valor de configuração mudará quando a orientação alternar entre paisagem e retrato para corresponder à altura atual.

Quando o aplicativo fornece vários diretórios de recursos com valores diferentes para essa configuração, o sistema usa o mais próximo (sem exceder) da altura atual da tela do dispositivo. O valor aqui considera as decorações da tela. Portanto, se o dispositivo tiver alguns elementos de IU persistentes na borda superior ou inferior da tela, ele usará um valor para a altura menor do que o tamanho atual da tela, considerando esses elementos da IU e reduzindo o espaço disponível do aplicativo. As decorações da tela que não forem fixas (como uma barra de status do telefone que pode ser ocultada com tela cheia) não serão consideradas aqui, assim como as decorações da janela, como a barra de título ou a barra de ação. Portanto, os aplicativos devem ser preparados para lidar com o espaço um pouco menor do que especificam.

Adicionado na API de nível 13.

Veja também o campo de configuração screenHeightDp, que tem a largura atual da tela.

Para obter mais informações sobre como projetar para telas diferentes e usar esse qualificador, consulte o guia do desenvolvedor Compatibilidade com várias telas.

Tamanho da tela small
normal
large
xlarge
  • small: Telas de tamanho semelhante à 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 à tela de média densidade HVGA. O tamanho mínimo do layout para uma tela normal é de aproximadamente 320 x 470 unidades dp. Exemplos de tais delas são as WQVGA de baixa densidade, HVGA de média densidade e WVGA de alta densidade.
  • large: Telas de tamanho semelhante à tela de média densidade VGA. 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 720x960 unidades dp. Na maioria dos casos, dispositivos com telas muito grandes seriam grandes demais para serem carregados em bolsos e, provavelmente, seriam dispositivos no estilo tablet. Adicionado à API de nível 9.

Observação: Usar um qualificador de tamanho não significa 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 representarem a melhor correspondência.

Atenção: Se todos os recursos usarem um qualificador de tamanho maior do que a tela atual, o sistema não os usará e o aplicativo apresentará um erro em tempo de execução (por exemplo, se todos os recursos de layout receberem tag com o qualificador xlarge, mas o dispositivo tiver uma tela de tamanho normal).

Adicionado à API de nível 4.

Consulte Compatibilidade com várias telas para obter mais informações.

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

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 à API de nível 4.

Isso baseia-se puramente na relação de aspecto da tela (uma tela "grande" é mais larga). Isso não está relacionado à 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 dispositivo vestíveis redondos
  • notround: Telas retangulares, como celulares ou tablets

Adicionado à API de nível 23.

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

Orientação da tela port
land
  • port: O dispositivo está na orientação de retrato (vertical)
  • land: O dispositivo está na orientação de paisagem (horizontal)

Isso pode mudar durante a vida útil do aplicativo se o usuário girar a tela. Consulte Processamento de alterações em tempo de execução para obter informações sobre como isso pode afetar o aplicativo em tempo de execução.

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

Modo de IU car
desk
television
appliance watch
  • car: O dispositivo está exibindo em uma estação de acoplamento de carro
  • desk: O dispositivo está exibindo em uma estação de acoplamento de mesa
  • television: O dispositivo está exibindo em uma televisão, fornecendo uma experiência à distância, onde a IU é em tela grande, o usuário está longe, orientado principalmente por um controle direcional ou por outro tipo de interação sem indicador
  • appliance: O dispositivo está servindo como uma aplicação, sem tela
  • watch: O dispositivo tem uma tela que é usada no braço

Adicionado à API de nível 8, televisão adicionada à API de nível 13 e relógio adicionado à API de nível 20.

Para obter informações sobre como o aplicativo pode responder quando o dispositivo é inserido ou removido de um dock, consulte Determinação e monitoramento do tipo e do estado do dock.

Isso pode mudar durante a vida útil do aplicativo se o usuário colocar o dispositivo em um dock. É possível ativar ou desativar alguns desses modos usando UiModeManager. Consulte Processamento de alterações em tempo de execução para obter informações sobre como isso pode afetar o aplicativo em tempo de execução.

Modo noturno night
notnight
  • night: Noite
  • notnight: Dia

Adicionado à API de nível 8.

Isso pode mudar durante a vida útil do aplicativo se o modo noturno for deixado no modo automático (padrão), em que o modo altera-se com base no horário. É possível ativar ou desativar esse modo usando UiModeManager. Consulte Processamento de alterações em tempo de execução para obter informações sobre como isso pode afetar o aplicativo em tempo de execução.

Densidade de pixel da tela (dpi) ldpi
mdpi
hdpi
xhdpi
xxhdpi
xxxhdpi
nodpi
tvdpi
anydpi
  • ldpi: Telas de baixa densidade, aproximadamente 120 dpi.
  • mdpi: Telas de média densidade (em HVGA tradicional); aproximadamente 160 dpi.
  • hdpi: Telas de alta densidade, aproximadamente 240 dpi.
  • xhdpi: Telas de densidade extra-alta, aproximadamente 320 dpi. Adicionado à API de nível 8
  • xxhdpi: Telas de densidade extra-extra-alta, aproximadamente 480 dpi. Adicionado à API de nível 16
  • xxxhdpi: Usos de densidade extra-extra-extra-alta (somente ícone do inicializador, consulte a observação em Compatibilidade com várias telas), aproximadamente 640 dpi. Adicionado à API de nível 18
  • nodpi: Isso pode ser usado para recursos de bitmap que você não deseja dimensionar para corresponder à densidade do dispositivo.
  • tvdpi: Telas entre mdpi e hdpi, aproximadamente 213 dpi. Não é considerado um grupo de densidade "principal". Geralmente usado para televisões e a maioria dos aplicativos não precisam — fornecer recursos mdpi e hdpi é o suficiente para a maioria dos aplicativos e o sistema dimensionará de forma adequada. Adicionado à API de nível 13
  • anydpi: Esse qualificador corresponde a todas as densidades de tela e é priorizado em relação a outros qualificadores. Isso é útil para drawables vetoriais. Adicionado à API de nível 21

Há uma razão de dimensionamento de 3:4:6:8:12:16 entre as seis densidades principais (ignorando a densidade tvdpi). Então, 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.

Caso decida que os recursos de imagem não parecem suficientemente bons para uma televisão ou outros dispositivos e queira testar recursos tvdpi, o fator de dimensionamento é 1,33*mdpi. Por exemplo, uma imagem de 100 px x 100 px para telas mdpi deve ser de 133 px x 133 px para tvdpi.

Observação: Usar um qualificador de densidade não significa que os recursos sejam apenas para telas desta densidade. Caso não forneça recursos alternativos com qualificadores que melhor correspondem à configuração atual do dispositivo, o sistema poderá usar quaisquer recursos que representarem a melhor correspondência.

Consulte Compatibilidade com várias telas para obter mais informações sobre como lidar com as diferentes densidades de tela e como o Android pode dimensionar os bitmaps para encaixá-los na densidade atual.

Tipo de tela tátil notouch
finger
  • notouch: Os dispositivos não têm uma tela sensível ao toque.
  • finger: O dispositivo tem uma tela sensível ao toque que se destina à interação direcional do dedo do usuário.

Veja também o campo de configuração touchscreen, que indica o tipo de tela sensível ao toque no dispositivo.

Disponibilidade de teclado keysexposed
keyshidden
keyssoft
  • keysexposed: O dispositivo tem um teclado disponível. Se o dispositivo tiver um teclado de software ativo (o que é provável), ele deverá ser usado mesmo quando o teclado de hardware não estiver exposto ao usuário, mesmo se o dispositivo não tiver teclado de hardware. Caso nenhum teclado de software seja fornecido ou esteja desativado, isso será usado apenas quando um teclado de hardware for exposto.
  • keyshidden: O dispositivo tem um teclado de hardware disponível, mas 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 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 aplicativo se o usuário abrir um teclado de hardware. Consulte Processamento de alterações em tempo de execução para obter informações sobre como isso pode afetar o aplicativo em tempo de execução.

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

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

Versão da plataforma (nível de API) Exemplos:
v3
v4
v7
etc.

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

Observação: Alguns qualificadores de configuração foram adicionados desde o Android 1.0, então nem todas as versões do Android suportam todos eles. Usar um novo qualificador adiciona implicitamente um qualificador da versão de plataforma, então dispositivos mais antigos com certeza o ignorarão. Por exemplo, usar um qualificador w600dp incluirá automaticamente o qualificador v13, pois o qualificador de largura disponível era novo na API de nível 13. Para evitar quaisquer problemas, sempre inclua um conjunto de recursos padrão (um conjunto de recursos sem qualificadores). Para obter mais informações, consulte a seção Fornecimento da melhor compatibilidade de dispositivo com recursos.

Regras de nome do qualificador

Eis 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 aplica-se aos dispositivos em inglês dos E.U.A. na orientação de paisagem.
  • Os qualificadores devem estar na ordem listada na tabela 2. Por exemplo:
    • Incorreto: drawable-hdpi-port/
    • Correto: drawable-port-hdpi/
  • Os diretórios de recursos alternativos não podem ser aninhados. Por exemplo, não é possível ter 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 processar para evitar problemas nos sistemas de arquivo que não diferenciam maiúsculas e minúsculas. Qualquer letra maiúscula nos nomes é apenas para o benefício da leitura.
  • Somente um valor para cada tipo de qualificador é suportado. Por exemplo, se você quiser usar os mesmos arquivos desenháveis para Espanha e França, não será possível ter um diretório chamado drawable-rES-rFR/. Em vez disso, você precisa de dois diretórios de recursos, como drawable-rES/ e drawable-rFR/, que contenham arquivos adequados. No entanto, não é necessário duplicar os mesmos arquivos em ambos os locais. Em vez disso, é possível criar um alias para um recurso. Consulte Criação de recursos de alias abaixo.

Após salvar os recursos alternativos nos diretórios nomeados com esses qualificadores, o Android aplicará automaticamente os recursos no aplicativo com base na configuração atual do dispositivo. Sempre que um recurso for solicitado, o Android verificará diretórios de recursos alternativos que contenham o arquivo de recurso solicitado e, em seguida,encontrará o melhor recurso correspondente (discutido abaixo). Se não houver recursos alternativos que correspondam a uma configuração de dispositivo específica, o Android 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).

Criação de recursos de alias

Quando estiver com um recurso que gostaria de usar para mais de uma configuração de dispositivo, mas não quer fornecê-lo como um recurso padrão), não será necessário usar o mesmo recurso em mais de um diretório de recursos alternativos. Em vez disso, é possível (em alguns casos) criar um recurso alternativo que age como um alias para um recurso salvo no diretório de recurso padrão.

Observação: Nem todos os recursos oferecem um mecanismo que possibilita criar um alias para outro recurso. Em particular, recursos de animação, de menu, brutos e de outros tipos no diretório xml/ não oferecem essa função.

Por exemplo: você tem um ícone do aplicativo, 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. Você pode presumir que precisa copiar a mesma imagem para o diretório do recurso do inglês canadense e do francês canadense, mas não é verdade. Em vez disso, é possível salvar a imagem que é usada para ambos como icon_ca.png (qualquer nome que não seja icon.png) e colocá-la no diretório res/drawable/ padrão. Em seguida, crie um arquivo icon.xml em res/drawable-en-rCA/ e em res/drawable-fr-rCA/ que referencie o recurso icon_ca.png usando o elemento <bitmap>. Isso permite que você armazene apenas uma versão do arquivo PNG e dois arquivos XML pequenos que apontam para ele. (Um exemplo de arquivo XML é exibido abaixo)

Desenhável

Para criar um alias para um drawable existente, use o elemento <bitmap>. Por exemplo:

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

Se salvar esse arquivo como icon.xml (em um diretório de recursos alternativos, como res/drawable-en-rCA/), ele 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>. Por exemplo:

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

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

Strings e outros valores simples

Para criar um alias para uma string existente, basta usar o ID de recurso da string desejado como o valor para a nova string. Por exemplo:

<?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 forma. Por exemplo, uma cor:

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

Fornecimento da melhor compatibilidade de dispositivo com recursos

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

Por exemplo: se o aplicativo for compatível com vários idiomas, sempre inclua um diretório values/ (em que as strings sejam salvas) sem qualificadores de região e idioma. Se colocar todos os arquivos de string em diretórios que têm qualificadores de região e idioma, o aplicativo apresentará erros ao entrar em execução em dispositivo configurado para um idioma que as strings não suportem. Porém, contanto que você forneça recursos values/ padrão, o aplicativo será executado sem problemas (mesmo que o usuário não entenda o idioma — é melhor do que apresentar erros).

Do mesmo modo, se você fornecer recursos de layout diferentes com base na orientação da tela, deve escolher 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, como layout/ para paisagem e layout-port/ para retrato.

Fornecer recursos padrão é importante não só porque o aplicativo pode ser executado em uma configuração que você não tenha antecipado, mas também as novas versões do Android, às vezes, adicionam qualificadores de configuração que as versões mais antigas não suportam. Se 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 aplicativo, ocorrerá um erro caso você não forneça os recursos padrão, pois ele não poderá usar os recursos nomeados com o novo qualificador. Por exemplo: se minSdkVersion estiver definido como 4 e você qualificar todos os recursos drawable usando o modo noturno (night ou notnight, que foram adicionados à API de nível 8), o dispositivo com API de nível 4 não poderá acessar os recursos drawable e apresentará erro. Neste caso, você provavelmente quererá que notnight seja o recurso padrão, portanto deverá excluir esse qualificador para que os recursos drawable fiquem em drawable/ ou drawable-night/.

Então, para fornecer a melhor compatibilidade de dispositivo, sempre forneça os recursos padrão para os recursos imprescindíveis para o aplicativo para obter o desempenho adequado. Em seguida, crie recursos para configurações específicas de dispositivo usando os qualificadores de configuração.

Há uma exceção a essa regra: Se a minSdkVersion do aplicativo for 4 ou mais recente, você não precisará de recursos drawable padrão ao fornecer recursos drawable alternativos com o qualificador de densidade da tela. Mesmo sem os recursos desenháveis padrão, o Android poderá encontrar a melhor correspondência dentre as densidades de tela alternativas e dimensionar os bitmaps conforme necessário. No entanto, para obter a melhor experiência em todos os tipos de dispositivo, você deve fornecer desenháveis alternativos para todos os três tipos de densidade.

Como o Android encontra o melhor recurso correspondente

Ao solicitar um recurso para o qual você fornece alternativas, o Android seleciona quais recursos alternativos usar em tempo de execução, dependendo da configuração do dispositivo atual. Para demonstrar como o Android seleciona um recurso alternativo, presuma que os seguintes diretórios desenháveis contenham versões diferentes das mesmas imagens:

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

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

Localidade = en-GB
Orientação da tela = port
Densidade de pixel da tela = hdpi
Tipo de tela sensível ao toque = notouch
Método principal de entrada de texto = 12key

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

O sistema chega à conclusão de quais recursos deve usar com a seguinte 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, pois contradiz a localidade en-GB.

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

    Exceção: A densidade de pixel da tela é a que o qualificador não eliminou devido a uma contradição. Apesar de a densidade da tela do dispositivo ser hdpi, drawable-port-ldpi/ não é eliminado, pois todas as densidades de telas são consideradas uma correspondência neste ponto. Obtenha mais informações no documento Compatibilidade com várias telas.

  2. Escolha o (próximo) qualificador de maior precedência na lista (tabela 2). (Comece com MCC e, em seguida, siga para baixo.)
  3. Algum dos diretórios de recurso incluem esse qualificador?
    • Se não, volte à etapa 2 e veja o próximo qualificador. (Neste exemplo, a resposta é "não" até que o qualificador de idioma seja alcançado.)
    • Se sim, prossiga para a etapa 4.
  4. Elimine os diretórios de recurso que não incluem esse qualificador. No exemplo, o sistema elimina todos os diretórios que não incluem um qualificador de idioma:
  5. drawable/
    drawable-en/
    drawable-en-port/
    drawable-en-notouch-12key/
    drawable-port-ldpi/
    drawable-port-notouch-12key/
    

    Exceção: Se o qualificador em questão for a densidade de pixel da tensidade da tela do dispositivo de forma mais aproximada. Geralmente, o Android prefere dimensionar uma imagem original maior em vez de uma maior. Consulte Compatibilidade com várias telas.

  6. Volte e repita as etapas 2, 3 e 4 até que reste apenas um diretório. No exemplo, a orientação da tela é o próximo qualificador, onde há várias correspondências. Portanto, os recursos que não especificarem uma orientação de tela serão eliminados:
    drawable-en/
    drawable-en-port/
    drawable-en-notouch-12key/
    

    O diretório restante é drawable-en-port.

Apesar de esse processo ser executado para cada recurso solicitado, o sistema posteriormente aprimora alguns aspectos. Tal otimização, quando a configuração do dispositivo é conhecida, pode eliminar os recursos alternativos que nunca correspondem. Por exemplo, se o idioma da configuração for inglês ("en"), qualquer diretório de recurso que tiver um qualificador de idioma definido para outro idioma que não seja inglês nunca 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 usará os recursos projetados para uma tela menor do que a tela atual, caso não tenha recursos que correspondam de forma mais eficaz (por exemplo, uma tela de tamanho grande usará os recursos de tela de tamanho normal se necessário). No entanto, se os únicos recursos disponíveis forem maiores do que a tela atual, o sistema não os usará e o aplicativo apresentará erros se nenhum outro recurso corresponder à configuração do dispositivo (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. Por exemplo, na etapa 4 acima, a última escolha na lista inclui três qualificadores que correspondem exatamente ao dispositivo (orientação, tipo de tela sensível ao toque e método de entrada), enquanto que drawable-en tem apenas um parâmetro que corresponde (idioma). No entanto, o idioma tem uma precedência maior que esses outros qualificadores, então drawable-port-notouch-12key está fora.

Para obter mais informações sobre como usar os recursos no aplicativo, acesse Acesso aos recursos.