Android XML 中 tools 命名空间的作用

2017-02-12 2017-02-12 约 3000 字预计阅读 6 分钟

译自 Google Android Studio 用户指南 Tools Attributes Reference

Android Studio 支持 tools 命名空间中的各种 XML 属性，这些属性支持仅设计时使用的功能（例如哪些布局显示在片段中）或编译时行为（例如应用对于 XML 资源的优化模式）。构建应用程序时，构建工具会删除这些属性，不会影响 APK 大小或运行时的行为。要使用这些属性，请将工具命名空间添加到要使用它们的每个 XML 文件的根元素，如下所示：

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

错误处理属性

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

`tools:ignore`

适用于：任何元素使用者：Lint 此属性为用逗号分隔的 lint 问题 ID 列表，可以使 lint 忽略次元素及其子元素标记的问题。例如，您可以告诉工具忽略 MissingTranslation 错误：

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

`tools:targetApi`

适用于：任何元素使用者：Lint 此属性的工作原理与 Java 代码中的 @TargetApi 注解相同：它允许您指定此元素的适用 API 级别（使用整数或代号）。这个属性表示您相信这个元素及其子元素将只使用指定或更高的 API 级别。这将阻止 lint 警告您该元素或其属性在指定的 minSdkVersion 的 API 级别不可用。您可以如下所示地使用它，因为 GridLayout 仅在 API 级别不低于 14 的系统可用，而您也知道此布局不用于任何更低的版本：

1
2
3
<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 文件（默认字符串文件），以指示用于默认字符串的语言是西班牙语而不是英语：

1
2
<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 仅为布局预览指定一些文本。 {% img https://developer.android.google.cn/studio/images/write/tools-attribute-text_2x.png “图1. tools:text 属性设置预览界面的值为 Google Voice” %} 您可以同时添加 android: 属性（在运行时生效）和对应的 tools: 属性（仅覆盖预览中的相应运行时属性）。您还可以用 tools: 属性来仅为预览取消特定的属性。例如，如果您有一个具有两个子项的 FrameLayout，但是您希望在布局预览中只看到一个子项，则可以在布局预览中将其中一个子项设置为不可见，如下所示：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<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"  />

在使用布局编辑器设计视图中时，“属性”窗口也允许您编辑某些仅设计时生效的视图属性。每个仅设计时生效的属性都用属性名称旁边的扳手图标

https://developer.android.google.cn/studio/images/buttons/layout-tools-attr.png

指示，以将其与同名的实际属性区分开。

`tools:context`

适用于：任何根 <View> 元素使用者：Lint，Android Studio 布局编辑器此属性声明此布局默认与哪个活动相关联。这激活了编辑器或布局预览中的一些功能，这些功能需要知悉活动的具体信息，例如在预览界面应该显示什么主题，以及在通过 quickfix（图2）创建方法时，插入 onClick 处理程序的位置。 {% img https://developer.android.google.cn/studio/images/write/tools-attribute-context_2x.png “图2. onClick属性相关的 Quickfix 窗口只有在你设置了 tools:context 的时候才有效” %} 您可以使用与清单文件中相同的点前缀（不包括完整的软件包名称）指定活动类名称。比如：

1
2
3
4
<android.support.constraint.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    tools:context=".MainActivity" >

提示：您也可以从布局编辑器工具栏中选择预览界面的主题。

`tools:layout`

适用于：<fragment> 使用者：Android Studio 布局编辑器此属性声明您希望预览时在片段内使用的布局（因为预览时无法执行活动代码以显示应用布局）。例如：

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

`tools:listitem`、`tools:listheader` 和 `tools:listfooter`

适用于：<AdapterView>（以及子类如 <ListView>）使用者：Android Studio 布局编辑器这些属性指定要在预览界面中显示的列表项目、页眉和页脚的布局。布局中的任何数据字段都用数字内容（例如“Item 1”）的形式填充，以保证列表项不重复。例如：

1
2
3
4
5
6
7
8
<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:listitem="@layout/sample_list_footer" />

注意：这些属性不适用于 Android Studio 2.2 中的 ListView，但在 2.3（issue 215172）中已修复。

`tools:showIn`

适用于：<include> 所引用的布局中的根 <View> 使用者：Android Studio 布局编辑器此属性允许您指向包含此布局作为的父布局，因此您可以预览（和编辑）显示父布局中嵌入的文件。例如：

1
2
3
4
5
6
<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 扩展名）。例如：

1
2
3
4
5
6
7
<?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" />

资源压缩属性

以下属性允许您启用严格引用检查，并声明在使用资源压缩时是保留还是丢弃某些资源。要启用资源压缩，请在 build.gradle 文件中（同样设置 minifyEnabled 属性允许代码压缩）将 shrinkResources 属性设置为 true。例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
android {
    ...
    buildTypes {
        release {
            shrinkResources true
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'),
                    'proguard-rules.pro'
        }
    }
}

`tools:shrinkMode`

适用于：<resources> 使用者：具有资源压缩功能的构建工具此属性允许您使用构建工具是否应启用“安全模式”（尽量安全地进行构建工作，并保留所有明确引用的资源，以及可能通过调用 Resources.getIdentifier() 来动态引用的资源）或“严格模式”（仅保留在代码或其他资源中明确引用的资源）。默认是使用安全模式（shrinkMode="safe"）。要改为使用严格模式，请将 shrinkMode="strict" 添加到 <resources> 标签，如下所示：

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

当您启用严格模式时，您可能需要使用 tools:keep 来保留已删除但实际需要的资源，并使用 tools:discard 以显式删除更多资源。要了解更多详细信息，请参阅Shrink your resources。

`tools:keep`

适用于：<resources> 使用者：具有资源压缩功能的构建工具使用资源压缩功能删除未使用的资源时，此属性允许您指定要保留的资源（通常是因为它们被在运行时以间接方式引用，例如将动态生成的资源名称传递给 Resources.getIdentifier()）。要使用这个属性，请在资源目录（例如，在 res/raw/keep.xml）中使用 <resources> 标记创建 XML 文件，并将 tools:keep 属性指定为一个用逗号分隔的列表。您可以使用星号字符作为通配符。例如：

1
2
3
<?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" />

要了解更多详细信息，请参阅Shrink your resources。

`tools:discard`

适用于：<resources> 使用者：具有资源压缩功能的构建工具使用资源压缩功能删除未使用的资源时，此属性允许您手动指定要丢弃的资源（通常是被引用了却不影响应用运行的资源，或者因为 Gradle 插件不正确的推断出而引用的资源）。要使用这个属性，请在资源目录（例如，在 res/raw/keep.xml）中使用 <resources> 标记创建 XML 文件，并将 tools:discard 属性指定为一个用逗号分隔的列表。您可以使用星号字符作为通配符。例如：

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

要了解更多详细信息，请参阅Shrink your resources。

目录

Android XML 中 tools 命名空间的作用

错误处理属性

tools:ignore

tools:targetApi

tools:locale

仅设计时生效的视图属性

tools: 覆盖 android:

tools:context

tools:layout

tools:listitem、tools:listheader 和 tools:listfooter

tools:showIn

tools:menu