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

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="purple_200">#FFBB86FC</color>

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

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 方法创建可在 ImageIcon 可组合项中使用的 PainterrememberAnimatedVectorPainter 方法的布尔值 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
)

图标

Jetpack Compose 附带 Icons 对象,该对象是在 Compose 中使用 Material 图标的入口点。共有以下五种不同的图标主题:FilledOutlinedRoundedTwoToneSharp。每个主题包含相同的图标,但视觉风格不同。通常,您应该选择一种主题,并在整个应用中保持使用这一主题,从而确保一致性。

如需绘制图标,您可以使用 Icon 可组合项,该可组合项将应用色调并提供与图标匹配的布局尺寸。

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

一些最常用的图标可用作 androidx.compose.material 依赖项的一部分。如需使用其他任何 Material 图标,请将 material-icons-extended 依赖项添加到 build.gradle 文件。

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

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

字体

如需在 Compose 中使用字体,请下载字体文件,并将其放在 res/font 文件夹中以直接捆绑到 APK 中。

使用 Font API 加载每种字体,并使用这些字体创建一个 FontFamily,您可以在 TextStyle 实例中使用该 FontFamily 来创建您自己的 Typography。通过 以下代码取自 夹娃娃 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()
    }
}

如需了解如何在 Compose 中使用可下载字体,请参阅 可下载字体页面。

如需详细了解排版,请参阅 Compose 中的主题设置文档