Kotlin Multiplatform Development Help

多平台资源的设置与配置

要正确配置项目以使用多平台资源:

  1. 添加库依赖项。

  2. 为每种资源类型创建必要的目录。

  3. 为限定资源创建额外目录(例如,深色UI主题的不同图片或本地化字符串)。

构建脚本与目录设置

要在多平台项目中访问资源,请添加库依赖项并按以下方式组织项目目录中的文件:

  1. composeApp目录的build.gradle.kts文件中,向commonMain源集添加依赖:

    kotlin { sourceSets { commonMain.dependencies { implementation(compose.components.resources) } } }
  2. 在需要添加资源的源集目录中(本例为commonMain )创建新目录composeResources

    Compose资源项目结构
  3. 按以下规则组织composeResources目录结构:

    • 图片应放在drawable目录。Compose Multiplatform支持栅格化图片(JPEG、PNG、位图和WebP)和矢量Android XML图片(不引用Android资源)。

    • 字体应放在font目录。

    • 字符串应放在values目录。

    • 其他文件应放在files目录中,可采用任何合适的文件夹层级。

自定义资源目录

build.gradle.kts文件的compose.resources {}块中,可为每个源集指定自定义资源目录。这些自定义目录也应像默认的composeResources一样包含文件:用drawable子目录存放图片, font子目录存放字体等。

简单示例如下,指向特定文件夹:

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

也可设置由Gradle任务填充的文件夹,例如存放下载的文件:

abstract class DownloadRemoteFiles : DefaultTask() { @get:OutputDirectory val outputDir = layout.buildDirectory.dir("downloadedRemoteFiles") @TaskAction fun run() { /* 下载文件的代码 */ } } compose.resources { customDirectory( sourceSetName = "iosMain", directoryProvider = tasks.register<DownloadRemoteFiles>("downloadedRemoteFiles").map { it.outputDir.get() } ) }

androidLibrary目标中的资源

从Android Gradle插件8.8.0版本开始,可在androidLibrary目标中使用生成的Res类和资源访问器。要启用androidLibrary中的多平台资源支持,请按如下方式更新配置:

kotlin { androidLibrary { experimentalProperties["android.experimental.kmp.enableAndroidResources"] = true } }

限定符

有时,同一资源需根据环境(如语言区域、屏幕密度或界面主题)以不同形式呈现。例如,可能需要为不同语言本地化文本或调整深色主题的图片。为此,该库提供了特殊限定符。

files目录中的原始文件外,所有资源类型都支持限定符。使用连字符将限定符添加到目录名:

多平台资源中的限定符

该库支持以下优先级的限定符: 语言主题密度

  • 可组合应用不同类型的限定符。例如"drawable-en-rUS-mdpi-dark"表示适用于美国地区英语、160 DPI屏幕深色主题的图片。

  • 若无法访问带有所需限定符的资源,则改用不带限定符的默认资源。

语言与区域限定符

可组合语言和区域限定符:

  • 语言由两字母(ISO 639-1)或三字母(ISO 639-2) 语言代码定义。

  • 可在语言代码后添加两字母ISO 3166-1-alpha-2区域代码,区域代码需带小写r前缀,例如: drawable-spa-rMX

语言和区域代码区分大小写。

主题限定符

可添加"light"或"dark"限定符。Compose Multiplatform将根据当前系统主题选择所需资源。

密度限定符

可使用以下密度限定符:

  • "ldpi" – 120 DPI,0.75倍密度

  • "mdpi" – 160 DPI,1倍密度

  • "hdpi" – 240 DPI,1.5倍密度

  • "xhdpi" – 320 DPI,2倍密度

  • "xxhdpi" – 480 DPI,3倍密度

  • "xxxhdpi" – 640dpi,4倍密度

资源选择取决于系统中定义的屏幕密度。

发布

从Compose Multiplatform 1.6.10开始,所有必要资源都包含在发布的Maven制品中。

启用此功能需使用Kotlin 2.0.0或更高版本及Gradle 7.6或更高版本。

下一步?

  • 了解如何访问已设置的资源,以及如何自定义默认生成的访问器,请参阅在应用中使用多平台资源 页面。

  • 查看官方演示项目 ,了解在面向iOS、Android和桌面的Compose Multiplatform项目中如何处理资源。

22 四月 2025