Dokumentacja atrybutów narzędzi

Android Studio obsługuje różne atrybuty XML w przestrzeni nazw tools, które umożliwiają korzystanie z funkcji związanych z czasem projektowania, np. układ wyświetlany we fragmencie lub zachowania w czasie kompilacji, np. wybór trybu zmniejszania rozmiaru zasobów XML. Gdy tworzysz aplikację, narzędzia do kompilacji usuwają te atrybuty, tak aby nie miało to wpływu na rozmiar pliku APK ani działanie w czasie działania.

Aby użyć tych atrybutów, dodaj przestrzeń nazw tools do elementu głównego każdego pliku XML, w którym chcesz ich użyć, jak na przykładzie poniżej:

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

Atrybuty obsługi błędów

Te atrybuty pomagają pominąć ostrzeżenia o lintowaniu:

tools:ignore

Przeznaczenie: dowolny element

Używane przez: Lint

Ten atrybut może zawierać rozdzieloną przecinkami listę identyfikatorów problemów z lintami, które mają być ignorowane przez narzędzia w tym elemencie lub jego elementach podrzędnych.

Możesz na przykład skonfigurować ignorowanie przez narzędzia błędu MissingTranslation:

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

tools:targetApi

Przeznaczenie: dowolny element

Używane przez: Lint

Ten atrybut działa tak samo jak adnotacja @TargetApi w kodzie Java. Pozwala on określić poziom interfejsu API (w postaci liczby całkowitej lub nazwy kodu), który obsługuje ten element.

Informuje to narzędzia, które Twoim zdaniem oraz elementy podrzędne są używane tylko na określonym poziomie interfejsu API lub wyższym. Dzięki temu lint nie ostrzega Cię, jeśli dany element lub jego atrybuty są niedostępne na poziomie interfejsu API, który określisz jako minSdkVersion.

Możesz na przykład użyć tego atrybutu, ponieważ atrybut GridLayout jest dostępny tylko na poziomie API 14 i wyższych, ale wiesz, że ten układ nie jest używany w kodzie w niższych wersjach:

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

Zalecamy jednak korzystanie z GridLayout z biblioteki pomocy.

tools:locale

Przeznaczenie: <resources>

Używany przez: Lint, edytor Android Studio

Informuje to narzędzia, jaki jest domyślny język lub region dla zasobów w danym elemencie <resources>, dzięki czemu unikniesz ostrzeżeń ze sprawdzania pisowni. W przeciwnym razie narzędzie zakłada, że używany jest język angielski.

Wartość musi być prawidłowym kwalifikatorem języka.

Możesz np. dodać ten fragment do domyślnego pliku values/strings.xml, aby wskazać, że domyślnym językiem w domyślnych ciągach znaków jest hiszpański, a nie angielski:

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

Atrybuty widoku danych w czasie projektowania

Podane niżej atrybuty określają cechy układu, które są widoczne tylko w podglądzie układu w Android Studio.

tools: zamiast android:

Przeznaczenie: <View>

Używane przez: edytor układu Android Studio

Na podglądzie układu możesz wstawić przykładowe dane, używając prefiksu tools: zamiast android: z dowolnym atrybutem <View> ze platformy Androida. Jest to przydatne, gdy wartość atrybutu nie jest wypełniona do czasu działania, a chcesz zobaczyć efekt w podglądzie układu.

Jeśli na przykład wartość atrybutu android:text jest ustawiona w czasie działania lub chcesz zobaczyć układ z inną wartością niż domyślna, możesz dodać element tools:text, aby określić tekst tylko na potrzeby podglądu układu.

Możesz dodać zarówno atrybut przestrzeni nazw android:, który jest używany w czasie działania, jak i pasujący atrybut tools:, który zastępuje atrybut środowiska wykonawczego tylko w podglądzie układu.

