Compose 中的資源

Jetpack Compose 可以存取 Android 專案中定義的資源。本文件將說明 Compose 支援存取這些資源的部分 API。

資源是程式碼使用的額外檔案和靜態內容，例如點陣圖、版面配置定義、使用者介面字串和動畫指示等。如果您不熟悉 Android 中的資源，請參閱應用程式資源總覽指南。

字串

最常見的資源類型是字串。使用 stringResource API 可擷取 XML 資源中靜態定義的字串。

// In the res/values/strings.xml file
// <string name="compose">Jetpack Compose</string>

// In your Compose code
Text(
    text = stringResource(R.string.compose)
)
ResourcesSnippets.kt

stringResource 也適用於位置格式設定。

// In the res/values/strings.xml file
// <string name="congratulate">Happy %1$s %2$d</string>

// In your Compose code
Text(
    text = stringResource(R.string.congratulate, "New Year", 2021)
)
ResourcesSnippets.kt

字串複數 (實驗功能)

使用 pluralStringResource API 載入設有一定數量的字串複數。

// In the res/strings.xml file
// <plurals name="runtime_format">
//    <item quantity="one">%1$d minute</item>
//    <item quantity="other">%1$d minutes</item>
// </plurals>

// In your Compose code
Text(
    text = pluralStringResource(
        R.plurals.runtime_format,
        quantity,
        quantity
    )
)
ResourcesSnippets.kt

使用 pluralStringResource 方法時，如果您的字串包含數字格式，您就必須傳送兩次此計數。舉例來說，如果是 %1$d minutes 字串，第一個計數參數會選取適當的複數字串，並在 %1$d 預留位置插入第二個計數參數。如果您的多重字串不包含字串格式，則不需要將第三個參數傳送至 pluralStringResource。

如要進一步瞭解複數相關資訊，請參閱數量字串說明文件。

尺寸

同樣地，您也可以使用 dimensionResource API，從資源 XML 檔案取得尺寸。

// In the res/values/dimens.xml file
// <dimen name="padding_small">8dp</dimen>

// In your Compose code
val smallPadding = dimensionResource(R.dimen.padding_small)
Text(
    text = "...",
    modifier = Modifier.padding(smallPadding)
)
ResourcesSnippets.kt

顏色

如果要為應用程式階段採用 Compose，請使用 colorResource API 從資源 XML 檔案取得顏色。

// In the res/colors.xml file
// <color name="purple_200">#FFBB86FC</color>

// In your Compose code
Divider(color = colorResource(R.color.purple_200))
ResourcesSnippets.kt

colorResource 在處理靜態顏色時可正常運作，但會壓縮合併顏色狀態清單資源。

警告：最好使用主題中的顏色，而非硬式編碼顏色。雖然您可以使用 colorResource 函式存取顏色，我們仍建議在 MaterialTheme 中定義應用程式的顏色，該物件可透過 MaterialTheme.colors.primary 等可組合項存取。如需更多資訊，請參閱「Compose 中的設計系統」說明文件。

向量素材資源和圖片資源

使用 painterResource API 可載入向量可繪項目或光柵化素材資源格式，例如 PNG。您不需要知道可繪項目的類型，只要在 Image 可組合項或 paint 修飾符中使用 painterResource 即可。

// Files in res/drawable folders. For example:
// - res/drawable-nodpi/ic_logo.xml
// - res/drawable-xxhdpi/ic_logo.png

// In your Compose code
Icon(
    painter = painterResource(id = R.drawable.ic_logo),
    contentDescription = null // decorative element
)
ResourcesSnippets.kt

painterResource 會將主執行緒中的資源內容解碼並進行剖析。

注意：painterResource 與 Context.getDrawable 不同，只能載入 BitmapDrawable 和 VectorDrawable 平台 Drawable 類型。

動畫向量可繪項目

