【Compose Multiplatform跨端声明式UI实用技术】第15课:跨平台资源管理

43 阅读18分钟

第14课完成了平台互操作的学习。本课深入CMP资源管理体系:compose-multiplatform-resources 库与Gradle插件配置、composeResources 目录结构规范、资源限定符与多环境适配、Res 类的生成与自定义、图片/字符串/字体/原始文件的访问方式、字符串国际化与多语言目录组织,以及Web端自动字体回退与资源预加载。本课内容基于CMP 1.12.1与Kotlin 2.3.20。 文末附有15道配套习题与本课知识点总结。

目录

一、为什么需要跨平台资源管理

1.1 传统资源管理的困境

在单平台开发中,Android使用 res/drawable、res/values/strings.xml,iOS使用 Assets.xcassets、Localizable.strings,桌面端使用类路径资源。各平台的资源组织方式和访问API完全不同。在CMP项目中,如果继续使用平台各自的资源系统,共享代码就无法直接访问资源,必须通过 expect/actual 为每个平台编写资源加载代码,复杂度急剧上升。

1.2 CMP资源管理的解决方案

Compose Multiplatform提供了一个专门的 compose-multiplatform-resources 库和Gradle插件支持,用于在所有受支持平台的公共代码中访问资源。其核心设计是:资源统一存放在 composeResources 目录中,构建时自动生成类型安全的 Res 类,开发者通过 Res.drawable.xxx、Res.string.xxx 等属性访问资源,无需关心底层平台的资源加载机制。

下面是 CMP 资源管理的整体架构流程图:

mermaid diagram

二、依赖配置与目录结构

2.1 添加依赖

在 composeApp/build.gradle.kts 中,将资源库依赖添加到 commonMain 源集:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(compose.components.resources)
        }
    }
}

如需引用完整坐标,可使用 org.jetbrains.compose.components:components-resources。在CMP 1.10.0+中,依赖别名已弃用,应在版本目录中显式声明:

[libraries]
compose-components-resources = { module = "org.jetbrains.compose.components:components-resources", version.ref = "composeMultiplatform" }

2.2 创建资源目录

在 commonMain 源集下创建 composeResources 目录,按以下规则组织文件:

commonMain/
└── composeResources/
    ├── drawable/          # 图片(JPEG、PNG、Bitmap、WebP、Android XML矢量图)
    ├── font/              # 字体(TTF、OTF、TTC)
    ├── values/            # 字符串(strings.xml 格式)
    └── files/             # 其他文件(可任意组织文件夹层级)

关键规则:图片放在 drawable 目录,字体放在 font 目录,字符串放在 values 目录,其他文件放在 files 目录。files 目录支持任意文件夹层级,适合存储JSON配置文件、音频、PDF等非结构化资源。需要注意,files 目录不生成类型安全访问器,需要通过 Res.readBytes() 手动读取。

2.3 自定义资源目录

在 compose.resources {} 块中,可以为每个源集指定自定义资源目录:

compose.resources {
    customDirectory(
        sourceSetName = "jvmMain",
        directoryProvider = provider {
            layout.projectDirectory.dir("desktopResources")
        }
    )
}

自定义目录也需遵循相同的子目录结构(drawable、font、values、files)。还可以通过Gradle任务动态生成资源目录,例如从远程下载文件。

2.4 androidLibrary目标的资源支持

从AGP 8.8.0开始,androidLibrary 目标也支持生成的 Res 类和资源访问器:

kotlin {
    androidLibrary {
        androidResources.enable = true
    }
}

下面是资源目录的组织结构图:

mermaid diagram

三、资源限定符:多环境适配

3.1 限定符的概念

同一资源可能需要在不同环境下呈现不同形态——不同语言的文本、深色/浅色主题的图片、不同屏幕密度的图标。Compose Multiplatform通过目录名后缀(限定符) 来表达这些约束。

3.2 支持的限定符类型

限定符类型示例说明
语言values-en、values-fr、values-zh按语言代码匹配
区域values-en-rUS、values-en-rGB按区域代码匹配
主题drawable-dark、drawable-light按系统深色/浅色主题匹配
密度drawable-mdpi、drawable-hdpi按屏幕密度匹配

限定符可以组合使用,例如 drawable-en-rUS-mdpi-dark 表示英语(美国)区域、160 DPI屏幕、深色主题下的图片。

3.3 中文双脚本回退机制

