可绘制资源

可绘制资源是指可以绘制到屏幕上的图形的通用概念,您可以使用 getDrawable(int) 等 API 检索它,或使用 android:drawableandroid:icon 等属性将其应用于另一个 XML 资源。可绘制对象有以下几种类型:

位图文件
位图图形文件(PNG、WEBP、JPG 或 GIF)。创建 BitmapDrawable
Nine-patch 文件
一个带有可拉伸区域的 PNG 文件,用于让图像根据内容调整大小(.9.png)。创建 NinePatchDrawable
图层列表
一个管理其他可绘制对象数组的可绘制对象。这些可绘制对象按数组顺序绘制,因此索引最大的元素绘制在最上面。创建 LayerDrawable
状态列表
一个 XML 文件,用于引用不同状态的不同位图图形,例如,在轻触按钮时使用不同的图像。创建 StateListDrawable
级别列表
一个 XML 文件,用于定义一个可绘制对象,该对象管理多个备用可绘制对象,每个对象都分配有一个最大数值。创建 LevelListDrawable
过渡可绘制对象
一个 XML 文件,用于定义一个可以在两个可绘制资源之间交叉淡出的可绘制对象。创建 TransitionDrawable
内嵌可绘制对象
一个 XML 文件,用于定义一个可绘制对象,该对象将另一个可绘制对象内嵌指定距离。当视图需要一个小于视图实际边界的背景可绘制对象时,这很有用。
剪裁可绘制对象
一个 XML 文件,用于定义一个可绘制对象,该对象根据其当前级别值剪裁另一个可绘制对象。创建 ClipDrawable
缩放可绘制对象
一个 XML 文件,用于定义一个可绘制对象,该对象根据其当前级别值更改另一个可绘制对象的大小。创建 ScaleDrawable
形状可绘制对象.
一个 XML 文件,用于定义几何形状,包括颜色和渐变。创建 GradientDrawable

有关如何创建 AnimationDrawable 的信息,请参阅动画资源文档。

注意:颜色资源也可以在 XML 中用作可绘制对象。例如,在创建状态列表可绘制对象时,您可以为 android:drawable 属性引用颜色资源(android:drawable="@color/green")。

位图

位图图像。Android 支持以下格式的位图文件:PNG(首选)、WEBP(首选,需要 API 级别 17 或更高版本)、JPG(可接受)、GIF(不建议使用)。

您可以直接引用位图文件,使用文件名作为资源 ID,或在 XML 中创建别名资源 ID。

注意:在构建过程中,aapt 工具可能会通过无损图像压缩自动优化位图文件。例如,不需要超过 256 种颜色的真彩色 PNG 可能会转换为具有颜色调色板的 8 位 PNG。这会生成质量相同但所需内存更少的图像。

因此,请注意放置在此目录中的图像二进制文件在构建过程中可能会发生变化。如果您打算将图像作为位流读取以将其转换为位图,请将您的图像放在 res/raw/ 文件夹中,那里它们不会被优化。

位图文件

位图文件是 PNG、WEBP、JPG 或 GIF 文件。当您将这些文件保存到 res/drawable/ 目录时,Android 会为它们中的任何一个创建 Drawable 资源。

文件位置
res/drawable/filename.png.png.webp.jpg.gif
文件名即资源 ID
已编译资源数据类型
指向 BitmapDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
示例
将图像保存到 res/drawable/myimage.png 后,此布局 XML 会将图像应用于视图
<ImageView
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:src="@drawable/myimage" />

以下应用代码将图像检索为 Drawable

Kotlin

val drawable: Drawable? = ResourcesCompat.getDrawable(resources, R.drawable.myimage, null)

Java

Resources res = getResources();
Drawable drawable = ResourcesCompat.getDrawable(res, R.drawable.myimage, null);
另请参阅

XML 位图

XML 位图是 XML 中定义的一种资源,指向位图文件。其作用是原始位图文件的别名。XML 可以为位图指定附加属性,例如抖动和平铺。

注意:您可以将 <bitmap> 元素用作 <item> 元素的子元素。例如,在创建状态列表图层列表时,您可以从 <item> 元素中排除 android:drawable 属性,并在其内部嵌套一个 <bitmap> 来定义可绘制项。

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 BitmapDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<bitmap
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:src="@[package:]drawable/drawable_resource"
    android:antialias=["true" | "false"]
    android:dither=["true" | "false"]
    android:filter=["true" | "false"]
    android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" |
                      "fill_vertical" | "center_horizontal" | "fill_horizontal" |
                      "center" | "fill" | "clip_vertical" | "clip_horizontal"]
    android:mipMap=["true" | "false"]
    android:tileMode=["disabled" | "clamp" | "repeat" | "mirror"] />
