可繪製資源

Stay organized with collections Save and categorize content based on your preferences.

可繪製資源是圖形可繪製於畫面上的一般概念,您可以利用 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()。預設值為 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 圖片也會縮放至符合檢視畫面的大小。使用 Nine-Patch 圖片的一個例子,是 Android 標準 Button 小工具使用的背景,此背景為配合按鈕內的文字 (或圖片) 而必須延展。

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

如需查看如何建立具有可延展區域的 Nine-Patch 檔案的完整討論,請參閱「2D 圖形」文件。

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> 元素,為每個使用「置中重心」的項目定義可繪製資源。這可以確保圖片不會因偏移圖片導致的大小調整,而為符合容器大小而縮放。

此版面配置 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
「布林值」。如果點陣圖的像素設定與螢幕的設定不同,則為「true」以啟用或停用點陣圖的遞色 (例如:在 RGB 565 的螢幕上顯示 ARGB 8888 點陣圖);設為「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
「布林值」。如果使用方向控制瀏覽,物件為目前的使用者所選內容時應使用此項目,則為「true」(例如使用 D-Pad 瀏覽清單時);如果在沒有選取物件時應使用此項目,則為「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);
另請參閱: