Справочник атрибутов инструментов (Представления)

Концепции и реализация Jetpack Compose

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

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

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

tools:targetApi

Предназначено для : любого элемента

Используется : Lint

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

Это сообщает инструментам, что вы считаете, что этот элемент и любые его дочерние элементы используются только на указанном уровне API или выше. Это предотвращает предупреждения линтера, если этот элемент или его атрибуты недоступны на уровне 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 из библиотеки поддержки.)

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

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

tools: вместо android:

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

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

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

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

Рисунок 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.

Рисунок 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/ или любого подобного префикса ID и без расширения .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	Изображения, которые можно использовать в качестве фона.