元素
<bitmap>
必需。定义位图源及其属性。

属性

xmlns:android
字符串。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"。仅当 <bitmap> 是根元素时才需要。当 <bitmap> 嵌套在 <item> 内部时则不需要。
android:src
可绘制资源必需。对可绘制资源的引用。
android:antialias
布尔值。启用或禁用抗锯齿。
android:dither
布尔值。如果位图与屏幕没有相同的像素配置(例如 RGB 565 屏幕上的 ARGB 8888 位图),则启用或禁用位图的抖动。
android:filter
布尔值。启用或禁用位图过滤。当位图缩小或拉伸以使其外观平滑时,会使用过滤。
android:gravity
关键字。定义位图的重力。如果位图小于容器,则重力表示将可绘制对象放置在其容器中的位置。

必须是以下一个或多个常量值,以 | 分隔

描述
top 将对象放置在其容器的顶部,不改变其大小。
bottom 将对象放置在其容器的底部,不改变其大小。
left 将对象放置在其容器的左边缘,不改变其大小。
right 将对象放置在其容器的右边缘,不改变其大小。
center_vertical 将对象放置在其容器的垂直中心,不改变其大小。
fill_vertical 如果需要,增大对象的垂直尺寸,使其完全填充其容器。
center_horizontal 将对象放置在其容器的水平中心,不改变其大小。
fill_horizontal 如果需要,增大对象的水平尺寸,使其完全填充其容器。
center 将对象放置在其容器的垂直和水平轴的中心,不改变其大小。
fill 如果需要,增大对象的水平和垂直尺寸,使其完全填充其容器。这是默认值。
clip_vertical 可以设置的附加选项,用于将子项的顶部和/或底部边缘剪裁到其容器的边界。剪裁基于垂直重力:顶部重力剪裁底部边缘,底部重力剪裁顶部边缘,两者都不剪裁两个边缘。
clip_horizontal 可以设置的附加选项,用于将子项的左侧和/或右侧边缘剪裁到其容器的边界。剪裁基于水平重力:左侧重力剪裁右边缘,右侧重力剪裁左边缘,两者都不剪裁两个边缘。
android:mipMap
布尔值。启用或禁用 mipmap 提示。有关更多信息,请参阅 setHasMipMap()。默认值为 false。
android:tileMode
关键字。定义平铺模式。启用平铺模式时,位图会重复。启用平铺模式时,重力会被忽略。

必须是以下常量值之一

描述
disabled 不要平铺位图。这是默认值。
clamp 如果着色器绘制超出其原始边界,则复制边缘颜色
repeat 水平和垂直重复着色器的图像。
mirror 水平和垂直重复着色器的图像,交替镜像图像,使相邻图像始终无缝衔接。
示例
<?xml version="1.0" encoding="utf-8"?>
<bitmap xmlns:android="http://schemas.android.com/apk/res/android"
    android:src="@drawable/icon"
    android:tileMode="repeat" />
另请参阅

Nine-patch

一个 NinePatch 是一个 PNG 图像,您可以在其中定义可拉伸区域,当视图中的内容超出正常图像边界时,Android 会对其进行缩放。您通常将此类图像指定为至少有一个维度设置为 "wrap_content" 的视图的背景。

当视图增长以适应内容时,nine-patch 图像也会按比例缩放以匹配视图的大小。九宫格图像的一个用例是 Android 标准 Button 微件使用的背景,它必须拉伸以适应按钮内的文本(或图像)。

与普通位图一样,您可以直接引用九宫格文件,或从 XML 定义的资源中引用。

有关如何创建具有可拉伸区域的九宫格文件的完整讨论,请参阅创建可调整大小的位图(9 宫格文件)

Nine-patch 文件

文件位置
res/drawable/filename.9.png
文件名即资源 ID
已编译资源数据类型
指向 NinePatchDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
示例
将图像保存到 res/drawable/myninepatch.9.png 后,此布局 XML 会将九宫格应用于视图
<Button
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:background="@drawable/myninepatch" />
另请参阅

XML nine-patch

XML nine-patch 是 XML 中定义的一种资源,指向九宫格文件。XML 可以为图像指定抖动。

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 NinePatchDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<nine-patch
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:src="@[package:]drawable/drawable_resource"
    android:dither=["true" | "false"] />
元素
<nine-patch>
必需。定义 nine-patch 源及其属性。

属性

