Référence des attributs de l'espace de noms tools

Android Studio prend en charge de nombreux attributs XML dans l'espace de noms tools. Ces attributs activent des fonctionnalités au moment de la mise en page (par exemple la mise en page à afficher dans un fragment) ou des comportements au moment de la compilation (par exemple le mode de réduction à appliquer à vos ressources XML). Lorsque vous compilez votre application, les outils de compilation suppriment ces attributs de sorte que cela n'ait pas d'incidence sur la taille de votre APK ni sur le comportement lors de l'exécution.

Pour utiliser ces attributs, ajoutez l'espace de noms tools à l'élément racine de chaque fichier XML dans lequel vous souhaitez les utiliser, comme indiqué ci-dessous :

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

Attributs de gestion des exceptions

Les attributs suivants permettent de supprimer les messages d'avertissement lint :

tools:ignore

Destiné à : tous les éléments

Utilisé par : lint

Cet attribut accepte une liste d'ID de problèmes lint séparés par une virgule que les outils doivent ignorer sur cet élément ou sur l'un de ses descendants.

Vous pouvez par exemple indiquer aux outils d'ignorer l'erreur MissingTranslation :

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

tools:targetApi

Destiné à : tous les éléments

Utilisé par : lint

Cet attribut fonctionne de la même manière que l'annotation @TargetApi dans le code Java. Il vous permet de spécifier le niveau d'API (sous forme d'entier ou de nom de code) prenant en charge cet élément.

Cette action indique aux outils que vous pensez que cet élément (et tous ses enfants) ne sera utilisé qu'au niveau d'API spécifié ou à un niveau supérieur. Ainsi, lint ne vous avertit pas si cet élément ou ses attributs ne sont pas disponibles au niveau de l'API que vous spécifiez en tant que votre minSdkVersion.

Vous pouvez par exemple vous servir de cet attribut parce que GridLayout n'est disponible qu'à partir du niveau d'API 14, mais vous savez que cette mise en page n'est utilisée dans votre code pour aucune version antérieure :

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

(Toutefois, nous vous recommandons d'utiliser plutôt GridLayout dans la bibliothèque Support.)

tools:locale

Destiné à : <resources>

Utilisé par : lint, éditeur Android Studio

Cet attribut indique aux outils la langue/les paramètres régionaux par défaut des ressources dans l'élément <resources> donné, pour éviter les avertissements du correcteur orthographique. Sinon, l'outil suppose que la langue est l'anglais.

La valeur doit correspondre à un qualificatif de paramètres régionaux valide.

Vous pouvez par exemple ajouter cet attribut à votre fichier values/strings.xml pour indiquer que la langue utilisée pour les chaînes par défaut est l'espagnol plutôt que l'anglais :

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

Attributs de la vue au moment de la mise en page

Les attributs suivants définissent les caractéristiques de mise en page qui ne sont visibles que dans l'aperçu de la mise en page Android Studio.

tools: au lieu de android:

Destiné à : <View>

Utilisé par : éditeur de mise en page Android Studio

Vous pouvez insérer des exemples de données dans votre aperçu de mise en page en utilisant le préfixe tools: au lieu de android: avec n'importe quel attribut <View> du framework Android. Cette approche est utile lorsque la valeur de l'attribut n'est pas renseignée avant l'exécution et que vous souhaitez voir l'effet dans l'aperçu de la mise en page.

Par exemple, si la valeur de l'attribut android:text est définie au moment de l'exécution ou si vous souhaitez afficher la mise en page avec une valeur différente de celle par défaut, vous pouvez ajouter tools:text pour spécifier du texte pour l'aperçu de mise en page uniquement.

Figure 1. L'attribut tools:text définit "Google Voice" comme valeur d'aperçu de la mise en page.

Vous pouvez ajouter à la fois l'attribut d'espace de noms android:, utilisé au moment de l'exécution, et l'attribut tools: correspondant, qui se substitue à l'attribut "runtime" uniquement dans l'aperçu de la mise en page.

Vous pouvez également utiliser un attribut tools: pour annuler un paramètre d'attribut uniquement pour l'aperçu de la mise en page. Par exemple, si vous disposez d'un élément FrameLayout avec deux enfants, mais que vous ne souhaitez afficher qu'un seul enfant dans l'aperçu de la mise en page, vous pouvez en définir un de sorte qu'il soit invisible dans l'aperçu de la mise en page, comme indiqué ici :

<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"  />

Lorsque vous utilisez l'éditeur de mise en page dans l'affichage Projet, la fenêtre Propriétés vous permet de modifier certains attributs de la vue au moment de la mise en page. Chaque attribut utilisé au moment de la mise en page est indiqué par une icône en forme de clé plate  figurant à côté du nom de l'attribut, ce qui permet de le distinguer de l'attribut réel portant le même nom.

tools:context

Destiné à : tous les éléments <View> racines

Utilisé par : lint, éditeur de mise en page Android Studio

Cet attribut déclare l'activité à laquelle cette mise en page est associée par défaut. Cela permet d'activer dans l'éditeur ou la mise en page des fonctionnalités qui nécessitent une connaissance de l'activité, par exemple le thème de la mise en page dans l'aperçu et l'emplacement d'insertion des gestionnaires onClick générés à partir d'un QuickFix (figure 2).

Figure 2. Le QuickFix pour l'attribut onClick ne fonctionne que si vous avez défini tools:context.

Vous pouvez spécifier le nom de la classe d'activité en utilisant le même préfixe à point que dans le fichier manifeste (en excluant le nom de package complet).

Exemple :

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

Conseil :Vous pouvez également sélectionner le thème de l'aperçu de la mise en page à partir de l'onglet Barre d'outils de l'éditeur de mise en page.

tools:itemCount

Destiné à : <RecyclerView>

Utilisé par : éditeur de mise en page Android Studio

Pour un RecyclerView donné, cet attribut spécifie le nombre d'éléments que l'éditeur de mise en page doit afficher dans la fenêtre Preview (Aperçu).

Exemple :

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

tools:layout

Destiné à : <fragment>

Utilisé par : éditeur de mise en page Android Studio

Cet attribut déclare la mise en page que l'aperçu de mise en page doit dessiner dans le fragment (car l'aperçu de mise en page ne peut pas exécuter le code d'activité qui applique normalement la mise en page).

Exemple :

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

tools:listitem, tools:listheader, tools:listfooter

Destiné à : <AdapterView> (et sous-classes telles que <ListView>)

Utilisé par : éditeur de mise en page Android Studio

Ces attributs spécifient la mise en page à afficher dans l'aperçu de la mise en page pour les éléments d'une liste, l'en-tête et le pied de page. Tous les champs de données de la mise en page contiennent des contenus numériques comme "Élément 1". Ainsi, les éléments de la liste ne sont pas répétitifs.

Exemple :

<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

Destiné à : tous les éléments <View> racines dans une mise en page désignée par un <include>

Utilisé par : éditeur de mise en page Android Studio

Cet attribut vous permet de pointer vers une mise en page qui utilise cette mise en page avec <include>. Vous pouvez ainsi afficher un aperçu de ce fichier (et le modifier) tel qu'il apparaît lorsqu'il est intégré à sa mise en page parent.

Exemple :

<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" />

L'aperçu de mise en page affiche maintenant cette mise en page TextView telle qu'elle apparaît dans la mise en page activity_main.

tools:menu

Destiné à : tous les éléments <View> racines

Utilisé par : éditeur de mise en page Android Studio

Cet attribut permet d'indiquer le menu de l'aperçu de mise en page à afficher dans la barre d'application. La valeur peut être un ou plusieurs ID de menu, séparés par une virgule (sans @menu/ ni aucun autre préfixe d'ID similaire et sans l'extension .xml).

Exemple :

<?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

Destiné à : <NumberPicker>

Utilisé par : éditeur de mise en page Android Studio

Ces attributs définissent des valeurs minimales et maximales pour une vue NumberPicker.

Exemple :

<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

Destiné à : <DrawerLayout>

Utilisé par : éditeur de mise en page Android Studio

Cet attribut vous permet d'ouvrir un DrawerLayout dans l'aperçu.

Vous pouvez également modifier la façon dont l'éditeur de mise en page affiche la mise en page en transmettant l'une des valeurs suivantes :

Tableau 1. Valeurs permettant de modifier la façon dont l'éditeur de mise en page affiche un DrawerLayout

Constante	Valeur	Description
end	800005	Placer l'objet à la fin de son conteneur, sans modifier sa taille.
left	3	Placer l'objet à gauche de son conteneur, sans modifier sa taille.
right	5	Placer l'objet à droite de son conteneur, sans modifier sa taille.
start	800003	Placer l'objet au départ de son conteneur, sans modifier sa taille.

Exemple :

<androidx.drawerlayout.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" />

Ressources "@tools:sample/*"

Destiné à : toutes les vues acceptant le texte ou les images d'UI

Utilisé par : éditeur de mise en page Android Studio

Cet attribut vous permet d'injecter des données d'espace réservé ou des images dans votre vue. Par exemple, pour pouvoir tester le comportement de votre mise en page avec du texte avant d'avoir finalisé le texte d'UI de votre application, vous pouvez utiliser un texte d'espace réservé, comme dans cet exemple :

<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" />

Le tableau suivant décrit les types de données d'espace réservé que vous pouvez injecter dans vos mises en page :

Tableau 2. Données d'espace réservé dans les mises en page

Valeur d'attribut	Description des données d'espace réservé
@tools:sample/full_names	Noms complets générés de manière aléatoire à partir de la combinaison de @tools:sample/first_names et @tools:sample/last_names
@tools:sample/first_names	Prénoms courants
@tools:sample/last_names	Noms de famille courants
@tools:sample/cities	Noms de villes du monde entier
@tools:sample/us_zipcodes	Codes postaux américains générés de manière aléatoire
@tools:sample/us_phones	Numéros de téléphone générés de manière aléatoire, au format suivant : (800) 555-xxxx
@tools:sample/lorem	Texte d'espace réservé en alphabet latin
@tools:sample/date/day_of_week	Dates et heures aléatoires pour le format spécifié
@tools:sample/date/ddmmyy
@tools:sample/date/mmddyy
@tools:sample/date/hhmm
@tools:sample/date/hhmmss
@tools:sample/avatars	Drawables vectoriels utilisables comme avatars de profil
@tools:sample/backgrounds/scenic	Images utilisables en arrière-plan

Attributs de réduction des ressources

Les attributs suivants vous permettent d'activer des vérifications de référence strictes et de spécifier si vous souhaitez conserver ou supprimer certaines ressources lorsque vous utilisez la réduction des ressources.

Pour activer la réduction des ressources, définissez la propriété shrinkResources sur true dans votre fichier build.gradle (avec minifyEnabled pour la minification du code).

Exemple :

Groovy

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

Kotlin

android {
    ...
    buildTypes {
        getByName("release") {
            isShrinkResources = true
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

tools:shrinkMode

Destiné à : <resources>

Utilisé par : outils de compilation avec réduction des ressources

Cet attribut vous permet de spécifier si les outils de compilation doivent utiliser les éléments suivants :

• Mode sans échec : conservez toutes les ressources explicitement mentionnées et qui peuvent être référencées de manière dynamique en appelant Resources.getIdentifier().
• Mode strict : ne conservez que les ressources explicitement citées dans le code ou dans d'autres ressources.

Le mode sans échec (shrinkMode="safe") est utilisé par défaut. Pour utiliser le mode strict à la place, ajoutez shrinkMode="strict" à la balise <resources>, comme ci-dessous :

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

Lorsque vous activez le mode strict, vous devrez peut-être utiliser tools:keep pour conserver les ressources qui ont été supprimées, mais que vous souhaitez utiliser, et utiliser tools:discard pour supprimer explicitement d'autres ressources supplémentaires.

Pour en savoir plus, consultez la section Réduire vos ressources.

tools:keep

Destiné à : <resources>

Utilisé par : outils de compilation avec réduction des ressources

Lorsque vous utilisez la réduction des ressources pour supprimer des ressources inutilisées, cet attribut vous permet de spécifier les ressources à conserver (en général parce qu'elles sont référencées de manière indirecte lors de l'exécution, par exemple en transmettant un nom de ressource généré dynamiquement à Resources.getIdentifier()).

Pour cela, créez un fichier XML dans votre répertoire de ressources (par exemple, au niveau de res/raw/keep.xml) avec une balise <resources> et spécifiez chaque ressource à conserver dans l'attribut tools:keep sous forme de liste d'éléments séparés par une virgule. Vous pouvez utiliser un astérisque comme caractère générique.

Exemple :

<?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" />

Pour en savoir plus, consultez la section Réduire vos ressources.

tools:discard

Destiné à : <resources>

Utilisé par : outils de compilation avec réduction des ressources

Lorsque vous utilisez la réduction des ressources pour enlever les ressources inutilisées, cet attribut vous permet de spécifier les ressources à supprimer manuellement (en général parce que la ressource est référencée, mais d'une manière qui n'affecte pas votre application, ou parce que le plug-in Gradle a déduit de façon erronée que la ressource est référencée).

Pour cela, créez un fichier XML dans votre répertoire de ressources (par exemple, au niveau de res/raw/keep.xml) avec une balise <resources> et spécifiez chaque ressource à supprimer dans l'attribut tools:discard sous forme de liste d'éléments séparés par une virgule. Vous pouvez utiliser un astérisque comme caractère générique.

Exemple :

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

Pour en savoir plus, consultez la section Réduire vos ressources.