这是中文等多文字系统语言必须特别注意的场景。当一种语言有多个文字系统(如中文简体和繁体),除了脚本特定的目录(values-b+zh+Hans、values-b+zh+Hant),必须同时提供无脚本目录(values-zh)作为回退。如果只提供 values-b+zh+Hans 和 values-b+zh+Hant,所有请求都会匹配到它们,导致资源无法解析而崩溃。

3.4 实际目录结构示例

commonMain/composeResources/
├── drawable/
│   ├── logo.png                    # 默认图片
│   └── logo-dark.png               # 深色主题图片(通过限定符目录)
├── drawable-dark/
│   └── logo.png                    # 深色主题下的logo
├── values/
│   └── strings.xml                 # 默认语言(英语)
├── values-es/
│   └── strings.xml                 # 西班牙语
├── values-fr/
│   └── strings.xml                 # 法语
├── values-zh/
│   └── strings.xml                 # 中文回退(必须提供)
├── values-b+zh+Hans/
│   └── strings.xml                 # 中文简体
└── values-b+zh+Hant/
    └── strings.xml                 # 中文繁体

重要提醒:必须始终包含不带语言和区域限定符的 values/ 目录(用于保存默认字符串)。如果将所有字符串文件都放入带限定符的目录中,且设备语言不在支持列表中,应用在该设备上运行时会崩溃。

下面是资源限定符的匹配流程:

mermaid diagram

四、Res 类的生成与自定义

4.1 Res 类的生成机制

设置好资源后,构建项目会生成一个特殊的 Res 类,提供对所有资源的类型安全访问。要重新生成 Res 类,再次构建项目或在IDE中重新导入项目即可。

生成的类位于 {group name}.{module name}.generated.resources 包下,导入方式如下:

import project.composeapp.generated.resources.Res
import project.composeapp.generated.resources.example_image

其中 project 是项目名,composeapp 是放置资源目录的模块名,Res 是生成类的默认名称。

4.2 自定义Res类生成

在 compose.resources {} 块中可以配置Res类的生成行为:

compose.resources {
    publicResClass = false      // 默认:internal;设为true则公开
    packageOfResClass = "me.sample.library.resources"  // 自定义包名
    generateResClass = auto     // 默认:仅在有显式依赖时生成
}
配置项默认值说明
publicResClassfalse(internal)设为 true 使 Res 类对外可见
packageOfResClass{group}.{module}.generated.resources自定义生成类的包名
generateResClassautoalways 无条件生成;auto 仅在有显式资源依赖时生成

使用场景:当资源库作为KMP模块被其他模块依赖时,需要将 publicResClass = true 才能在其他模块中访问;当资源库仅通过传递依赖可用时,使用 generateResClass = always。

下面是 Res 类的生成与自定义流程:

mermaid diagram

五、各类资源的访问方式

5.1 图片资源

CMP支持光栅化图片(JPEG、PNG、Bitmap、WebP)和矢量图(Android XML Vector,不支持外部引用)。

// 作为Painter使用
Image(
    painter = painterResource(Res.drawable.example_image),
    contentDescription = null
)

// 作为ImageBitmap使用
Image(
    bitmap = imageResource(Res.drawable.example_image),
    contentDescription = null
)

// 作为ImageVector使用(XML矢量图)
Icon(
    imageVector = vectorResource(Res.drawable.example_vector),
    contentDescription = null
)

painterResource() 在所有平台(除Web外)同步工作;Web平台首次重组返回空Painter,后续重组替换为加载的图片。SVG图片在所有平台(除Android外)均被支持。

5.2 字符串资源

在 values/strings.xml 中以键值对形式定义字符串:

<resources>
    <string name="app_name">My Application</string>
    <string name="greeting">Hello, world!</string>
    <string name="welcome_message">Welcome, %s!</string>
</resources>

在Composable中使用 stringResource() 访问:

Text(text = stringResource(Res.string.greeting))
Text(text = stringResource(Res.string.welcome_message, "Alice"))

stringResource() 是可组合函数,根据当前用户的locale自动选择正确的翻译文本。它还支持字符串模板和复数形式(通过 pluralStringResource())。

5.3 字体资源

将字体文件(TTF、OTF、TTC)放入 composeResources/font/ 目录:

val appFont = FontFamily(
    Font(Res.font.inter_regular, FontWeight.Normal),
    Font(Res.font.inter_bold, FontWeight.Bold),
)

Text(
    text = "自定义字体文本",
    fontFamily = appFont
)

5.4 原始文件资源

对于非结构化文件(JSON、音频、PDF等),放入 composeResources/files/ 目录,通过 Res.readBytes() 读取字节:

