Referência de atributos de ferramentas

O Android Studio é compatível com vários atributos XML no namespace tools que permitem recursos de tempo de design (como qual layout exibir em um fragmento) ou comportamentos em tempo de compilação (como o modo de redução aplicado aos recursos XML). Quando você cria seu app, as ferramentas de compilação removem esses atributos para que não haja efeito no tamanho do APK ou no comportamento do ambiente de execução.

Para usar esses atributos, adicione o namespace tools ao elemento raiz de cada arquivo XML em que você quer usá-los, conforme mostrado aqui:

    <RootTag xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools" >
    

Atributos de processamento de erros

Os atributos a seguir ajudam a suprimir mensagens de aviso de lint.

tools:ignore

Destinado a: qualquer elemento

Usado por: lint

Esse atributo aceita uma lista separada por vírgulas de IDs de problemas de lint que você quer que as ferramentas ignorem neste elemento ou em qualquer um dos descendentes dele.

Por exemplo, você pode dizer às ferramentas para ignorar o erro MissingTranslation:

<string name="show_all_apps" tools:ignore="MissingTranslation">All</string>
    

tools:targetApi

Destinado a: qualquer elemento

Usado por: lint

Esse atributo funciona da mesma forma que a anotação @TargetApi no código Java: ele permite especificar o nível da API (como um número inteiro ou um nome de código) que é compatível com esse elemento.

Isso informa às ferramentas que você acredita que esse elemento (e qualquer filho) será usado apenas no nível de API especificado ou em níveis posteriores. Isso impede que o lint avise se esse elemento ou os atributos dele não estão disponíveis no nível da API que você especificou como minSdkVersion.

Por exemplo, você pode usar isso porque GridLayout está disponível somente no nível de API 14 e posteriores, mas você sabe que esse layout não é usado para versões anteriores:

<GridLayout xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        tools:targetApi="14" >
    

No entanto, você pode usar GridLayout a partir da Biblioteca de Suporte.

tools:locale

Destinado a: <resources>

Usado por: lint, editor do Android Studio

Para evitar avisos do corretor ortográfico, isso informa às ferramentas qual é o idioma/a localidade padrão dos recursos no elemento <resources> fornecido, porque as ferramentas presumem que seja o inglês. O valor precisa ser um qualificador de localidade válido.

Por exemplo, você pode adicionar isso ao arquivo values/strings.xml (os valores de string padrão) para indicar que o idioma usado para as strings padrão é espanhol em vez de inglês:

<resources xmlns:tools="http://schemas.android.com/tools"
        tools:locale="es">
    

Atributos de visualização no tempo de design

Os seguintes atributos definem características de layout que são visíveis apenas na visualização do layout do Android Studio.

tools: em vez de android:

Destinado a: <View>

Usado por: editor de layout do Android Studio

Você pode inserir dados de amostra na visualização de layout usando o prefixo tools: em vez de android: com qualquer atributo <View> da estrutura do Android. Isso é útil quando o valor do atributo não é preenchido até o tempo de execução, mas você quer ver o efeito antecipadamente, na visualização do layout.

Por exemplo, se o valor do atributo android:text for definido no tempo de execução ou você quiser ver o layout com um valor diferente do padrão, será possível adicionar tools:text para especificar algum texto somente para a visualização do layout.

Figura 1. O atributo tools:text define "Google Voice" como o valor da visualização do layout

Você pode adicionar o atributo de namespace android: (que é usado no tempo de execução) e o atributo tools: correspondente (que modifica o atributo de tempo de execução apenas na visualização do layout).

Você também pode usar um atributo tools: para desmarcar um atributo somente para a visualização do layout. Por exemplo, se você tiver um FrameLayout com vários filhos, mas quiser ver apenas um filho na visualização do layout, poderá configurar os outros para ficarem invisíveis, conforme mostrado aqui:

    <Button
        android:id="@+id/button"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="First" />

    <Button
        android:id="@+id/button2"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Second"
        tools:visibility="invisible"  />
    

Ao usar o Layout Editor na visualização de design, a janela Properties também permite editar alguns atributos de visualização de tempo de design. Cada atributo de tempo de design é indicado com um ícone de chave inglesa ao lado do nome do atributo para distingui-lo do atributo real com o mesmo nome.

tools:context

Destinado a: qualquer raiz <View>

Usado por: lint, editor de layout do Android Studio

Esse atributo declara com qual atividade esse layout está associado por padrão. Isso ativa recursos no editor ou na visualização do layout que exigem confirmação da atividade, como qual será o tema de layout na visualização e onde inserir os gerenciadores onClick ao fazer uma correção rápida (Figura 2).

