工具属性参考

Android Studio 支持 tools 命名空间中的各种 XML 属性，这些属性可启用设计时功能（例如在 fragment 中显示哪个布局）或编译时行为（例如对 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 列表，工具将忽略此元素或其任何后代中的这些问题。

例如，您可以告知工具忽略 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 布局编辑器

您可以通过在 Android 框架的任何 <View> 属性中使用 tools: 前缀而不是 android:，在布局预览中插入示例数据。当属性的值直到运行时才填充，并且您想在布局预览中查看效果时，这非常有用。

例如，如果 android:text 属性值在运行时设置，或者您想查看与默认值不同的布局，您可以添加 tools:text 来仅为布局预览指定一些文本。

您可以同时添加在运行时使用的 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"  />

在设计视图中使用布局编辑器时，Properties (属性) 窗口允许您编辑一些设计时视图属性。每个设计时属性旁边都有一个扳手图标 ，以将其与同名的真实属性区分开来。

tools:context

适用范围：任意根 <View>

由以下工具使用：Lint、Android Studio 布局编辑器

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

您可以使用与清单文件相同的点前缀来指定 Activity 类名（不包括完整包名）。

例如：

<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 内部绘制哪个布局，因为布局预览无法执行通常应用布局的 activity 代码。

例如：

<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 布局编辑器

此属性允许您指向使用 <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: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 方式的值

例如：

<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. 布局占位符数据

资源缩减属性

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

要启用资源缩减，请在您的 build.gradle 文件中，将 shrinkResources 属性设置为 true，同时启用 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")。要改用严格模式，请在 <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()。

要使用此功能，请在您的资源目录（例如 res/raw/keep.xml）中创建一个 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 插件错误地推断该资源已被引用。

要使用此功能，请在您的资源目录（例如 res/raw/keep.xml）中创建一个 XML 文件，其中包含 <resources> 标签，并在 tools:discard 属性中指定要丢弃的每个资源，作为逗号分隔的列表。您可以使用星号字符作为通配符。

例如：

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

有关详细信息，请参阅缩减资源。