val jsonBytes = Res.readBytes("files/config.json")
val jsonString = jsonBytes.decodeToString()

// 字节数组转为图片
val imageBitmap = remember(jsonBytes) {
    jsonBytes.decodeToImageBitmap()
}

从CMP 1.7.0开始,所有多平台资源都被打包到Android assets中。Res.readBytes() 接收 composeResources 目录内的文件路径。

六、Web端资源处理

6.1 自动字体回退(CMP 1.12.0)

这是CMP 1.12.0为Web平台带来的重要改进。此前,应用加载的字体未涵盖的字符会被显示为替换字形(□,即“豆腐块”)。现在,当渲染过程中遇到未解析的字符时,Compose Multiplatform for Web会根据需要自动下载所需的Noto字体子集。下载字体后,Compose会对受影响的文本进行重组。

这意味着日文、阿拉伯文、天城文和表情符号无需开发者手动捆绑字体即可正确渲染。需要注意的是,在获取到所需字体之前,“豆腐块”可能会短暂出现。

6.2 资源预加载

Web资源通过Fetch API异步加载。在初始加载或慢速网络连接时,资源获取可能导致视觉瑕疵,如FOUT(无样式文本闪烁)或显示占位符。CMP提供两种预加载策略:

浏览器原生预加载:在 wasmJsMain/resources/index.html 的 <head> 中添加 <link> 标签:

<link rel="preload" href="./composeResources/username.shared.generated.resources/font/FiraMono-Regular.ttf" as="fetch" type="font/ttf" crossorigin/>

CMP预加载API:CMP 1.8.0引入了实验性API用于预加载字体和图片资源:

// 预加载字体
preloadFont(Res.font.custom_font)

// 预加载图片
preloadImageBitmap(Res.drawable.hero_image)
preloadImageVector(Res.drawable.app_logo)

即使浏览器已预加载资源为原始字节,它们仍需要转换为适合渲染的格式(如 FontResource、DrawableResource)。CMP资源库内置了高级表示缓存,预加载API可以进一步优化这一转换过程。

6.3 Web资源路径映射

通过 configureWebResources() 函数可以指定Web资源的路径和URL:

// 映射到应用特定路径
configureWebResources {
    resourcePathMapping { path -> "/myApp/resources/$path" }
}

// 映射到外部CDN
configureWebResources {
    resourcePathMapping { path -> "https://mycdn.com/myApp/res/$path" }
}

下面是 Web 端资源加载与预加载流程:

mermaid diagram

七、跨平台注意事项与最佳实践

7.1 资源在Android上的打包行为

从CMP 1.7.0开始,所有多平台资源都被打包到Android assets中。这意味着资源不再以传统 res/drawable 形式存在,而是通过CMP的资源加载机制访问。如果项目中同时使用传统Android资源系统和CMP资源系统,需要注意两者的路径隔离。

7.2 资源限定符的已知问题

