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 对于静态颜色按预期工作，但它会扁平化颜色状态列表资源。

矢量资源和图像资源

使用 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 在主线程上解码和解析资源内容。

动画矢量可绘制对象

使用 AnimatedImageVector.animatedVectorResource API 可加载动画矢量可绘制对象 XML。此方法返回一个 AnimatedImageVector 实例。为了显示动画图像，请使用 rememberAnimatedVectorPainter 方法创建一个 Painter，该对象可在 Image 和 Icon 可组合项中使用。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 中使用 Material 图标的入口点。共有五个不同的图标主题：Filled、Outlined、Rounded、TwoTone 和 Sharp。每个主题都包含相同的图标，但具有独特的视觉样式。您通常应该选择一个主题并在整个应用中使用它以保持一致性。

要绘制图标，您可以使用 Icon 可组合项，它会应用色调并提供与图标匹配的布局大小。

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

一些最常用的图标作为 androidx.compose.material 依赖项的一部分提供。要使用任何其他 Material 图标，请将 material-icons-extended 依赖项添加到 build.gradle 文件中。

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

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

字体

要在 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(
    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 中的主题文档中了解有关排版的更多信息。