Figura 2. A correção rápida para o atributo onClick só funciona se você definir tools:context

Você pode especificar o nome da classe de atividade usando o mesmo prefixo de ponto do arquivo de manifest (excluindo o nome completo do pacote). Exemplo:

<android.support.constraint.ConstraintLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        tools:context=".MainActivity" >
    

Dica: você também pode selecionar o tema para a visualização do layout na barra de ferramentas do Layout Editor.

tools:itemCount

Destinado a: <RecyclerView>

Usado por: editor de layout do Android Studio

Para um determinado RecyclerView, esse atributo especifica o número de itens que o editor de layout precisa renderizar na janela Preview.

Exemplo:

<android.support.v7.widget.RecyclerView
        android:id="@+id/recyclerView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:itemCount="3"/>
    

tools:layout

Destinado a: <fragment>

Usado por: editor de layout do Android Studio

Esse atributo declara qual layout você quer que a visualização do layout desenhe dentro do fragmento, porque a visualização do layout não pode executar o código de atividade que normalmente aplica o layout.

Exemplo:

<fragment android:name="com.example.master.ItemListFragment"
        tools:layout="@layout/list_content" />
    

tools:listitem / tools:listheader / tools:listfooter

Destinado a: <AdapterView> (e subclasses como <ListView>)

Usado por: editor de layout do Android Studio

Esses atributos especificam qual layout será exibido na visualização do layout para os itens, cabeçalho e rodapé de uma lista. Todos os campos de dados no layout são preenchidos com conteúdo numérico, como "Item 1", para que os itens da lista não sejam repetitivos.

Exemplo:

<ListView xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:id="@android:id/list"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:listitem="@layout/sample_list_item"
        tools:listheader="@layout/sample_list_header"
        tools:listfooter="@layout/sample_list_footer" />
    

tools:showIn

Destinado a: qualquer raiz <View> em um layout referido por <include>

Usado por: editor de layout do Android Studio

Esse atributo permite apontar para um layout que usa esse layout como uma inclusão para que você possa visualizar (e editar) esse arquivo como ele aparece enquanto incorporado no layout pai.

Exemplo:

<TextView xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:text="@string/hello_world"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        tools:showIn="@layout/activity_main" />
    

Agora, a visualização do layout mostra esse layout TextView da maneira como ele aparece dentro do layout activity_main.

tools:menu

Destinado a: qualquer raiz <View>

Usado por: editor de layout do Android Studio

Esse atributo especifica qual menu a visualização do layout precisa mostrar na barra de apps. O valor pode ser um ou mais IDs de menu, separados por vírgulas (sem @menu/ ou qualquer prefixo de ID e sem a extensão .xml). Exemplo:

<?xml version="1.0" encoding="utf-8"?>
    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:orientation="vertical"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:menu="menu1,menu2" />
    

tools:minValue / tools:maxValue

Destinado a: <NumberPicker>

Usado por: editor de layout do Android Studio

Esses atributos definem valores mínimos e máximos para uma visualização NumberPicker.

Exemplo:

<NumberPicker xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:id="@+id/numberPicker"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        tools:minValue="0"
        tools:maxValue="10" />
    

tools:openDrawer

Destinado a: <DrawerLayout>

Usado por: editor de layout do Android Studio

Esse atributo permite abrir um DrawerLayout no painel Preview do editor de layout. Você também pode modificar de que maneira o editor renderiza o layout passando um dos seguintes valores:

Constante	Valor	Descrição
end	800005	Envie o objeto para o final do contêiner, sem alterar o tamanho dele.
left	3	Envie o objeto para a esquerda do contêiner, sem alterar o tamanho dele.
right	5	Envie o objeto para a direita do contêiner, sem alterar o tamanho dele.
start	800003	Envie o objeto para o início do contêiner, sem alterar o tamanho dele.

Exemplo:

<android.support.v4.widget.DrawerLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:id="@+id/drawer_layout"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:openDrawer="start" />
    

Recursos "@tools:sample/*"

Destinado a: qualquer visualização que seja compatível com texto ou imagens da IU.

Usado por: editor de layout do Android Studio

Esse atributo permite injetar dados ou imagens de marcador na visualização. Por exemplo, se você quiser testar como o layout se comporta com o texto, mas ainda não tiver concluído o texto da IU para seu app, use o texto do marcador da seguinte maneira:

<TextView xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        tools:text="@tools:sample/lorem" />
    

A tabela a seguir descreve os tipos de dados de marcadores de posição que você pode injetar nos layouts.

