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 可在主线程中解码并解析资源的内容。

注意：与 Context.getDrawable 不同，painterResource 只能加载 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 中使用 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: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 大小。因此，请考虑在正式 build 中使用 R8/Proguard 来移除未使用的资源。此外，由于大小较大，项目的构建时间和 Android Studio 的预览加载时间在开发过程中也可能会增加。另一方面，material-icons-extended 可让您快速访问所有图标的最新版本，实现更快迭代。您还可以使用此库复制图标的源代码，以便在应用中使用固定副本，或者使用 Android Studio 的“导入矢量资源”功能导入图标。

字体

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

使用 Font API 加载每种字体，并使用这些字体创建一个 FontFamily，您可以在 TextStyle 实例中使用该 FontFamily 来创建您自己的 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 中的主题设置文档