xmlns:android
字符串必需。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"
android:src
可绘制资源必需。对九宫格文件的引用。
android:dither
布尔值。如果位图与屏幕没有相同的像素配置(例如 RGB 565 屏幕上的 ARGB 8888 位图),则启用或禁用位图的抖动。
示例
<?xml version="1.0" encoding="utf-8"?>
<nine-patch xmlns:android="http://schemas.android.com/apk/res/android"
    android:src="@drawable/myninepatch"
    android:dither="false" />

图层列表

一个 LayerDrawable 是一个可绘制对象,它管理其他可绘制对象的数组。列表中的每个可绘制对象都按列表顺序绘制。列表中的最后一个可绘制对象绘制在最上面。

每个可绘制对象都由单个 <layer-list> 元素内的 <item> 元素表示。

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 LayerDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<layer-list
    xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:drawable="@[package:]drawable/drawable_resource"
        android:id="@[+][package:]id/resource_name"
        android:top="dimension"
        android:right="dimension"
        android:bottom="dimension"
        android:left="dimension" />
</layer-list>
元素
<layer-list>
必需。这必须是根元素。包含一个或多个 <item> 元素。

属性

xmlns:android
字符串必需。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"
<item>
定义一个要放置在图层可绘制对象中的可绘制对象,其位置由其属性定义。必须是 <layer-list> 元素的子元素。接受子 <bitmap> 元素。

属性

android:drawable
可绘制资源必需。对可绘制资源的引用。
android:id
资源 ID。此可绘制对象的唯一资源 ID。要为此项创建新的资源 ID,请使用以下形式:"@+id/name"。加号表示这是一个新创建的 ID。您可以使用此标识符通过 View.findViewById()Activity.findViewById() 检索和修改可绘制对象。
android:top
尺寸。顶部偏移量,作为尺寸值或尺寸资源
android:right
尺寸。右侧偏移量,作为尺寸值或尺寸资源
android:bottom
尺寸。底部偏移量,作为尺寸值或尺寸资源
android:left
尺寸。左侧偏移量,作为尺寸值或尺寸资源

默认情况下,所有可绘制项都会缩放以适应包含视图的大小。因此,将图像放置在图层列表中的不同位置可能会增加视图的大小,并且某些图像会进行适当的缩放。

为了避免缩放列表中的项目,请在 <item> 元素内部使用 <bitmap> 元素来指定可绘制对象,并将重力定义为不缩放的值,例如 "center"。例如,以下 <item> 定义了一个缩放以适应其容器视图的项目

<item android:drawable="@drawable/image" />

为避免缩放,以下示例使用具有居中重力的 <bitmap> 元素

<item>
  <bitmap android:src="@drawable/image"
          android:gravity="center" />
</item>
示例
XML 文件保存到 res/drawable/layers.xml
<?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item>
      <bitmap android:src="@drawable/android_red"
        android:gravity="center" />
    </item>
    <item android:top="10dp" android:left="10dp">
      <bitmap android:src="@drawable/android_green"
        android:gravity="center" />
    </item>
    <item android:top="20dp" android:left="20dp">
      <bitmap android:src="@drawable/android_blue"
        android:gravity="center" />
    </item>
</layer-list>

此示例使用嵌套的 <bitmap> 元素为每个项目定义可绘制资源,并设置 "center" 重力。这确保了由于偏移图像引起的尺寸调整,没有任何图像会缩放以适应容器的大小。

此布局 XML 将可绘制对象应用于视图

<ImageView
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:src="@drawable/layers" />

结果是一堆逐渐偏移的图像

另请参阅

状态列表

一个 StateListDrawable 是一个在 XML 中定义的可绘制对象,它根据对象的不同状态使用多个图像来表示相同的图形。例如,Button 微件的状态可以是已轻触、已聚焦或两者都不是;使用状态列表可绘制对象,您可以为每个状态提供不同的背景图像。

您在 XML 文件中描述状态列表。每个图形都由单个 <selector> 元素内部的 <item> 元素表示。每个 <item> 都使用各种属性来描述其用作可绘制对象图形的状态。

在每次状态更改期间,状态列表从上到下遍历,并使用第一个与当前状态匹配的项目。选择不是基于“最佳匹配”,而是基于满足状态最低条件的第一个项目。

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 StateListDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android"
    android:constantSize=["true" | "false"]
    android:dither=["true" | "false"]
    android:variablePadding=["true" | "false"] >
    <item
        android:drawable="@[package:]drawable/drawable_resource"
        android:state_pressed=["true" | "false"]
        android:state_focused=["true" | "false"]
        android:state_hovered=["true" | "false"]
        android:state_selected=["true" | "false"]
        android:state_checkable=["true" | "false"]
        android:state_checked=["true" | "false"]
        android:state_enabled=["true" | "false"]
        android:state_activated=["true" | "false"]
        android:state_window_focused=["true" | "false"] />