CMP的资源限定符解析在多次配置变更时可能存在跟踪问题(JetBrains issue #4734)。例如,从“浅色+英语”切换到“深色+法语”时可能显示错误的资源组合。生产环境中建议在目标平台上充分验证多语言+多主题组合的资源解析。

7.3 外部库中的资源

CMP支持从外部库访问资源。当编写供其他模块消费的资源库时,需将 publicResClass = true,并确保 generateResClass 配置正确,使依赖方能够访问生成的 Res 类。

7.4 Web端资源缓存

CMP资源库内置了资源的高级表示缓存(如 FontResource、DrawableResource),避免每次访问都重新解码。浏览器端还会对已下载的资源进行HTTP缓存。建议在开发阶段禁用缓存验证资源更新,生产环境保持默认缓存策略。

配套习题(15题)

第一组:配置与目录结构(4题)

第1题 CMP资源库的核心设计理念是( )

A. 各平台使用各自的资源系统 B. 资源统一存放在composeResources目录,构建时自动生成类型安全的Res类 C. 通过反射动态加载资源 D. 使用XML配置资源路径

答案:B

解析:CMP资源管理的核心设计是资源统一存放在composeResources目录中,构建时自动生成类型安全的Res类,开发者通过Res.drawable.xxx、Res.string.xxx等属性访问资源,无需关心底层平台的资源加载机制。

第2题 CMP资源目录中,字符串资源应放在哪个目录?( )

A. drawable B. font C. values D. files

答案:C

解析:CMP资源目录结构规则:图片放在drawable目录,字体放在font目录,字符串放在values目录,其他文件放在files目录。

第3题 composeResources/files/ 目录中是否可以创建子文件夹层级?( )

A. 不可以,只能放平铺文件 B. 可以,支持任意文件夹层级 C. 只允许一层子文件夹 D. 只能放JSON文件

答案:B

解析:files目录支持任意文件夹层级,适合存储JSON配置文件、音频、PDF等非结构化资源。需要注意,files目录不生成类型安全访问器,需要通过Res.readBytes()手动读取。

第4题 在CMP 1.10.0+中,添加资源库依赖的推荐方式是( )

A. 使用compose.components.resources别名 B. 在版本目录中显式声明org.jetbrains.compose.components:components-resources C. 使用反射加载 D. 无需添加依赖

答案:B

解析:CMP 1.10.0起依赖别名已弃用,应在版本目录中显式声明坐标:org.jetbrains.compose.components:components-resources。

第二组:资源限定符(4题)

第5题 drawable-en-rUS-mdpi-dark 表示( )

A. 英语(美国)区域、160 DPI屏幕、深色主题下的图片 B. 法语(法国)区域、320 DPI屏幕、浅色主题下的图片 C. 英语(英国)区域、480 DPI屏幕、深色主题下的图片 D. 西班牙语(美国)区域、160 DPI屏幕、浅色主题下的图片

答案:A

解析:en表示英语,rUS表示美国区域,mdpi表示160 DPI屏幕密度,dark表示深色主题。限定符可以组合使用,Compose Multiplatform根据当前环境选择匹配的资源。

第6题 关于中文的资源限定符目录,以下说法正确的是( )

A. 只需创建values-zh B. 只需创建values-b+zh+Hans C. 需要同时创建values-zh和values-b+zh+Hans D. 中文不需要单独的资源目录

答案:C

解析:当一种语言有多个文字系统时,除了脚本特定的目录(如values-b+zh+Hans、values-b+zh+Hant),还需要添加无脚本目录(values-zh),否则系统报告locale无脚本时资源无法解析而崩溃。

第7题 以下哪个不是CMP资源限定符支持的类型?( )

A. 语言(en、fr) B. 主题(dark、light) C. 屏幕密度(mdpi、hdpi) D. 网络状态(wifi、cellular)

答案:D

解析:CMP资源限定符支持语言代码、区域代码、主题(light/dark)、屏幕密度(mdpi、hdpi等)。网络状态不是资源限定符的支持类型。

第8题 values/strings.xml 和 values-fr/strings.xml 的关系是( )

A. 两者内容必须完全相同 B. values/ 是默认语言资源,values-fr/ 是法语翻译资源 C. values-fr/ 会覆盖 values/ 的所有内容 D. 两者不能同时存在

答案:B

解析:values/ 目录存放默认语言(通常是英语)的字符串资源,values-fr/ 存放法语翻译。当系统locale为法语时,使用values-fr/中的翻译;其他locale回退到values/。必须始终包含不带语言和区域限定符的values/目录。

第三组:Res类与资源访问(4题)

第9题 要重新生成 Res 类,应该( )

A. 手动创建Res.kt文件 B. 再次构建项目或在IDE中重新导入项目 C. 运行专门的Gradle任务 D. 重启IDE

答案:B

解析:设置好资源后,构建项目会自动生成Res类。要重新生成,再次构建项目或在IDE中重新导入项目即可。

第10题 publicResClass = false 的含义是( )

A. 不生成Res类 B. 生成的Res类默认为internal,仅在模块内可见 C. Res类中的资源不可用 D. Res类只能被Android访问

答案:B

解析:publicResClass = false(默认值)使生成的Res类为internal,仅在模块内可见。设为true时Res类对外公开,适用于资源库作为KMP模块被其他模块依赖的场景。

第11题 访问XML矢量图资源应使用哪个函数?( )

A. painterResource() B. imageResource() C. vectorResource() D. stringResource()

答案:C

解析:vectorResource() 返回 ImageVector,用于访问XML矢量图。painterResource() 返回Painter(通用),imageResource() 返回ImageBitmap(光栅图),stringResource() 用于字符串。

第12题 读取 composeResources/files/config.json 的正确方式是( )

A. File("files/config.json").readText() B. Res.readBytes("files/config.json") C. resources.get("config.json") D. ClassLoader.getResource("config.json")

答案:B

解析:Res.readBytes() 接收composeResources目录内的文件路径,返回字节数组。这是CMP中读取原始文件的标准方式,跨平台可用。

第四组:Web资源与字体(3题)

第13题 CMP 1.12.0为Web平台引入的自动字体回退功能的作用是( )

A. 自动下载所有字体 B. 当渲染遇到未解析字符时,自动下载所需的Noto字体子集 C. 禁用所有自定义字体 D. 仅支持英语字体

答案:B

解析:CMP 1.12.0的自动字体回退功能在渲染过程中遇到未解析字符时,会自动下载匹配的Noto字体子集,下载后Compose对受影响的文本进行重组。日文、阿拉伯文、天城文和表情符号无需开发者手动捆绑字体即可正确渲染。

第14题 CMP 1.8.0引入的Web端资源预加载API不包括( )

A. preloadFont() B. preloadImageBitmap() C. preloadImageVector() D. preloadString()

答案:D

解析:CMP 1.8.0引入的实验性预加载API包括preloadFont()、preloadImageBitmap()和preloadImageVector()。字符串资源不需要预加载,因为stringResource()是同步的。

第15题 通过 configureWebResources() 将资源映射到外部CDN的正确方式是( )

A. configureWebResources { "/cdn/$path" } B. configureWebResources { resourcePathMapping { path -> "https://mycdn.com/myApp/res/$path" } } C. configureWebResources { cdn = "https://mycdn.com" } D. configureWebResources { externalUrl = "https://mycdn.com" }

答案:B

解析:通过resourcePathMapping lambda 函数指定路径映射规则。使用绝对URL(以http://或https://开头)可以映射到外部CDN。

本课知识点总结

1. 资源库配置与目录结构

CMP通过compose-multiplatform-resources库和Gradle插件支持跨平台资源访问。commonMain/composeResources/目录下按类型组织:drawable(图片,支持JPEG/PNG/Bitmap/WebP和XML矢量图,SVG不支持Android)、font(TTF/OTF/TTC)、values(strings.xml格式字符串)、files(其他文件,支持任意文件夹层级,不生成类型安全访问器)。CMP 1.10.0+中依赖别名已弃用,需在版本目录中显式声明坐标。

2. 资源限定符

通过目录名后缀表达多环境适配:语言(en、fr)、区域(rUS、rGB)、主题(dark、light)、屏幕密度(mdpi、hdpi)。限定符可组合使用,如drawable-en-rUS-mdpi-dark。中文等多文字系统语言需同时提供无脚本目录(values-zh)和脚本特定目录(values-b+zh+Hans),否则资源无法解析而崩溃。必须始终包含不带语言和区域限定符的values/目录作为默认回退。

3. Res类的生成与自定义

构建项目自动生成Res类,提供类型安全的资源访问。可通过compose.resources {}块自定义:publicResClass(默认false,设为true使类公开)、packageOfResClass(自定义包名)、generateResClass(auto/always)。当资源库作为KMP模块被其他模块依赖时,需设置publicResClass = true;当资源库仅通过传递依赖可用时,使用generateResClass = always。

4. 各类资源的访问方式

图片:painterResource()(Painter)、imageResource()(ImageBitmap)、vectorResource()(ImageVector)。字符串:stringResource()(Composable函数,支持模板和复数)。字体:通过FontFamily(Font(Res.font.xxx))使用。原始文件:Res.readBytes()读取字节。CMP 1.7.0起所有资源打包到Android assets。

5. Web端资源处理

自动字体回退(CMP 1.12.0):渲染遇到未解析字符时自动下载Noto字体子集并重组文本,日文、阿拉伯文、天城文和表情符号无需手动捆绑字体。资源预加载:浏览器<link rel="preload">或CMP预加载API(preloadFont()、preloadImageBitmap()、preloadImageVector()),CMP资源库内置高级表示缓存进一步优化转换过程。路径映射:configureWebResources() 支持映射到应用路径或外部CDN。

6. 最佳实践与注意事项

资源限定符在多次配置变更时可能存在跟踪问题(#4734),需在目标平台充分验证。外部库资源需设置publicResClass = true。Web端开发阶段禁用缓存验证资源更新。files目录不生成类型安全访问器,需通过Res.readBytes()手动读取。中文等多脚本语言必须提供values-zh回退目录,否则资源解析失败。androidLibrary目标从AGP 8.8.0起支持资源,需设置androidResources.enable = true。

下一课预告:第16课将进入架构与工程化模块,深入CMP应用架构设计——从MVVM到Clean Architecture,包括分层架构的职责边界、MVI模式在CMP中的落地、Repository模式的数据源抽象、UseCase的组织与测试友好性、多模块架构拆分策略,以及状态管理架构的替代方案。