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)
)
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)
)
字串複數 (實驗功能)
使用 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)
)
使用 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)
)
顏色
如果要為應用程式階段採用 Compose,請使用 colorResource
API 從資源 XML 檔案取得顏色。
// In the res/colors.xml file
// <color name="colorGrey">#757575</color>
// In your Compose code
Divider(color = colorResource(R.color.colorGrey))
colorResource
在處理靜態顏色時可正常運作,但會壓縮合併顏色狀態清單資源。
向量素材資源和圖片資源
使用 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
)
painterResource
會將主執行緒中的資源內容解碼並進行剖析。
動畫向量可繪項目
使用 AnimatedImageVector.animatedVectorResource
API 可載入動畫向量可繪項目 XML。這個方法會傳回 AnimatedImageVector
執行個體。如要顯示動畫圖片,請使用 rememberAnimatedVectorPainter
方法建立可用於 Image
和 Icon
可組合項的 Painter
。rememberAnimatedVectorPainter
方法的 atEnd
布林值參數會指出圖片是否要繪製在所有動畫的結尾處。如果與可變動狀態搭配使用,變更這個值將觸發相應的動畫。
// Files in res/drawable folders. For example:
// - res/drawable/animated_vector.xml
// In your Compose code
val image = AnimatedImageVector.animatedVectorResource(R.drawable.animated_vector)
val atEnd by remember { mutableStateOf(false) }
Icon(
painter = rememberAnimatedVectorPainter(image, atEnd),
contentDescription = null // decorative element
)
圖示
Jetpack Compose 包含 Icons
物件,方便您在 Compose 中使用質感設計圖示。這些圖示有五種不同的主題:Filled、Outlined、Rounded、TwoTone 和 Sharp。每個主題都包含相同的圖示,但視覺樣式各不相同。一般而言,您應選擇一種主題並用於整個應用程式,以維持一致性。
如要繪製圖示,可以使用 Icon
,這個可組合項會套用色調並依據圖示提供大小相符的版面配置。
import androidx.compose.material.Icon
Icon(Icons.Rounded.Menu, contentDescription = "Localized description")
某些最常用的圖示是由 androidx.compose.material
依附元件提供使用。如要使用任何其他質感設計圖示,請將 material-icons-extended
依附元件新增至 build.gradle
檔案。
dependencies {
...
implementation "androidx.compose.material:material-icons-extended:$compose_version"
}
字型
如要在 Compose 中使用字型,請下載字型檔案並直接附在 APK 中,只要將字型檔案放入 res/font
資料夾即可。
透過 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(
defaultFontFamily = 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()
}
}
想進一步瞭解字體排版,請參閱 Compose 說明文件中的主題設定部分。