第14课完成了平台互操作的学习。本课深入CMP资源管理体系:
compose-multiplatform-resources库与Gradle插件配置、composeResources目录结构规范、资源限定符与多环境适配、Res类的生成与自定义、图片/字符串/字体/原始文件的访问方式、字符串国际化与多语言目录组织,以及Web端自动字体回退与资源预加载。本课内容基于CMP 1.12.1与Kotlin 2.3.20。 文末附有15道配套习题与本课知识点总结。
目录
- 一、为什么需要跨平台资源管理
- 二、依赖配置与目录结构
- 三、资源限定符:多环境适配
- 四、Res 类的生成与自定义
- 五、各类资源的访问方式
- 六、Web端资源处理
- 七、跨平台注意事项与最佳实践
- 配套习题(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 资源管理的整体架构流程图:
二、依赖配置与目录结构
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
}
}
下面是资源目录的组织结构图:
三、资源限定符:多环境适配
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/ 目录(用于保存默认字符串)。如果将所有字符串文件都放入带限定符的目录中,且设备语言不在支持列表中,应用在该设备上运行时会崩溃。
下面是资源限定符的匹配流程:
四、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 // 默认:仅在有显式依赖时生成
}
| 配置项 | 默认值 | 说明 |
|---|---|---|
publicResClass | false(internal) | 设为 true 使 Res 类对外可见 |
packageOfResClass | {group}.{module}.generated.resources | 自定义生成类的包名 |
generateResClass | auto | always 无条件生成;auto 仅在有显式资源依赖时生成 |
使用场景:当资源库作为KMP模块被其他模块依赖时,需要将 publicResClass = true 才能在其他模块中访问;当资源库仅通过传递依赖可用时,使用 generateResClass = always。
下面是 Res 类的生成与自定义流程:
五、各类资源的访问方式
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 端资源加载与预加载流程:
七、跨平台注意事项与最佳实践
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的组织与测试友好性、多模块架构拆分策略,以及状态管理架构的替代方案。