Możesz też użyć atrybutu tools:, aby cofnąć ustawienie atrybutu tylko dla podglądu układu. Jeśli na przykład masz element FrameLayout z dwoma elementami podrzędnymi, ale chcesz, aby w podglądzie układu było tylko jedno z nich, możesz ustawić jeden z nich jako niewidoczny w podglądzie układu, jak pokazano tutaj:

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

Gdy korzystasz z Edytora układu w widoku projektu, w oknie Właściwości możesz edytować niektóre atrybuty widoku w czasie projektowania. Obok każdego atrybutu związanego z czasem projektowania jest widoczna ikona klucza . Pozwala to odróżnić go od rzeczywistego atrybutu o tej samej nazwie.

tools:context

Przeznaczenie: dowolny poziom główny <View>

Używane przez: Lint, edytora układu Android Studio

Ten atrybut deklaruje aktywność, z którą ten układ jest domyślnie powiązany. Umożliwia to włączenie w edytorze lub podglądzie układu funkcji, które wymagają znajomości działania, np. jaki jest motyw układu na podglądzie i gdzie wstawić moduły obsługi onClick wygenerowane z szybkiej poprawki, jak widać na ilustracji 2.

Nazwę klasy aktywności możesz podać za pomocą tego samego prefiksu kropki co w pliku manifestu (bez pełnej nazwy pakietu).

Na przykład:

<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

Przeznaczenie: <RecyclerView>

Używane przez: edytora układu Android Studio

W przypadku danego elementu RecyclerView ten atrybut określa liczbę elementów, które edytor układu powinien wyrenderować w oknie Podgląd.

Na przykład:

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

tools:layout

Przeznaczenie: <fragment>

Używane przez: edytor układu Android Studio

Ten atrybut deklaruje układ, który podgląd układu ma narysować wewnątrz fragmentu, ponieważ podgląd układu nie może wykonać kodu aktywności, który zwykle stosuje układ.

Na przykład:

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

tools:listitem, tools:listheader, tools:listfooter

Przeznaczenie dla: <AdapterView> (i podklasy takie jak <ListView>)

Używane przez: edytor układu Android Studio

Te atrybuty określają, jaki układ ma być wyświetlany na podglądzie układu elementów, nagłówka i stopki listy. Wszystkie pola danych w układzie są wypełniane danymi liczbowymi, np. „Element 1”, dzięki czemu elementy listy się nie powtarzają.

Na przykład:

<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

Przeznaczenie: dowolny główny element <View> w układzie, do którego odwołuje się <include>

Używane przez: edytor układu Android Studio

Ten atrybut pozwala wskazać układ, który korzysta z tego układu, używając pola <include>. Dzięki temu możesz wyświetlić podgląd pliku i edytować go w takiej postaci, w jakiej jest umieszczony w układzie nadrzędnym.

Na przykład:

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

Teraz na podglądzie układu widoczny będzie układ TextView w takiej postaci, w jakiej wygląda on w układzie activity_main.

tools:menu

Przeznaczenie: dowolny poziom główny <View>

Używane przez: edytor układu Android Studio

Ten atrybut określa menu, które ma być wyświetlane na pasku aplikacji w podglądzie układu. Wartość to co najmniej 1 identyfikator menu rozdzielonych przecinkami, bez prefiksu @menu/, żadnego takiego identyfikatora i bez rozszerzenia .xml.

Na przykład:

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

Przeznaczenie: <NumberPicker>

Używane przez: edytor układu Android Studio

Te atrybuty określają minimalne i maksymalne wartości w widoku NumberPicker.

Na przykład:

<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

Przeznaczenie: <DrawerLayout>

Używane przez: edytor układu Android Studio

Ten atrybut umożliwia otwieranie DrawerLayout na podglądzie.

Możesz też zmienić sposób renderowania układu przez edytor układu, przesyłając jedną z tych wartości:

Tabela 1. wartości umożliwiające zmianę sposobu, jak edytor układu renderuje element DrawerLayout

Na przykład:

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