</selector>
元素
<selector>
必需。这必须是根元素。包含一个或多个 <item> 元素。

属性

xmlns:android
字符串必需。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"
android:constantSize
布尔值。如果可绘制对象报告的内部大小在状态更改时保持不变(大小是所有状态中的最大值),则为 true;如果大小根据当前状态而变化,则为 false。默认值为 false。
android:dither
布尔值。如果位图与屏幕没有相同的像素配置(例如 RGB 565 屏幕上的 ARGB 8888 位图),则为 true 以启用位图的抖动;为 false 以禁用抖动。默认值为 true。
android:variablePadding
布尔值。如果可绘制对象的内边距根据所选的当前状态而变化,则为 true;如果内边距必须保持不变,基于所有状态的最大内边距,则为 false。启用此功能要求您在状态更改时处理布局执行,这通常不受支持。默认值为 false。
<item>
定义一个在某些状态下使用的可绘制对象,由其属性描述。必须是 <selector> 元素的子元素。

属性

android:drawable
可绘制资源必需。对可绘制资源的引用。
android:state_pressed
布尔值。如果此项在对象被轻触时使用(例如轻触按钮时),则为 true;如果此项在默认的非轻触状态下使用,则为 false。
android:state_focused
布尔值。如果此项在对象具有输入焦点时使用(例如用户选择文本输入时),则为 true;如果此项在默认的非聚焦状态下使用,则为 false。
android:state_hovered
布尔值。如果此项在光标悬停在对象上时使用,则为 true;如果此项在默认的非悬停状态下使用,则为 false。通常,此可绘制对象可以与“聚焦”状态下使用的可绘制对象相同。

在 API 级别 14 中引入。

android:state_selected
布尔值。如果此项在对象是当前用户在使用方向控制导航时(例如使用 D-pad 导航列表时)的选择,则为 true;如果此项在对象未被选中时使用,则为 false。

android:state_focused 不足时使用选中状态,例如当列表视图具有焦点并且其中一个项目使用 D-pad 被选中时。

android:state_checkable
布尔值。如果此项在对象可选时使用,则为 true;如果此项在对象不可选时使用,则为 false。仅当对象可以在可选和不可选微件之间转换时才有用。
android:state_checked
布尔值。如果此项在对象被选中时使用,则为 true;如果此项在对象未被选中时使用,则为 false。
android:state_enabled
布尔值。如果此项在对象启用时使用(意味着能够接收触摸或点击事件),则为 true;如果此项在对象禁用时使用,则为 false。
android:state_activated
布尔值。如果此项在对象被激活为持久性选择时使用,例如在持久性导航视图中“突出显示”先前选择的列表项,则为 true;如果此项在对象未激活时使用,则为 false。

在 API 级别 11 中引入。

android:state_window_focused
布尔值。如果此项在应用窗口具有焦点时(即应用在前台时)使用,则为 true;如果此项在应用窗口不具有焦点时使用(例如,如果通知栏被拉下或出现对话框),则为 false。

注意:Android 会应用状态列表中与对象当前状态匹配的第一个项目。因此,如果列表中的第一个项目不包含前面任何状态属性,那么它每次都会被应用。这就是为什么您希望您的默认值始终放在最后,如下面的示例所示。

示例
XML 文件保存到 res/drawable/button.xml
<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:state_pressed="true"
          android:drawable="@drawable/button_pressed" /> <!-- pressed -->
    <item android:state_focused="true"
          android:drawable="@drawable/button_focused" /> <!-- focused -->
    <item android:state_hovered="true"
          android:drawable="@drawable/button_focused" /> <!-- hovered -->
    <item android:drawable="@drawable/button_normal" /> <!-- default -->
</selector>

此布局 XML 将状态列表可绘制对象应用于按钮

<Button
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:background="@drawable/button" />
另请参阅

级别列表

一个管理多个备用可绘制对象的对象,每个对象都分配有一个最大数值。使用 setLevel() 设置可绘制对象的级别值会加载级别列表中 android:maxLevel 值大于或等于传递给该方法的值的可绘制资源。

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 LevelListDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<level-list
    xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:drawable="@drawable/drawable_resource"
        android:maxLevel="integer"
        android:minLevel="integer" />
</level-list>
元素
<level-list>
必需。这必须是根元素。包含一个或多个 <item> 元素。

属性

xmlns:android
字符串必需。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"
<item>
定义在特定级别使用的可绘制对象。

属性

