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 布局编辑器
您可通过将 tools:
前缀(而非 android:
)与 Android 框架中的任意 <View>
属性搭配使用,在布局预览中插入示例数据。此属性在以下情况下很有用:属性的值在运行时之前不会填充,但您希望在布局预览中看到效果。
例如,如果在运行时设置 android:text
属性值,或者您希望在布局中看到默认值以外的值,则可添加 tools:text
以指定一些仅在布局预览中显示的文本。
![tools:text 属性用于将“Google Voice”设为在布局预览中显示的值](https://developer.android.google.cn/static/studio/images/write/tools-attribute-text_2x.png?authuser=6&hl=ro)
tools:text
属性用于将“Google Voice”设为在布局预览中显示的值。您可以同时添加 android:
命名空间属性(会在运行时用到)和匹配的 tools:
属性(会替换仅在布局预览中显示的运行时属性)。
您还可以使用 tools:
属性来撤消仅为布局预览指定的属性设置。例如,如果您拥有的 FrameLayout
包含 2 个子元素,但您希望在布局预览中仅看到一个子元素,则可将其中一个子元素设为在布局预览中不可见,如下所示:
<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" />
在 Design 视图中使用布局编辑器时,您可通过 Properties 窗口修改部分设计时视图属性。每个设计时属性的属性名称旁边都会显示扳手图标 ,以便与同名的真实属性区分开来。
tools:context
适用于:任何根 <View>
使用者:lint、Android Studio 布局编辑器
此属性用于声明相应布局默认与哪个 activity 关联。这会在编辑器或布局预览中启用具有以下特征的功能:需要了解相应 activity,例如预览中的布局主题是什么以及在何处插入通过快速修复生成的 onClick
处理程序,如图 2 所示。
![只有在您设置了 tools:context 的情况下,onClick 属性的快速修复功能才会起作用](https://developer.android.google.cn/static/studio/images/write/tools-attribute-context_2x.png?authuser=6&hl=ro)
tools:context
的情况下,onClick
属性的快速修复功能才会起作用。您可以使用清单文件所用的同一点前缀指定 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>
对于给定的
RecyclerView
,此属性会指定布局编辑器应该在 Preview 窗口中呈现的内容的数量。
例如:
<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
适用于:<ListView>
(以及 <AdapterView>
等子类)
使用者: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
的值
常量 | 值 | 说明 |
---|---|---|
end | 800005 | 将对象推送到其容器的末尾,不更改其大小。 |
left | 3 | 将对象推送到其容器的左侧,不更改其大小。 |
right | 5 | 将对象推送到其容器的右侧,不更改其大小。 |
start | 800003 | 将对象推送到其容器的开头,不更改其大小。 |
例如:
<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/*"
资源
适用于:支持界面文本或图片的任何视图
通过此属性,您可将占位符数据或图片注入到视图中。 例如,如果您想在未最终确定应用界面文本的情况下测试布局在采用文本时的行为,则可以使用占位符文本,如下所示:
<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
属性(若涉及代码缩减,则还包括 minifyEnabled
)设为 true
。
例如:
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()
。
若要使用,请先在资源目录中(例如在 res/raw/keep.xml
处)创建一个具有 <resources>
标记的 XML 文件,并以英文逗号分隔列表的形式指定要在 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
处)创建一个具有 <resources>
标记的 XML 文件,并以英文逗号分隔列表的形式指定要在 tools:discard
属性中舍弃的各项资源。您可以使用星号字符作为通配符。
例如:
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
tools:discard="@layout/unused_1" />
如需了解详情,请参阅缩减资源。