Справочник по атрибутам инструментов

Android Studio поддерживает различные атрибуты XML в пространстве имен tools , которые позволяют использовать функции времени разработки, например, какой макет отображать во фрагменте, или поведение во время компиляции, например, какой режим сжатия применять к вашим ресурсам XML. Когда вы создаете свое приложение, инструменты сборки удаляют эти атрибуты, чтобы это не повлияло на размер APK или поведение во время выполнения.

Чтобы использовать эти атрибуты, добавьте пространство имен tools в корневой элемент каждого XML-файла, в котором вы хотите их использовать, как показано здесь: 

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

Атрибуты обработки ошибок

Следующие атрибуты помогают подавлять предупреждающие сообщения о lint:

tools:ignore

Назначение: Любой элемент

Использует: Линт

Этот атрибут принимает разделенный запятыми список идентификаторов проблем с анализом, которые вы хотите, чтобы инструменты игнорировали для этого элемента или любого из его потомков.

Например, вы можете указать инструментам игнорировать ошибку MissingTranslation : 

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

tools:targetApi

Назначение : Любой элемент

Использует : Линт

Этот атрибут работает так же, как аннотация @TargetApi в коде Java. Он позволяет указать уровень API (в виде целого числа или кодового имени), который поддерживает этот элемент.

Это сообщает инструментам, что вы считаете, что этот элемент и все дочерние элементы используются только на указанном уровне API или выше. Это не позволяет lint предупреждать вас, если этот элемент или его атрибуты недоступны на уровне API, который вы указываете в качестве minSdkVersion .

Например, вы можете использовать этот атрибут, поскольку GridLayout доступен только на уровне API 14 и выше, но вы знаете, что этот макет не используется в вашем коде для более низких версий:

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

(Однако обратите внимание, что вместо этого мы рекомендуем использовать GridLayout из библиотеки поддержки.)

tools:locale

Предназначено для: <resources>

Используется: Lint, редактор Android Studio.

Это сообщает инструментам, какой язык или локаль по умолчанию используется для ресурсов в данном элементе <resources> , чтобы избежать предупреждений от средства проверки правописания. В противном случае инструмент предполагает, что выбран английский язык.

Значение должно быть допустимым квалификатором локали .

Например, вы можете добавить это в файл values/strings.xml чтобы указать, что языком, используемым для строк по умолчанию, является испанский, а не английский: 

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

Атрибуты представления времени разработки

Следующие атрибуты определяют характеристики макета, которые видны только в предварительном просмотре макета Android Studio.

tools: вместо android:

Предназначено для: <View>

Используется: редактор макетов Android Studio.

Вы можете вставить образцы данных в предварительный просмотр макета, используя префикс tools: вместо android: с любым атрибутом <View> из платформы Android. Это полезно, когда значение атрибута не заполняется до времени выполнения, и вы хотите увидеть эффект в предварительном просмотре макета.

Например, если значение атрибута android:text установлено во время выполнения или вы хотите видеть макет со значением, отличным от значения по умолчанию, вы можете добавить tools:text , чтобы указать некоторый текст только для предварительного просмотра макета.

Атрибут Tools:text устанавливает Google Voice в качестве значения для предварительного просмотра макета.
Рис. 1. Атрибут tools:text устанавливает «Google Voice» в качестве значения для предварительного просмотра макета.

Вы можете добавить как атрибут android: namespace, который используется во время выполнения, так и соответствующий атрибут tools: который переопределяет атрибут времени выполнения только в предварительном просмотре макета.

Вы также можете использовать tools: чтобы отменить настройку атрибута только для предварительного просмотра макета. Например, если у вас есть FrameLayout с двумя дочерними элементами, но вы хотите видеть только один дочерний элемент в предварительном просмотре макета, вы можете сделать один из них невидимым в предварительном просмотре макета, как показано здесь:

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

При использовании редактора макетов в представлении «Дизайн» окно «Свойства» позволяет редактировать некоторые атрибуты представления во время разработки. Каждый атрибут времени разработки обозначается значком гаечного ключа. Значок гаечного ключа рядом с именем атрибута, чтобы отличить его от реального атрибута с тем же именем.