android:drawable
可绘制资源必需。对要内嵌的可绘制资源的引用。
android:maxLevel
整数。此项允许的最大级别。
android:minLevel
整数。此项允许的最小级别。
示例
<?xml version="1.0" encoding="utf-8"?>
<level-list xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:drawable="@drawable/status_off"
        android:maxLevel="0" />
    <item
        android:drawable="@drawable/status_on"
        android:maxLevel="1" />
</level-list>

一旦将其应用于 View,可以通过 setLevel()setImageLevel() 更改级别。

另请参阅

过渡可绘制对象

一个 TransitionDrawable 是一个可绘制对象,它可以在两个其他可绘制资源之间交叉淡入淡出。

每个可绘制对象都由单个 <transition> 元素内的 <item> 元素表示。仅支持不超过两个项目。要向前过渡,请调用 startTransition()。要向后过渡,请调用 reverseTransition()

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 TransitionDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<transition
xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:drawable="@[package:]drawable/drawable_resource"
        android:id="@[+][package:]id/resource_name"
        android:top="dimension"
        android:right="dimension"
        android:bottom="dimension"
        android:left="dimension" />
</transition>
元素
<transition>
必需。这必须是根元素。包含一个或多个 <item> 元素。

属性

xmlns:android
字符串必需。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"
<item>
定义一个用作可绘制对象过渡一部分的可绘制对象。必须是 <transition> 元素的子元素。接受子 <bitmap> 元素。

属性

android:drawable
可绘制资源必需。对可绘制资源的引用。
android:id
资源 ID。此可绘制对象的唯一资源 ID。要为此项创建新的资源 ID,请使用以下形式:"@+id/name"。加号表示这是一个新创建的 ID。您可以使用此标识符通过 View.findViewById()Activity.findViewById() 检索和修改可绘制对象。
android:top
整数。顶部的像素偏移量。
android:right
整数。右侧的像素偏移量。
android:bottom
整数。底部的像素偏移量。
android:left
整数。左侧的像素偏移量。
示例
XML 文件保存到 res/drawable/transition.xml
<?xml version="1.0" encoding="utf-8"?>
<transition xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@drawable/on" />
    <item android:drawable="@drawable/off" />
</transition>

此布局 XML 将可绘制对象应用于视图

<ImageButton
    android:id="@+id/button"
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:src="@drawable/transition" />

以下代码执行从第一个项目到第二个项目的 500 毫秒过渡

Kotlin

val button: ImageButton = findViewById(R.id.button)
val drawable: Drawable = button.drawable
if (drawable is TransitionDrawable) {
    drawable.startTransition(500)
}

Java

ImageButton button = (ImageButton) findViewById(R.id.button);
Drawable drawable = button.getDrawable();
if (drawable instanceof TransitionDrawable) {
    ((TransitionDrawable) drawable).startTransition(500);
}
另请参阅

内嵌可绘制对象

一个在 XML 中定义的可绘制对象,它将另一个可绘制对象内嵌指定距离。当视图需要一个小于视图实际边界的背景时,这很有用。

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 InsetDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<inset
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/drawable_resource"
    android:insetTop="dimension"
    android:insetRight="dimension"
    android:insetBottom="dimension"
    android:insetLeft="dimension" />
元素
<inset>
必需。定义内嵌可绘制对象。这必须是根元素。

属性

xmlns:android
字符串必需。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"
android:drawable
可绘制资源必需。对要内嵌的可绘制资源的引用。
android:insetTop
尺寸。顶部内嵌量,作为尺寸值或尺寸资源
android:insetRight
尺寸。右侧内嵌量,作为尺寸值或尺寸资源
android:insetBottom
尺寸。底部内嵌量,作为尺寸值或尺寸资源
android:insetLeft
尺寸。左侧内嵌量,作为尺寸值或尺寸资源
示例
<?xml version="1.0" encoding="utf-8"?>
<inset xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/background"
    android:insetTop="10dp"
    android:insetLeft="10dp" />
另请参阅

剪裁可绘制对象

一个在 XML 中定义的可绘制对象,它根据其当前级别剪裁另一个可绘制对象。您可以根据级别控制子可绘制对象在宽度和高度上的剪裁量,以及控制它在整个容器中放置位置的重力。最常用于实现进度条等功能。

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 ClipDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<clip
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/drawable_resource"
    android:clipOrientation=["horizontal" | "vertical"]
    android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" |
                     "fill_vertical" | "center_horizontal" | "fill_horizontal" |
                     "center" | "fill" | "clip_vertical" | "clip_horizontal"] />
元素
<clip>
必需。定义剪裁可绘制对象。这必须是根元素。