Przeznaczenie: każdy widok, który obsługuje tekst lub obrazy interfejsu.

Używane przez: edytora układu Android Studio

Ten atrybut umożliwia wstawianie w widoku danych lub obrazów zastępczych. Aby np. sprawdzić, jak układ zachowuje się z tekstem przed ostatecznego, sformatowanego interfejsu aplikacji, możesz użyć tekstu zastępczego w ten sposób:

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

W tabeli poniżej opisujemy typy danych zastępczych, które możesz wstrzykiwać do swoich układów:

Tabela 2. Dane zastępcze układów

Atrybuty zmniejszania zasobów

Poniższe atrybuty umożliwiają włączenie ścisłej kontroli odwołań i zadeklarowanie, czy podczas zmniejszania zasobów chcesz zachować, czy odrzucić określone zasoby.

Aby włączyć zmniejszanie zasobów, ustaw właściwość shrinkResources na true w pliku build.gradle oraz na minifyEnabled, aby zmniejszyć kod.

Na przykład:

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

Przeznaczenie: <resources>

Używane przez: tworzenie narzędzi z ograniczaniem zasobów

Ten atrybut pozwala określić, czy narzędzia do kompilacji powinny korzystać z tych elementów:

• Tryb awaryjny: zachowaj wszystkie zasoby, które są jawnie cytowane, i do których może się dynamicznie odwoływać za pomocą wywołania Resources.getIdentifier().
• Tryb ścisły: zachowujesz tylko zasoby, które są jawnie cytowane w kodzie lub innych zasobach.

Domyślnie jest używany tryb awaryjny (shrinkMode="safe"). Aby zamiast tego użyć trybu ścisłego, dodaj parametr shrinkMode="strict" do tagu <resources> w ten sposób:

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

Po włączeniu trybu ścisłego konieczne może być użycie tools:keep, aby zachować usunięte zasoby, które są faktycznie potrzebne, oraz użycie tools:discard do jawnego usunięcia jeszcze większej liczby zasobów.

Więcej informacji znajdziesz w artykule o zmniejszaniu zasobów.

tools:keep

Przeznaczenie: <resources>

Używane przez: tworzenie narzędzi z ograniczaniem zasobów

Jeśli używasz zmniejszania zasobów w celu usuwania nieużywanych zasobów, ten atrybut pozwala określić zasoby do zachowania. Zwykle dzieje się tak w sposób pośredni w czasie działania, na przykład przez przekazanie dynamicznie generowanej nazwy zasobu do Resources.getIdentifier().

Aby go użyć, utwórz plik XML w katalogu zasobów (np. res/raw/keep.xml) z tagiem <resources> i w atrybucie tools:keep wskaż każdy zasób do zachowania w postaci listy rozdzielonej przecinkami. Możesz użyć symbolu z gwiazdką jako symbolu wieloznacznego.

Na przykład:

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

Więcej informacji znajdziesz w artykule o zmniejszaniu zasobów.

tools:discard

Przeznaczenie: <resources>

Używane przez: tworzenie narzędzi z ograniczaniem zasobów

Jeśli używasz zmniejszania zasobów do usuwania nieużywanych zasobów, ten atrybut pozwala określić zasoby, które chcesz ręcznie odrzucić. Zwykle jest to związane z odwołaniem się do zasobu, ale w sposób, który nie ma wpływu na Twoją aplikację, lub dlatego, że wtyczka Gradle błędnie wywnioskowała, że zasób jest wskazywany przez odwołanie.

Aby go użyć, utwórz plik XML w katalogu zasobów (np. res/raw/keep.xml) z tagiem <resources> i w atrybucie tools:discard wskaż każdy zasób do odrzucenia w postaci listy rozdzielonej przecinkami. Możesz użyć symbolu z gwiazdką jako symbolu wieloznacznego.

Na przykład:

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

Więcej informacji znajdziesz w artykule o zmniejszaniu zasobów.