Valor do atributo	Descrição dos dados do marcador
@tools:sample/full_names	Nomes completos que são gerados aleatoriamente a partir da combinação de @tools:sample/first_names e @tools:sample/last_names.
@tools:sample/first_names	Nomes comuns.
@tools:sample/last_names	Sobrenomes comuns.
@tools:sample/cities	Nomes de cidades de todo o mundo.
@tools:sample/us_zipcodes	Códigos postais dos EUA gerados aleatoriamente.
@tools:sample/us_phones	Números de telefone gerados aleatoriamente, com o seguinte formato: (800) 555-xxxx.
@tools:sample/lorem	Texto de marcador derivado do latim.
@tools:sample/date/day_of_week	Datas e horários aleatórios para o formato especificado.
@tools:sample/date/ddmmyy
@tools:sample/date/mmddyy
@tools:sample/date/hhmm
@tools:sample/date/hhmmss
@tools:sample/avatars	Drawables de vetor que você pode usar como avatares de perfil.
@tools:sample/backgrounds/scenic	Imagens que você pode usar como planos de fundo.

Atributos de redução de recursos

Os atributos a seguir permitem que você ative verificações de referência estritas e declare se quer manter ou descartar certos recursos ao usar a redução de recursos.

Para ativar a redução de recursos, defina a propriedade shrinkResources como true no arquivo build.gradle (junto a minifyEnabled para a redução de código). Exemplo:

android {
        ...
        buildTypes {
            release {
                shrinkResources true
                minifyEnabled true
                proguardFiles getDefaultProguardFile('proguard-android.txt'),
                        'proguard-rules.pro'
            }
        }
    }
    

tools:shrinkMode

Destinado a: <resources>

Usado por: ferramentas de compilação com redução de recursos

Esse atributo permite que você especifique se as ferramentas de compilação usarão o "modo de segurança" (reproduzir com segurança e manter todos os recursos explicitamente citados e que possam ser referenciados dinamicamente com uma chamada para Resources.getIdentifier()) ou o "modo estrito" (manter apenas os recursos explicitamente citados no código ou em outros recursos).

O padrão é usar o modo de segurança (shrinkMode="safe"). Para usar o modo estrito, adicione shrinkMode="strict" à tag <resources>, como mostrado aqui:

<?xml version="1.0" encoding="utf-8"?>
    <resources xmlns:tools="http://schemas.android.com/tools"
        tools:shrinkMode="strict" />
    

Quando você ativa o modo estrito, pode ser necessário usar tools:keep para manter os recursos que foram removidos, mas que você realmente quer, e usar tools:discard para remover explicitamente ainda mais recursos.

Para mais informações, consulte Reduza seus recursos.

tools:keep

Destinado a: <resources>

Usado por: ferramentas de compilação com redução de recursos

Ao usar a redução de recursos para remover recursos não utilizados, esse atributo permite que você especifique recursos que gostaria de manter, geralmente porque eles são referenciados indiretamente no tempo de execução, por exemplo, passando um nome de recurso gerado dinamicamente para Resources.getIdentifier().

Para usá-la, crie um arquivo XML no diretório de recursos (por exemplo, em res/raw/keep.xml) com uma tag <resources> e especifique cada recurso que deve ser mantido no atributo tools:keep como uma lista separada por vírgulas. Você pode usar o caractere asterisco como curinga. Exemplo:

<?xml version="1.0" encoding="utf-8"?>
    <resources xmlns:tools="http://schemas.android.com/tools"
        tools:keep="@layout/used_1,@layout/used_2,@layout/*_3" />
    

Para mais informações, consulte Reduza seus recursos.

tools:discard

Destinado a: <resources>

Usado por: ferramentas de compilação com redução de recursos

Ao usar a redução de recursos para remover recursos não utilizados, esse atributo permite que você especifique aqueles que quer descartar de modo manual, geralmente porque o recurso é referenciado, mas de uma maneira que não afeta seu app, ou porque o plug-in do Gradle deduziu incorretamente que o recurso é referenciado.

Para usá-la, crie um arquivo XML no diretório de recursos (por exemplo, em res/raw/keep.xml) com uma tag <resources> e especifique cada recurso que deve ser mantido no atributo tools:discard como uma lista separada por vírgulas. Você pode usar o caractere asterisco como curinga. Exemplo:

<?xml version="1.0" encoding="utf-8"?>
    <resources xmlns:tools="http://schemas.android.com/tools"
        tools:discard="@layout/unused_1" />
    

Para mais informações, consulte Reduza seus recursos.