Kotlin Multiplatform Development Help

Compose Multiplatform 1.7.3 新特性

以下是本功能版本的主要亮点:

完整变更列表请查看GitHub发布说明

依赖项

重大变更

最低AGP版本提升至8.1.0

由于Compose Multiplatform 1.7.0依赖的Jetpack Compose 1.7.0和Lifecycle 2.8.0均不支持AGP 7,升级至1.7.3时需同步升级AGP依赖。

弃用Java资源API,推荐使用多平台资源库

本版本明确弃用compose.ui包中的Java资源API:包括painterResource()loadImageBitmap()loadSvgPainter()loadXmlImageVector()函数,以及ClassLoaderResourceLoader类和相关函数。

建议迁移至多平台资源库 。Java资源虽可继续使用,但无法享受框架提供的增强功能:生成式访问器、多模块支持、本地化等特性。

如需继续访问Java资源,可参考pull request中的实现方案 ,确保代码在升级至1.7.3后仍能正常工作。

iOS原生元素触摸处理新默认行为

在1.7.3之前,Compose Multiplatform无法响应互操作UI视图中的触摸事件。现版本实现了更精细的触摸序列处理逻辑,默认添加初始触摸延迟,使父组件能判断触摸序列是否针对原生视图并作出相应反应。

详见iOS章节说明功能文档

iOS强制禁用最小帧持续时间

为避免开发者忽略高刷新率显示屏的警告提示,现强制要求Info.plist文件中必须包含CADisableMinimumFrameDurationOnPhone属性且值为true ,否则应用将崩溃。

可通过设置ComposeUIViewControllerConfiguration.enforceStrictPlistSanityCheckfalse禁用此检查。

弃用桌面平台Modifier.onExternalDrag

实验性API Modifier.onExternalDrag及相关接口已弃用,推荐使用新的Modifier.dragAndDropTargetDragData接口已移至compose.ui.draganddrop包。

1.7.0版本使用弃用API将触发警告,1.8.0版本将彻底移除onExternalDrag修饰符。

跨平台特性

共享元素过渡动画

新增组件间共享元素的平滑过渡API,特别适用于导航场景,帮助用户追踪UI变化轨迹。详见Jetpack Compose文档

类型安全导航

采用Jetpack Compose的类型安全导航方案,Navigation 2.8.0新API为导航图提供编译时安全保障,效果等同于XML导航的Safe Args插件

详见Google类型安全导航文档

多平台资源

打包至Android资产

多平台资源现打包至Android资产,支持Android Studio为Android源集中的Compose组件生成预览。

同时支持通过简单路径(如Res.getUri("files/index.html") )从WebView和媒体组件直接访问资源。

自定义资源目录

配置DSL新增customDirectory设置,支持关联自定义目录到特定源集,例如使用下载文件作为资源。

多平台字体缓存

将Android字体缓存功能扩展至其他平台,减少Font资源的重复字节读取。

支持多平台测试资源

资源库现支持测试资源,包括:

  • 向测试源集添加资源

  • 使用源集专属的生成式访问器

  • 仅测试运行时打包测试资源

资源映射至字符串ID

各类资源按其文件名映射,例如通过Res.allDrawableResources属性访问所有drawable资源:

Image(painterResource(Res.allDrawableResources["compose_multiplatform"]!!), null)

字节数组转图像API

新增转换函数:

  • decodeToImageBitmap() :JPEG/PNG/BMP/WEBP转ImageBitmap

  • decodeToImageVector() :XML矢量文件转ImageVector

  • decodeToSvgPainter() :SVG转Painter (Android不可用)

详见使用文档

新增通用模块

material3.adaptive:adaptive*

Material3自适应模块现支持通用代码,需在build.gradle.kts中添加显式依赖:

implementation("org.jetbrains.compose.material3.adaptive:adaptive:1.0.0-alpha03")

material3-adaptive-navigation-suite

支持构建自适应导航的Material3套件现支持通用代码。

material3-window-size-class

WindowSizeClass类需添加显式依赖:

implementation("org.jetbrains.compose.material3:material3-window-size-class:1.7.3")

注: calculateWindowSizeClass()函数暂不支持通用代码。

material-navigation

导航库新增通用代码支持,需添加:

implementation("org.jetbrains.androidx.navigation:navigation-compose:2.8.0-alpha10") implementation("org.jetbrains.compose.material:material-navigation:1.7.0-beta02")

Skia升级至Milestone 126

通过Skiko更新Skia版本,变更详情见发布说明

新增绘图API GraphicsLayer

移植Jetpack Compose 1.7.0的新绘图层,支持在任意位置渲染组件内容,适用于动画内容的多场景渲染。详见参考文档

LocalLifecycleOwner移出Compose UI

LocalLifecycleOwner类从Compose UI包移至Lifecycle包,支持独立于Compose UI访问生命周期API。注意:若无Compose UI绑定,实例将无法监听平台特定事件。

iOS平台

改进触摸互操作性

优化iOS互操作视图的触摸处理:

  • 默认延迟150毫秒传递触摸事件

  • 超过移动阈值时父组件拦截序列

  • 无显著移动时由互操作视图独占处理 此行为与原生UIScrollView一致,解决滚动列表内嵌视频播放器等场景的触摸冲突问题。

原生性能提升

结合Kotlin 2.0.20优化:

  • LazyVerticalGrid滚动性能提升约9%,帧丢失减少

  • VisualEffects渲染速度提升3.6倍

  • AnimatedVisibility动画渲染提速约6% 实验性并发标记GC可进一步缩短GC暂停时间。

性能测试代码详见:

桌面平台

拖放功能

实现内容拖入/拖出应用的机制,通过dragAndDropSourcedragAndDropTarget修饰符指定拖放目标。目前仅支持桌面和Android源集,详见Jetpack文档

BasicTextField桌面适配

稳定版BasicTextField2重命名为BasicTextField并适配桌面平台,特性包括:

  • 更可靠的状态管理

  • 新增TextFieldBuffer API

  • 视觉变换与样式API

  • 支持撤销状态的UndoState

ComposePanel渲染设置

新增RenderSettings.isVsyncEnabled参数,禁用垂直同步可降低输入延迟(可能导致画面撕裂),默认保持VSync同步。

Web平台

skiko.js在Kotlin/Wasm中冗余

Kotlin/Wasm应用可移除index.html中的skiko.js以提升加载速度,未来版本将彻底移除。

22 四月 2025