工具屬性參考資料

Android Studio 支援在 tools 命名空間中運用各種 XML 屬性來啟用設計時間功能 (例如要在片段中顯示的版面配置) 或編譯時間行為 (例如要套用至 XML 資源的縮小模式類型)。在您建構應用程式時,建構工具會移除這些屬性,因此不會對 APK 大小或執行階段行為造成任何影響。

如要使用這些屬性,請在每個想要使用 XML 檔案的根元素中新增 tools 命名空間,如下所示:

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

處理屬性時發生錯誤

下列屬性有助於偵測 Lint 警告訊息。

tools:ignore

適用於:任何元素

使用這項屬性的工具:Lint

這項屬性接受以逗號分隔的 Lint 問題 ID 清單,也就是您希望工具忽略這個元素或其直系後代。

舉例來說,您可以指示工具忽略 MissingTranslation 錯誤:

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

tools:targetApi

適用於:任何元素

使用這項屬性的工具:Lint

這個屬性的運作方式與 Java 程式碼中的 @TargetApi 註解相同:可讓您指定支援這個元素的 API 級別 (可以是整數或程式碼名稱)。

這表示您認為這個元素 (以及任何子項) 只會在指定的 API 級別以上使用。如果在您指定為 minSdkVersion 的 API 級別上無法使用該元素或其屬性,則不會再收到 Lint 的警告。

舉例來說,由於 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:,並搭配 Android 架構中的任何 <View> 屬性。 當您的執行階段尚未填入屬性值時,但您仍想在版面配置預覽中預先查看效果,這項功能就非常實用。

舉例來說,如果您在執行階段設定 android:text 屬性值,或是想查看和預設不同的版面配置數值,則可以加上 tools:text 來指定僅供版面配置預覽的的某些文字。

圖 1. tools:text 屬性會將「Google Voice」設為版面配置預覽的值

您可以新增 android: 命名空間屬性 (在執行階段使用) 和相符的 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 版面配置編輯器

根據預設,這個屬性會宣告與這個版面配置相關聯的活動。這會在編輯器或版面配置預覽中啟用需要活動知識的功能,例如版面配置主題應在預覽畫面中的位置,以及進行 Quickfix 時插入這些 onClick 處理常式的位置 (圖 2)。

圖 2. 您必須先設定 tools:context,才能使用 onClick 的 Quickfix

您可以使用與資訊清單檔案相同的點前置字元 (不含完整套件名稱) 來指定活動類別名稱。例如:

<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,這個屬性會指定在「預覽」視窗中應轉譯的版面配置編輯器項目數量。

例如:

<android.support.v7.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 版面配置編輯器

這些屬性可指定在清單項目、標頭和頁尾的版面配置中顯示的版面配置類型。版面配置中的任何資料欄位都會填入數值項目 (例如「Item 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

適用於:版面配置中任何指 <include> 的根 <View>

使用這項屬性的工具:Android Studio 版面配置編輯器

這項屬性可讓您指向使用此版面配置做為加入的版面配置,因此您可以在出現嵌入父項版面配置時預覽 (和編輯) 這個檔案。

例如:

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

現在,版面配置預覽畫面會在出現於 activity_main 版面配置中時顯示此 TextView 版面配置。

tools:menu

適用於:任何根 <View>

使用這項屬性的工具:Android Studio 版面配置編輯器

這個屬性會指定版面配置預覽應在應用程式列中顯示的選單。這個值可以是一或多個選單 ID,並以逗號分隔 (不含任何 @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。您也可以透過傳遞下列其中一個值,修改版面配置編輯器的轉譯方式:

常數說明
結束800005將物件推送到容器的結尾,而不變更其大小。
左側3將物件推送到容器的左側,而不變更其大小。
右側5將物件推送到容器的右側,而不變更其大小。
開始800003將物件推送至容器的起點,而不變更其大小。

例如:

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

"@tools:sample/*" 資源

適用於:任何支援 UI 文字或圖片的檢視畫面。

使用這項屬性的工具:Android Studio 版面配置編輯器

這個屬性可讓您在檢視畫面中插入預留位置資料或圖片。 舉例來說,如果您想測試版面配置加入文字的行為方式,但尚未針對應用程式提供最終 UI 文字,則可使用預留位置文字如下:

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

下表說明可插入版面配置的預留位置資料類型。

屬性值預留位置資料的說明
@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 可做為背景的圖片。

資源縮減屬性

下列屬性可讓您在使用資源縮減時啟用嚴格的參考資料檢查,並宣告是否要保留或捨棄特定資源。

如要啟用資源縮減功能,請將 build.gradle 檔案中的 shrinkResources 屬性設為 true (以及用於程式碼縮減的 minifyEnabled)。例如:

Groovy

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

Kotlin

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

tools:shrinkMode

適用於:<resources>

使用這項屬性的工具:具有資源縮減機制的建構工具

這項屬性可讓您指定建構工具是否應使用「安全模式」(安全執行並保留已明確引用的所有資源,且「可能」會透過呼叫 Resources.getIdentifier() 進行動態參照) 或「嚴格模式」(只會保留程式碼或其他資源中明確引用的資源)。

預設為安全模式 (shrinkMode="safe")。如要改用嚴格模式,請在 <resources> 標記中加入 shrinkMode="strict",如下所示:

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

詳情請參閱「縮減資源」一節。