可繪製資源

可繪製資源是圖形可繪製於畫面上的一般概念,您可以利用 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 工具,透過無失真圖片壓縮的方式,自動將點陣圖檔案最佳化。舉例來說,真實色彩 PNG 如果需要的顏色不超過 256 種顏色,也許可以利用調色盤轉換成 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
布林值。如果點陣圖與螢幕有不同的像素設定 (例如:點陣圖為 ARGB 8888,而螢幕為 RGB 565),則啟用或停用點陣圖的遞色。
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()。預設值為否。
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 圖片也會縮放至符合檢視區塊的大小。使用 nine-patch 圖片的一個例子,是 Android 標準 Button 小工具使用的背景,此背景為配合按鈕內的文字 (或圖片) 而必須延展。

與一般的點陣圖相同,您可以直接參照 nine-patch 檔案或 XML 定義的資源。

如要進一步瞭解如何建立具有可延展區域的 nine-patch 檔案,請參閱「建立可調整大小的點陣圖 (9-patch 檔案)」。

nine-patch 檔案

檔案位置:
res/drawable/filename.9.png
檔案名稱即為資源 ID
編譯資源資料類型:
NinePatchDrawable 的資源指標。
資源參照:
Java:R.drawable.filename
XML:@[package:]drawable/filename
例如:
res/drawable/myninepatch.9.png 儲存圖片後,此版面配置 XML 就會將 nine-patch 套用至檢視區塊:
<Button
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:background="@drawable/myninepatch" />
另請參閱:

XML nine-patch

XML nine-patch 是 XML 中定義的資源,會指向 nine-patch 檔案。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
可繪製資源。必要。參照 nine-patch 檔案。
android:dither
布林值。如果點陣圖與螢幕有不同的像素設定 (例如:點陣圖為 ARGB 8888,而螢幕為 RGB 565),則啟用或停用點陣圖的遞色。
例如:
<?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。您可以使用此 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
布林值。如果點陣圖與螢幕有不同的像素設定 (例如:點陣圖為 ARGB 8888,而螢幕為 RGB 565),則為「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。您可以使用此 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,然後再以您要使用的值覆寫每個邊角,並將不要成為圓角的邊角值設為零 (「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);
另請參閱: