Compose Multiplatform 1.10 发布：统一 Preview、Navigation 3、Hot Reload 三箭齐发

2026 年 3 月 16 日，JetBrains 正式发布 Compose Multiplatform 1.10.2，这是一次里程碑式的更新。统一的 @Preview 注解、Navigation 3 跨平台支持、开箱即用的 Hot Reload——每一项都直击开发者痛点。

一句话总结

Compose Multiplatform 1.10 = 统一 Preview + Navigation 3 + Hot Reload，跨平台 UI 开发进入新阶段。

01 统一的 @Preview 注解

这可能是最让人兴奋的变化之一。

之前写 Compose Multiplatform 项目，预览注解要在不同的 source set 中使用不同的包名：

// ❌ 以前的混乱局面
// Android 端
import androidx.compose.ui.tooling.preview.Preview

// Desktop 端
import androidx.compose.desktop.ui.tooling.preview.Preview

// 跨平台 commonMain
import org.jetbrains.compose.ui.tooling.preview.Preview

现在，一个注解走天下：

// ✅ 现在只需要一个
import androidx.compose.ui.tooling.preview.Preview

@Preview
@Composable
fun MyScreenPreview() {
    MyScreen()
}

直接在 commonMain 中使用 androidx.compose.ui.tooling.preview.Preview，旧的注解已被标记为废弃。

告别混乱的 import，这才是跨平台该有的样子。

02 Navigation 3 跨平台支持

Jetpack Navigation 3 正式登陆 Compose Multiplatform！新增三个跨平台构件：

// Navigation 3 多平台依赖
org.jetbrains.androidx.navigation3:navigation3-ui
org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-navigation3
org.jetbrains.compose.material3.adaptive:adaptive-navigation3

各平台的特殊适配也很贴心：

iOS 端——端边缘滑动手势管理：

通过 EndEdgePanGestureBehavior 控制端边缘（LTR 布局的右边缘）的滑动手势
默认禁用，避免与业务手势冲突

Web 端——键盘导航：

按下 Esc 键即可返回上一屏
同时支持关闭对话框、弹窗和 Material 3 SearchBar

浏览器历史导航和地址栏集成将在后续版本跟进。

03 PredictiveBackHandler 正式废弃

Android 14 引入的预测性返回手势一直是跨平台适配的痛点。1.10 中，旧的 PredictiveBackHandler 正式废弃，取而代之的是更清晰的 Navigation Event API。

Before：

// ❌ 旧 API —— 回调逻辑混在 try-catch 中
PredictiveBackHandler(enabled = true) { progress ->
    try {
        progress.collect { event ->
            // 处理手势进度动画
        }
        // ✅ 手势完成
    } catch (e: Exception) {
        // ❌ 手势取消
    }
}

After：

// ✅ 新 API —— 职责分离，逻辑清晰
val navState = rememberNavigationEventState(
    NavigationEventInfo.None
)

NavigationBackHandler(
    state = navState,
    isBackEnabled = true,
    onBackCancelled = { /* 手势取消 */ },
    onBackCompleted = { /* 手势完成 */ }
)

LaunchedEffect(navState.transitionState) {
    val state = navState.transitionState
    if (state is NavigationEventTransitionState.InProgress) {
        val progress = state.latestEvent.progress
        // 用 progress 驱动动画
    }
}

核心变化：

维度	旧 API	新 API
完成/取消	try-catch 区分	独立回调 onBackCompleted / onBackCancelled
进度追踪	Flow collect	TransitionState 状态观察
状态管理	无	NavigationEventState 保存 UI 状态

04 开箱即用的 Hot Reload

Compose Hot Reload 不再需要手动配置插件，现已内置到 Compose Multiplatform Gradle 插件中。

桌面应用默认启用
最低要求 Kotlin 2.1.20
已有项目可安全移除显式的 Hot Reload 插件声明

// ❌ 不再需要手动添加
plugins {
    id("org.jetbrains.compose-hot-reload") // 可以删了
}

// ✅ Compose 插件自带
plugins {
    id("org.jetbrains.compose")  // Hot Reload 已内置
}

改代码，保存，立刻看到效果。这才是 2026 年该有的开发体验。

05 iOS 重要更新

5.1 Window Insets 支持

现在支持 WindowInsetsRulers，可以基于状态栏、导航栏、软键盘等窗口内边距来定位和调整 UI 元素。

5.2 自定义 IME 配置

通过 PlatformImeOptions 实现：

UIResponder.inputView：替换系统键盘为自定义输入视图
UIResponder.inputAccessoryView：在键盘上方添加自定义辅助视图

5.3 互操作视图叠加

新增实验性 placedAsOverlay 标志：

@OptIn(ExperimentalComposeUiApi::class)
UIKitViewController(
    modifier = modifier,
    factory = { createNativeMap() },
    properties = UIKitInteropProperties(
        placedAsOverlay = true  // 渲染在 Compose UI 之上
    )
)

地图、视频播放器等原生视图现在可以更自然地叠加在 Compose UI 之上。

5.4 互操作视图自动调整大小

UIKit 互操作视图支持根据 intrinsicContentSize 自动调整大小，包括通过 UIHostingController 包装的 SwiftUI 视图。

06 其他值得关注的更新

Web 端资源缓存

使用 Web Cache API 缓存静态资产
应用启动或页面刷新时自动清理缓存

Skia 升级至 M138

从 M132 大幅升级，带来渲染性能和功能改进

Popup / Dialog 属性稳定化

以下属性从实验性提升为稳定状态：

DialogProperties.usePlatformInsets
DialogProperties.scrimColor
PopupProperties.usePlatformDefaultWidth
PopupProperties.usePlatformInsets

AGP 9.0.0 兼容

需升级到 CMP 1.9.3 或 1.10.0

07 迁移注意事项

Kotlin 版本要求：

如果项目包含 native 或 web 目标，需升级到 Kotlin 2.2.20
Hot Reload 最低要求 Kotlin 2.1.20

依赖别名废弃：

compose.ui、compose.material3 等 Gradle 插件依赖别名已废弃
建议改用版本目录（Version Catalog）中的直接库引用
未来将提供 BOM 简化依赖管理

写在最后

Compose Multiplatform 1.10 是一次质变级的更新：

统一 @Preview 消除了跨平台预览的碎片化
Navigation 3 让导航逻辑真正实现一次编写、多端运行
内置 Hot Reload 大幅提升桌面端开发效率
iOS 互操作增强 让混合开发更加顺滑

如果你正在做 KMP 项目，现在就是升级的好时机。

你的项目升级到 1.10 了吗？遇到了什么问题？欢迎在评论区交流。