使用 AnimatedImageVector.animatedVectorResource API 可載入動畫向量可繪項目 XML。這個方法會傳回 AnimatedImageVector 執行個體。如要顯示動畫圖片，請使用 rememberAnimatedVectorPainter 方法建立可用於 Image 和 Icon 可組合項的 Painter。rememberAnimatedVectorPainter 方法的 atEnd 布林值參數會指出圖片是否要繪製在所有動畫的結尾處。如果與可變動狀態搭配使用，變更這個值將觸發相應的動畫。

// Files in res/drawable folders. For example:
// - res/drawable/ic_hourglass_animated.xml

// In your Compose code
val image =
    AnimatedImageVector.animatedVectorResource(R.drawable.ic_hourglass_animated)
val atEnd by remember { mutableStateOf(false) }
Icon(
    painter = rememberAnimatedVectorPainter(image, atEnd),
    contentDescription = null // decorative element
)
ResourcesSnippets.kt

圖示

Jetpack Compose 包含 Icons 物件，方便您在 Compose 中使用質感設計圖示。這些圖示有五種不同的主題：Filled、Outlined、Rounded、TwoTone 和 Sharp。每個主題都包含相同的圖示，但視覺樣式各不相同。一般而言，您應選擇一種主題並用於整個應用程式，以維持一致性。

如要繪製圖示，可以使用 Icon，這個可組合項會套用色調並依據圖示提供大小相符的版面配置。

Icon(Icons.Rounded.Menu, contentDescription = "Localized description")
ResourcesSnippets.kt

某些最常用的圖示是由 androidx.compose.material 依附元件提供使用。如要使用任何其他質感設計圖示，請將 material-icons-extended 依附元件新增至 build.gradle 檔案。

dependencies {
  def composeBom = platform('androidx.compose:compose-bom:2024.10.01')
  implementation composeBom

  implementation 'androidx.compose.material:material-icons-extended'
}

注意： 圖示會保有 Material 定義的相同名稱，但其 snake_case 名稱會轉換成 PascalCase。舉例來說，add_alarm 會變成 AddAlarm。開頭為數字 (例如 360) 的圖示會加上 _ 這個前置字元，變成 _360。

警告： material-icons-extended 是大型程式庫，可能會影響您的 APK 大小。因此，建議您在正式版中使用 R8/Proguard 移除未使用的資源。另外因為程式庫較大，所以在開發期間，專案的建構時間和 Android Studio 的預覽載入時間可能會增加。另一方面，material-icons-extended 可讓您快速存取所有圖示的最新版本，更迅速地完成疊代。您也可以使用這個程式庫複製圖示的原始碼，以便在應用程式中提供一個固定版本，或者使用 Android Studio 的匯入向量素材資源功能來匯入圖示。

字型

如要在 Compose 中使用字型，請將字型檔案放入 res/font 資料夾，即可直接下載這些檔案並納入在 APK 中。

透過 Font API 載入每種字型，然後使用這些字型建立 FontFamily，以便在 TextStyle 執行個體中使用，建立自己的 Typography。下方是從 Crane Compose 範例和相關的 Typography.kt 檔案中擷取的程式碼。

// Define and load the fonts of the app
private val light = Font(R.font.raleway_light, FontWeight.W300)
private val regular = Font(R.font.raleway_regular, FontWeight.W400)
private val medium = Font(R.font.raleway_medium, FontWeight.W500)
private val semibold = Font(R.font.raleway_semibold, FontWeight.W600)

// Create a font family to use in TextStyles
private val craneFontFamily = FontFamily(light, regular, medium, semibold)

// Use the font family to define a custom typography
val craneTypography = Typography(
    titleLarge = TextStyle(
        fontFamily = craneFontFamily
    ) /* ... */
)

// Pass the typography to a MaterialTheme that will create a theme using
// that typography in the part of the UI hierarchy where this theme is used
@Composable
fun CraneTheme(content: @Composable () -> Unit) {
    MaterialTheme(typography = craneTypography) {
        content()
    }
}
ResourcesSnippets.kt

如要瞭解如何在 Compose 中使用可下載的字型，請參閱「可下載的字型」頁面。

想進一步瞭解字體排版，請參閱 Compose 說明文件中的主題設定部分