属性

xmlns:android
字符串必需。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"
android:drawable
可绘制资源必需。对要剪裁的可绘制资源的引用。
android:clipOrientation
关键字。剪裁的方向。

必须是以下常量值之一

描述
horizontal 水平剪裁可绘制对象。
vertical 垂直剪裁可绘制对象。
android:gravity
关键字。指定在可绘制对象内剪裁的位置。

必须是以下一个或多个常量值,以 | 分隔

描述
top 将对象放置在其容器的顶部,不改变其大小。当 clipOrientation"vertical" 时,剪裁发生在可绘制对象的底部。
bottom 将对象放置在其容器的底部,不改变其大小。当 clipOrientation"vertical" 时,剪裁发生在可绘制对象的顶部。
left 将对象放置在其容器的左边缘,不改变其大小。这是默认值。当 clipOrientation"horizontal" 时,剪裁发生在可绘制对象的右侧。
right 将对象放置在其容器的右边缘,不改变其大小。当 clipOrientation"horizontal" 时,剪裁发生在可绘制对象的左侧。
center_vertical 将对象放置在其容器的垂直中心,不改变其大小。剪裁行为与重力为 "center" 时相同。
fill_vertical 如果需要,增大对象的垂直尺寸,使其完全填充其容器。当 clipOrientation"vertical" 时,不会发生剪裁,因为可绘制对象填充了垂直空间(除非可绘制对象级别为 0,在这种情况下它不可见)。
center_horizontal 将对象放置在其容器的水平中心,不改变其大小。剪裁行为与重力为 "center" 时相同。
fill_horizontal 如果需要,增大对象的水平尺寸,使其完全填充其容器。当 clipOrientation"horizontal" 时,不会发生剪裁,因为可绘制对象填充了水平空间(除非可绘制对象级别为 0,在这种情况下它不可见)。
center 将对象放置在其容器的垂直和水平轴的中心,不改变其大小。当 clipOrientation"horizontal" 时,剪裁发生在左侧和右侧。当 clipOrientation"vertical" 时,剪裁发生在顶部和底部。
fill 如果需要,增大对象的水平和垂直尺寸,使其完全填充其容器。不会发生剪裁,因为可绘制对象填充了水平和垂直空间(除非可绘制对象级别为 0,在这种情况下它不可见)。
clip_vertical 可以设置的附加选项,用于将子项的顶部和/或底部边缘剪裁到其容器的边界。剪裁基于垂直重力:顶部重力剪裁底部边缘,底部重力剪裁顶部边缘,两者都不剪裁两个边缘。
clip_horizontal 可以设置的附加选项,用于将子项的左侧和/或右侧边缘剪裁到其容器的边界。剪裁基于水平重力:左侧重力剪裁右边缘,右侧重力剪裁左边缘,两者都不剪裁两个边缘。
示例
XML 文件保存到 res/drawable/clip.xml
<?xml version="1.0" encoding="utf-8"?>
<clip xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/android"
    android:clipOrientation="horizontal"
    android:gravity="left" />

以下布局 XML 将剪裁可绘制对象应用于视图

<ImageView
    android:id="@+id/image"
    android:src="@drawable/clip"
    android:layout_height="wrap_content"
    android:layout_width="wrap_content" />

以下代码获取可绘制对象并增加剪裁量以逐步显示图像

Kotlin

val imageview: ImageView = findViewById(R.id.image)
val drawable: Drawable = imageview.background
if (drawable is ClipDrawable) {
    drawable.level = drawable.level + 1000
}

Java

ImageView imageview = (ImageView) findViewById(R.id.image);
Drawable drawable = imageview.getBackground();
if (drawable instanceof ClipDrawable) {
    ((ClipDrawable)drawable).setLevel(drawable.getLevel() + 1000);
}

增加级别会减少剪裁量并缓慢显示图像。这是级别为 7000 时的图像

注意:默认级别为 0,表示完全剪裁,因此图像不可见。当级别为 10,000 时,图像未被剪裁,完全可见。

另请参阅

缩放可绘制对象

一个在 XML 中定义的可绘制对象,它根据其当前级别更改另一个可绘制对象的大小。

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 ScaleDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<scale
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/drawable_resource"
    android:scaleGravity=["top" | "bottom" | "left" | "right" | "center_vertical" |
                          "fill_vertical" | "center_horizontal" | "fill_horizontal" |
                          "center" | "fill" | "clip_vertical" | "clip_horizontal"]
    android:scaleHeight="percentage"
    android:scaleWidth="percentage" />
元素
<scale>
必需。定义缩放可绘制对象。这必须是根元素。

