可繪製資源

可繪製資源是圖形可繪製於畫面上的一般概念，您可以利用 getDrawable(int) 等 API 擷取資料，或使用 android:drawable 和 android: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);

另請參閱：

• 可繪項目總覽
• BitmapDrawable

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" />

另請參閱：

• BitmapDrawable
• 建立別名資源

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" />

另請參閱：

• 建立可調整大小的點陣圖 (9-patch 檔案)
• NinePatchDrawable

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" />

結果導致一堆越來越偏移的圖片：

另請參閱：

• LayerDrawable

狀態清單

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" />

另請參閱：

• StateListDrawable

等級清單

可管理多個替代可繪項目的可繪項目，每個可繪項目都會指派最大數值。如果使用 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() 變更等級。

另請參閱：

• LevelListDrawable

轉場可繪項目

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);
}

另請參閱：

• TransitionDrawable

插邊可繪項目

在 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" />

另請參閱：

• InsetDrawable

裁減可繪項目

在 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 時，圖片不會裁剪，因此會完整顯示。

另請參閱：

• ClipDrawable

縮放可繪項目

在 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%" />

另請參閱：

• ScaleDrawable

形狀可繪項目

這是 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);

另請參閱：

• ShapeDrawable