工具属性参考

Android Studio 支持 tools 命名空间中的各种 XML 属性,这些属性使设计时功能(例如在片段中显示哪个布局)或编译时行为(例如要应用于 XML 资源的哪个缩减模式)成为可能。构建应用程序时,构建工具会删除这些属性,因此不会影响 APK 大小或运行时行为。

要使用这些属性,请将 tools 命名空间添加到要使用这些属性的每个 XML 文件的根元素,如下所示

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

错误处理属性

以下属性有助于抑制 lint 警告消息

tools:ignore

目标:任何元素

使用:Lint

此属性接受要忽略的 lint 问题 ID 的逗号分隔列表,这些问题 ID 是您希望工具在该元素或其任何后代上忽略的。

例如,您可以告诉工具忽略 MissingTranslation 错误

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

tools:targetApi

目标:任何元素

使用:Lint

此属性的工作方式与 Java 代码中的 @TargetApi 注释相同。它允许您指定支持该元素的 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 来仅为布局预览指定一些文本。

The tools:text attribute sets Google Voice as the value for the layout
      preview
图 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"  />

在设计视图中使用 布局编辑器 时,**属性** 窗口允许您编辑一些设计时视图属性。每个设计时属性旁边都有一个扳手图标 The Wrench icon,以区别于同名实际属性。

tools:context

预期用途: 任何根 <View>

使用工具: Lint、Android Studio 布局编辑器

此属性声明默认情况下此布局与哪个活动关联。这将启用编辑器或布局预览中的功能,这些功能需要了解活动,例如预览中布局主题是什么以及从快速修复生成的 onClick 处理程序在何处插入,如图 2 所示。

Quickfix
    for the onClick attribute works only if you've set tools:context
图 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:listitemtools:listheadertools: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

预期用途: 布局中任何由 <include> 引用的根 <View>

使用工具: 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 布局编辑器

此属性指定布局预览在 应用栏 中显示哪个菜单。该值是一个或多个菜单 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:minValuetools: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 的值

常量描述
end800005将对象推送到其容器的末尾,不改变其大小。
left3将对象推送到其容器的左侧,不改变其大小。
right5将对象推送到其容器的右侧,不改变其大小。
start800003将对象推送到其容器的开头,不改变其大小。

例如

<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/*" 资源

预期用途: 任何支持 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" />

下表描述了您可以注入布局中的占位符数据类型

表 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 您可以用作背景的图像

资源缩减属性

以下属性允许您启用严格的引用检查,并声明在使用 资源缩减 时保留或丢弃某些资源。

要启用资源缩减,请在您的 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") {
            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" />

有关更多信息,请参阅 缩减您的资源