属性

xmlns:android
字符串必需。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"
android:drawable
可绘制资源必需。对可绘制资源的引用。
android:scaleGravity
关键字。指定缩放后的重力位置。

必须是以下一个或多个常量值,以 | 分隔

描述
top 将对象放置在其容器的顶部,不改变其大小。
bottom 将对象放置在其容器的底部,不改变其大小。
left 将对象放置在其容器的左边缘,不改变其大小。这是默认值。
right 将对象放置在其容器的右边缘,不改变其大小。
center_vertical 将对象放置在其容器的垂直中心,不改变其大小。
fill_vertical 如果需要,增大对象的垂直尺寸,使其完全填充其容器。
center_horizontal 将对象放置在其容器的水平中心,不改变其大小。
fill_horizontal 如果需要,增大对象的水平尺寸,使其完全填充其容器。
center 将对象放置在其容器的垂直和水平轴的中心,不改变其大小。
fill 如果需要,增大对象的水平和垂直尺寸,使其完全填充其容器。
clip_vertical 可以设置的附加选项,用于将子项的顶部和/或底部边缘剪裁到其容器的边界。剪裁基于垂直重力:顶部重力剪裁底部边缘,底部重力剪裁顶部边缘,两者都不剪裁两个边缘。
clip_horizontal 可以设置的附加选项,用于将子项的左侧和/或右侧边缘剪裁到其容器的边界。剪裁基于水平重力:左侧重力剪裁右边缘,右侧重力剪裁左边缘,两者都不剪裁两个边缘。
android:scaleHeight
百分比。缩放高度,表示为可绘制对象边界的百分比。值的格式为 XX%,例如 100% 或 12.5%。
android:scaleWidth
百分比。缩放宽度,表示为可绘制对象边界的百分比。值的格式为 XX%,例如 100% 或 12.5%。
示例
<?xml version="1.0" encoding="utf-8"?>
<scale xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/logo"
    android:scaleGravity="center_vertical|center_horizontal"
    android:scaleHeight="80%"
    android:scaleWidth="80%" />
另请参阅

形状可绘制对象

这是 XML 中定义的通用形状。

文件位置
res/drawable/filename.xml
文件名即资源 ID
已编译资源数据类型
指向 GradientDrawable 的资源指针
资源引用
在 Java 中:R.drawable.filename
在 XML 中:@[package:]drawable/filename
语法
<?xml version="1.0" encoding="utf-8"?>
<shape
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape=["rectangle" | "oval" | "line" | "ring"] >
    <corners
        android:radius="integer"
        android:topLeftRadius="integer"
        android:topRightRadius="integer"
        android:bottomLeftRadius="integer"
        android:bottomRightRadius="integer" />
    <gradient
        android:angle="integer"
        android:centerX="float"
        android:centerY="float"
        android:centerColor="integer"
        android:endColor="color"
        android:gradientRadius="integer"
        android:startColor="color"
        android:type=["linear" | "radial" | "sweep"]
        android:useLevel=["true" | "false"] />
    <padding
        android:left="integer"
        android:top="integer"
        android:right="integer"
        android:bottom="integer" />
    <size
        android:width="integer"
        android:height="integer" />
    <solid
        android:color="color" />
    <stroke
        android:width="integer"
        android:color="color"
        android:dashWidth="integer"
        android:dashGap="integer" />
</shape>
元素
<shape>
必需。形状可绘制对象。这必须是根元素。

属性

xmlns:android
字符串必需。定义 XML 命名空间,必须是 "http://schemas.android.com/apk/res/android"
android:shape
关键字。定义形状类型。有效值为
描述
"rectangle" 填充包含视图的矩形。这是默认形状。
"oval" 适合包含视图尺寸的椭圆形形状。
"line" 跨越包含视图宽度的水平线。此形状需要 <stroke> 元素来定义线的宽度。
"ring" 环形形状。

以下属性仅在 android:shape="ring" 时使用

android:innerRadius
尺寸。圆环内部(中间的孔)的半径,作为尺寸值或尺寸资源
android:innerRadiusRatio
浮点数。圆环内部的半径,表示为圆环宽度的比率。例如,如果 android:innerRadiusRatio="5",则内半径等于圆环宽度除以 5。此值被 android:innerRadius 覆盖。默认值为 9。
android:thickness
尺寸。圆环的厚度,作为尺寸值或尺寸资源
android:thicknessRatio
浮点数。圆环的厚度,表示为圆环宽度的比率。例如,如果 android:thicknessRatio="2",则厚度等于圆环宽度除以 2。此值被 android:innerRadius 覆盖。默认值为 3。
android:useLevel
布尔值。如果此项用作 LevelListDrawable,则为 true。通常为 false,否则您的形状可能不会出现。
<corners>
为形状创建圆角。仅当形状为矩形时适用。