tools:context

Назначение: Любой корень <View>

Используется: Lint, редактор макетов Android Studio.

Этот атрибут объявляет, с каким действием по умолчанию связан этот макет. Это позволяет использовать функции в редакторе или предварительном просмотре макета, которые требуют знания действия, например, что такое тема макета в предварительном просмотре и куда вставлять обработчики onClick , созданные в результате быстрого исправления, как показано на рисунке 2.

Быстрое исправление для атрибута onClick работает, только если вы установили инструменты: контекст.
Рисунок 2. Быстрое исправление для атрибута onClick работает, только если вы установили tools:context .

Вы можете указать имя класса активности, используя тот же префикс точки, что и в файле манифеста (за исключением полного имени пакета).

Например:

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

tools:itemCount

Предназначено для: <RecyclerView>

Используется: Редактор макетов Android Studio

Для данного RecyclerView этот атрибут указывает количество элементов, которые редактор макета должен отображать в окне предварительного просмотра .

Например: 

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

tools:layout

Предназначено для: <fragment>

Используется: Редактор макетов Android Studio

Этот атрибут объявляет, какой макет вы хотите, чтобы предварительный просмотр макета отображался внутри фрагмента, поскольку предварительный просмотр макета не может выполнить код действия, который обычно применяет макет.

Например: 

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

tools:listitem , tools:listheader , tools:listfooter

Предназначен для: <AdapterView> (и подклассов, таких как <ListView> ).

Используется: Редактор макетов Android Studio

Эти атрибуты определяют, какой макет отображать при предварительном просмотре макета для элементов списка, верхнего и нижнего колонтитула. Все поля данных в макете заполняются числовым содержимым, например «Элемент 1», чтобы элементы списка не повторялись.

Например: 

<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

Предназначено для: любого корневого <View> в макете, на который ссылается <include>

Используется: Редактор макетов Android Studio

Этот атрибут позволяет указать макет, который использует этот макет, с помощью <include> , поэтому вы можете просмотреть и отредактировать этот файл так, как он выглядит, будучи встроенным в родительский макет.

Например:

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

Теперь предварительный просмотр макета показывает этот макет TextView так, как он выглядит внутри макета activity_main .

tools:menu

Назначение: Любой корень <View>

Используется: Редактор макетов Android Studio

Этот атрибут определяет, какое меню отображается в предварительном просмотре макета на панели приложения . Значением является один или несколько идентификаторов меню, разделенных запятыми, без @menu/ или любого подобного префикса идентификатора и без расширения .xml .

Например: 

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

Предназначено для: <NumberPicker>

Используется: Редактор макетов Android Studio

Эти атрибуты задают минимальные и максимальные значения для представления NumberPicker .

Например: 

<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

Предназначено для: <DrawerLayout>

Используется: Редактор макетов Android Studio

Этот атрибут позволяет открыть DrawerLayout в предварительном просмотре.

Вы также можете изменить способ визуализации макета в редакторе макетов, передав одно из следующих значений:

Таблица 1. Значения для изменения способа отображения DrawerLayout в редакторе макетов

Постоянный Ценить Описание
end 800005 Переместить объект в конец контейнера, не меняя его размера.
left 3 Сдвиньте объект слева от его контейнера, не меняя его размера.
right 5 Сдвинуть объект вправо от его контейнера, не меняя его размера.
start 800003 Переместить объект в начало контейнера, не меняя его размера.

Например: 

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

Ресурсы "@tools:sample/*"

Предназначено для: любого представления, поддерживающего текст или изображения пользовательского интерфейса.

Используется: Редактор макетов Android Studio

Этот атрибут позволяет вставлять в представление данные-заполнители или изображения. Например, чтобы проверить, как ваш макет ведет себя с текстом, прежде чем вы окончательно доработаете текст пользовательского интерфейса для вашего приложения, вы можете использовать текст-заполнитель следующим образом:

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