属性

android:radius
尺寸。所有角的半径,作为尺寸值或尺寸资源。以下属性将覆盖每个角。
android:topLeftRadius
尺寸。左上角的半径,作为尺寸值或尺寸资源
android:topRightRadius
尺寸。右上角的半径,作为尺寸值或尺寸资源
android:bottomLeftRadius
尺寸。左下角的半径,作为尺寸值或尺寸资源
android:bottomRightRadius
尺寸。右下角的半径,作为尺寸值或尺寸资源

注意:每个角最初都必须提供大于 1 的圆角半径,否则不会有圆角。如果您希望某些特定角不带圆角,一种解决方法是使用 android:radius 设置一个大于 1 的默认圆角半径,然后用您真正想要的值覆盖每个角,在不希望带圆角的地方提供 0(“0dp”)。

<gradient>
指定形状的渐变颜色。

属性

android:angle
整数。渐变的角度,以度为单位。0 表示从左到右,90 表示从下到上。它必须是 45 的倍数。默认值为 0。
android:centerX
浮点数。渐变中心的相对 X 坐标(0 - 1.0)。
android:centerY
浮点数。渐变中心的相对 Y 坐标(0 - 1.0)。
android:centerColor
颜色。起始颜色和结束颜色之间的可选颜色,作为十六进制值或颜色资源
android:endColor
颜色。结束颜色,作为十六进制值或颜色资源
android:gradientRadius
浮点数。渐变的半径。仅当 android:type="radial" 时才应用。
android:startColor
颜色。起始颜色,作为十六进制值或颜色资源
android:type
关键字。要应用的渐变模式类型。有效值为
描述
"linear" 线性渐变。这是默认值。
"radial" 径向渐变。起始颜色是中心颜色。
"sweep" 扫描线渐变。
android:useLevel
布尔值。如果此项用作 LevelListDrawable,则为 true。
<padding>
应用于包含视图元素的内边距。这会填充视图内容的位置,而不是形状。

属性

android:left
尺寸。左内边距,作为尺寸值或尺寸资源
android:top
尺寸。上内边距,作为尺寸值或尺寸资源
android:right
尺寸。右内边距,作为尺寸值或尺寸资源
android:bottom
尺寸。下内边距,作为尺寸值或尺寸资源
<size>
形状的大小。

属性

android:height
尺寸。形状的高度,作为尺寸值或尺寸资源
android:width
尺寸。形状的宽度,作为尺寸值或尺寸资源

注意:默认情况下,形状会按比例缩放以适应容器视图的大小,与此处定义的尺寸成比例。当您在 ImageView 中使用该形状时,可以通过将 android:scaleType 设置为 "center" 来限制缩放。

<solid>
填充形状的纯色。

属性

android:color
颜色。应用于形状的颜色,作为十六进制值或颜色资源
<stroke>
形状的描边线。

属性

android:width
尺寸。线的粗细,作为尺寸值或尺寸资源
android:color
颜色。线的颜色,作为十六进制值或颜色资源
android:dashGap
尺寸。线条虚线之间的距离,作为尺寸值或尺寸资源。仅当设置了 android:dashWidth 时才有效。
android:dashWidth
尺寸。每条虚线的大小,作为尺寸值或尺寸资源。仅当设置了 android:dashGap 时才有效。
示例
XML 文件保存到 res/drawable/gradient_box.xml
<?xml version="1.0" encoding="utf-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle">
    <gradient
        android:startColor="#FFFF0000"
        android:endColor="#80FF00FF"
        android:angle="45"/>
    <padding android:left="7dp"
        android:top="7dp"
        android:right="7dp"
        android:bottom="7dp" />
    <corners android:radius="8dp" />
</shape>

此布局 XML 将形状可绘制对象应用于视图

<TextView
    android:background="@drawable/gradient_box"
    android:layout_height="wrap_content"
    android:layout_width="wrap_content" />

此应用代码获取形状可绘制对象并将其应用于视图

Kotlin

val shape: Drawable? = getDrawable(resources, R.drawable.gradient_box, getTheme())

val tv: TextView = findViewById(R.id.textview)
tv.background = shape

Java

Resources res = getResources();
Drawable shape = ResourcesCompat.getDrawable(res, R.drawable.gradient_box, getTheme());

TextView tv = (TextView)findViewById(R.id.textview);
tv.setBackground(shape);
另请参阅