В следующей таблице описаны типы данных-заполнителей, которые можно вставлять в макеты:

Таблица 2. Данные-заполнители для макетов

Значение атрибута Описание данных-заполнителей
@tools:sample/full_names Полные имена, генерируемые случайным образом из комбинации @tools:sample/first_names и @tools:sample/last_names
@tools:sample/first_names Распространенные имена
@tools:sample/last_names Распространенные фамилии
@tools:sample/cities Названия городов со всего мира
@tools:sample/us_zipcodes Случайно сгенерированные почтовые индексы США.
@tools:sample/us_phones Случайно сгенерированные номера телефонов в следующем формате: (800) 555-xxxx
@tools:sample/lorem Текст заполнителя на латинице
@tools:sample/date/day_of_week Случайные даты и время для указанного формата
@tools:sample/date/ddmmyy
@tools:sample/date/mmddyy
@tools:sample/date/hhmm
@tools:sample/date/hhmmss
@tools:sample/avatars Векторные рисунки, которые можно использовать в качестве аватаров профиля.
@tools:sample/backgrounds/scenic Изображения, которые можно использовать в качестве фона

Атрибуты сокращения ресурсов

Следующие атрибуты позволяют включить строгую проверку ссылок и объявить, следует ли сохранять или удалять определенные ресурсы при использовании сжатия ресурсов .

Чтобы включить сжатие ресурсов, установите для свойства shrinkResources значение true в файле build.gradle , а также minifyEnabled для сжатия кода.

Например:

классный 

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

Котлин 

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

tools:shrinkMode

Предназначено для: <resources>

Используется: Инструменты создания с возможностью сокращения ресурсов.

Этот атрибут позволяет указать, должны ли инструменты сборки использовать следующее:

  • Безопасный режим: сохраните все ресурсы, которые явно цитируются и на которые можно ссылаться динамически с помощью вызова Resources.getIdentifier() .
  • Строгий режим: сохраняйте только те ресурсы, которые явно цитируются в коде или других ресурсах.

По умолчанию используется безопасный режим ( shrinkMode="safe" ). Чтобы вместо этого использовать строгий режим, добавьте shrinkMode="strict" к тегу <resources> , как показано здесь:

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

Когда вы включаете строгий режим, вам может потребоваться использовать tools:keep чтобы сохранить ресурсы, которые были удалены, но которые вам действительно нужны, и использовать tools:discard чтобы явно удалить еще больше ресурсов.

Дополнительные сведения см. в разделе Сокращение ресурсов .

tools:keep

Предназначено для: <resources>

Используется: Инструменты создания с возможностью сокращения ресурсов.

При использовании сжатия ресурсов для удаления неиспользуемых ресурсов этот атрибут позволяет указать ресурсы, которые следует сохранить, обычно потому, что во время выполнения на них ссылаются косвенно, например, путем передачи динамически генерируемого имени ресурса в Resources.getIdentifier() .

Для использования создайте XML-файл в каталоге ресурсов (например, res/raw/keep.xml ) с тегом <resources> и укажите каждый ресурс, который нужно сохранить, в tools:keep в виде списка, разделенного запятыми. В качестве подстановочного знака можно использовать символ звездочки.

Например:

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

Дополнительные сведения см. в разделе Сокращение ресурсов .

tools:discard

Предназначено для: <resources>

Используется: Инструменты создания с возможностью сокращения ресурсов.

При использовании сжатия ресурсов для удаления неиспользуемых ресурсов этот атрибут позволяет указать ресурсы, которые вы хотите удалить вручную, обычно потому, что на ресурс есть ссылка, но таким образом, который не влияет на ваше приложение, или потому, что плагин Gradle неправильно определил, что на ресурс есть ссылка. .

Для использования создайте XML-файл в каталоге ресурсов (например, res/raw/keep.xml ) с тегом <resources> и укажите каждый ресурс, который нужно отбросить, в tools:discard в виде списка, разделенного запятыми. В качестве подстановочного знака можно использовать символ звездочки.

Например:

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

Дополнительные сведения см. в разделе Сокращение ресурсов .