把 dependencies.gradle.kts 里的 Compose BOM 改成 2026.11.01 后,先别急着使用 Modifier.blur。这次升级最先要确认的是两道工具链门槛:Kotlin 必须达到 2.2 或更高版本,compileSdk 必须达到 37.1;任何一项没有满足,都不能把它当作一次普通的依赖替换。
掘金文章将这次更新概括为“改动不算大,但功能比较实用”:核心 Compose 模块升级到 1.13,Material 3 到达 1.5.0 稳定版,同时加入渐进式模糊、多边形形状,以及状态计算、列表缓存、退出动画和重组追踪方面的改进。 从项目升级角度看,这些能力不必一次全部接入。更稳妥的顺序是先解决版本兼容,再统一依赖,最后按业务逐项启用新 API,并用旧系统、连续交互和性能数据验证回归。
1.13 先把版本门槛和功能边界摊开
2026 年 11 月稳定版将核心 Compose 模块升级至 1.13,对应 Compose BOM 2026.11.01;官方同时明确,这次升级要求 Kotlin 2.2+ 和 compileSdk 37.1。 对已有 Android 项目来说,Kotlin 版本和编译目标属于硬条件,而不是可选的新功能开关。低版本 Kotlin 应先完成工具链升级,compileSdk 低于 37.1 时则需要安装对应 SDK 平台并调整构建配置。具体 DSL 会随 Android Gradle Plugin 版本变化,应以当前工程支持的写法为准,不要直接照搬其他项目的 compileSdk 配置片段。
BOM 也不意味着所有 Compose 组件的版本都会变成 1.13。BOM 2026.11.01 会统一映射核心模块的版本,其中 Material 3 已更新到 1.5.0 稳定版;其他组件应以官方完整 BOM 映射为准。 如果项目直接声明了某个 androidx.compose.* 依赖并固定版本,它还可能参与 Gradle 的版本冲突解析。比较稳妥的做法是让 BOM 管理版本,只保留确实需要覆盖的特殊依赖。
这次升级最明显的一项图形能力是渐进式模糊。它基于绘制阶段的 lambda,通过 Modifier.blur { ... } 和 BlurRadiusSpec 描述从清晰到模糊的过渡,可用于线性渐变、径向聚光,也可以接入自定义 AGSL RuntimeShader 生成动态模糊映射;对话框和弹出式窗口也增加了直接配置模糊属性的能力。 它适合图片底边渐隐、标题与背景融合、触摸位置驱动的径向聚光等场景,但它不是通用的“整屏毛玻璃开关”。
多边形相关 API 则补上了 Compose 绘图能力中的常见缺口。PolygonShape 是常规 Compose Shape,可以配合 Modifier.clip 或组件的形状参数使用,并自动适配布局尺寸;MorphPolygonShape 会在绘制阶段读取动画进度,在两个多边形之间插值,不必为了进度变化触发重组。 如果旧代码为了圆角多边形、星形或形状变形而引入了 androidx.graphics:graphics-shapes、手动创建 RoundedPolygon 并转换成 Path,现在值得重新评估是否可以直接使用这些 API。
状态、列表和动画方面,掘金文章列出的 computedStateOf、LazyLayoutCacheWindow 和 CapturedAnimatedVisibility 更偏向解决日常工程问题。 computedStateOf 面向“输入频繁变化,但输出通常只有少量有效状态”的场景;LazyLayoutCacheWindow 将列表预加载和离屏保留交给布局统一控制,并允许按可视区域比例调节;CapturedAnimatedVisibility 则用于处理退出动画与 Composition 生命周期的衔接,并在最后一帧完成退出动画后及时移出 Composition。 此外,Perfetto 可以用于追踪从一次 State 写入到对应 Recomposition 的路径,为定位无谓重组提供了更直接的入口。
渐进式模糊还受一项系统条件限制:其运行门槛是 Android 13,也就是 API 33;它作用于组件自身内容,不能直接模糊组件后方的内容,因此不能单独等同于完整毛玻璃效果。 升级 Compose 依赖也不会让旧系统自动获得新的系统平台接口,旧设备必须准备静态效果、渐变遮罩或其他回退方案。 如果需求本身就是模糊组件后方内容,那属于另一类背景渲染效果,而不是本文讨论的渐进式模糊。
官方发布说明还涉及文本、布局、性能更新,以及弃用和行为变化。 本文引用的资料只概括了这些类别,没有逐项列出全部具体 API,因此不应根据二手文章猜测弃用名称。实际升级时需要以官方完整说明、编译器警告和实际行为为准。
按这个顺序把现有项目升到 1.13
第一步,建立升级前基线。已有 Compose 项目应创建独立升级分支,保留当前 BOM、Kotlin、AGP 和 compileSdk 配置,并记录关键页面截图、交互结果、帧表现、内存占用和依赖解析结果。依赖图可以直接导出:
./gradlew :app:dependencies --configuration releaseRuntimeClasspath > dependencies-before.txt
如果项目没有 release 变体,应替换成实际存在的配置。新项目不需要做前后对比,但仍然要固定工具链版本,并从一开始使用 BOM 管理 Compose 依赖。
第二步,先升级工具链,再改 Compose 依赖。将 Kotlin Gradle 插件升级到 2.2 或更高版本,并把编译目标调整到 compileSdk 37.1。 这一阶段应先确保整个多模块项目能够稳定构建,避免在排查 Compose API 错误时混入 Kotlin 插件、Gradle Wrapper、AGP 或其他 AndroidX 库的兼容问题。本文引用的资料没有列出 AGP 的最低版本,遇到工具链报错时应对照对应版本的官方兼容矩阵,而不是盲目升降级。
第三步,统一 Compose 依赖。BOM 声明应改为:
dependencies {
implementation(platform("androidx.compose:compose-bom:2026.11.01"))
}
如果项目直接使用 Material 3,可以保留无版本声明,让 BOM 提供版本:
dependencies {
implementation("androidx.compose.material3:material3")
}
随后分别检查 Material 3、UI 和 Foundation 的实际解析版本:
./gradlew :app:dependencyInsight --dependency androidx.compose.material3:material3 --configuration releaseRuntimeClasspath
./gradlew :app:dependencyInsight --dependency androidx.compose.ui:ui --configuration releaseRuntimeClasspath
./gradlew :app:dependencyInsight --dependency androidx.compose.foundation:foundation --configuration releaseRuntimeClasspath
重点不是只看声明版本,而是检查最终选中版本、是否存在固定版本覆盖,以及不同模块是否解析到了不一致的 Compose 依赖。核心模块应按官方 BOM 映射解析到 1.13,Material 3 则应核对到 1.5.0。 先完成构建和现有功能冒烟测试,再开始接入新能力。
第四步,迁移渐进式模糊时先确定效果边界。图片底边渐隐可以采用类似下面的线性渐变规格:
// size 为目标绘制区域的尺寸
val blurRadiusSpec = BlurRadiusSpec.linearGradient(
start = DpOffset.Zero,
end = DpOffset(size.width, size.height),
BlurStop(fraction = 0f, radius = 0.dp),
BlurStop(fraction = 0.5f, radius = 0.dp),
BlurStop(fraction = 0.75f, radius = 14.dp),
BlurStop(fraction = 1f, radius = 28.dp),
)
这种配置让前 50% 保持清晰,随后逐步增加模糊半径,适合标题图片向背景过渡。径向聚光效果可以把渐变中心与触摸坐标关联;需要更复杂的动态映射时,再评估自定义 AGSL RuntimeShader。AGSL 提供更多自由度,采用自定义 RuntimeShader 时也必须同时观察绘制耗时和低端设备上的帧表现。
系统版本判断应放在效果入口,不能依赖升级后的默认表现:
val canUseProgressiveBlur =
Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU
if (canUseProgressiveBlur) {
// 渐进式模糊
} else {
// 渐变遮罩、静态模糊或其他回退效果
}
旧系统分支至少要保证图片仍可识别、对话框和弹出式窗口不出现空白或布局错位。对话框与弹出式窗口新增的模糊配置也应分别验证遮罩、圆角、点击区域和内容层级,不能只测试普通页面中的图片。
第五步,简化多边形实现。规则多边形、星形以及尺寸会随布局变化的自定义图形,可以优先评估 PolygonShape,确认效果后再移除旧项目中的路径转换代码。MorphPolygonShape 更适合两个形状之间的连续形变:把动画进度接入其进度 lambda 后,形变在绘制阶段读取进度,不需要为此单独触发重组。 迁移时应在不同尺寸、裁剪边界以及动画被中断的场景下检查结果,尤其要确认图形没有因为尺寸计算方式变化而出现裁切或跳变。
第六步,用 computedStateOf 简化稳定状态判断。典型的“列表是否已经离开顶部”可以写成:
val listState = rememberLazyListState()
val showBackToTop by remember {
computedStateOf {
listState.firstVisibleItemIndex > 0
}
}
这里的关键不是简单把 derivedStateOf 换成另一个名字,而是失效策略不同。computedStateOf 更适合轻量条件,并按计算结果是否相等决定依赖它的 Composition 是否需要失效;derivedStateOf 的无 policy 重载在依赖发生变化时仍会触发更新,如果需要在结果相等时跳过更新,还要使用带 SnapshotMutationPolicy 的重载。
因此不要机械替换所有 derivedStateOf。对于简单布尔条件、滚动阈值和轻量映射,可以优先评估 computedStateOf;对于复杂映射或重计算逻辑,则应根据结果相等性、缓存失效和依赖变化成本单独判断。升级后可用 Perfetto 观察一次列表滚动究竟触发了哪些 State 写入和 Recomposition,而不是只看代码形式。
第七步,调整列表缓存和退出动画。LazyLayoutCacheWindow 适合调整列表预加载和离屏保留策略,尤其在长列表、复杂条目或图片较多时,可以按可视区域比例调节提前加载范围。 调节前应先保留基线数据,因为扩大缓存范围可能减少条目在滚动时的即时创建,也可能增加内存占用。判断标准应是帧表现、滚动响应和内存三者一起改善,而不是只看某一项数字。
CapturedAnimatedVisibility 可以用于退出过程中不应长期留在 Composition 中的内容,让最后一帧继续完成退出动画,再及时释放组合状态。 应重点测试快速连续操作,例如关闭详情页的同时清空选中项,避免出现旧画面闪回、动画卡住或状态更新顺序颠倒。
第八步,把重组路径纳入性能排查。升级前后使用 Perfetto 记录相同操作路径,比较 State 写入、失效传播和 Recomposition 的发生位置。 如果列表已经滚到第十项,后面的索引变化仍然频繁发生,但“返回顶部”按钮始终为可见状态,那么应优先修正派生状态的失效方式,而不是继续叠加新的状态缓存。工具升级和新 API 接入应分开提交,这样性能变化才有明确的对照基线。
发版前逐项测试兼容风险
发版测试不能只看“能否编译”。建议至少建立下面这组矩阵:
| 测试维度 | 最低覆盖范围 | 重点观察 |
|---|---|---|
| API 33 及以上 | 主流设备或模拟器 | 渐进式模糊、径向聚光、多边形形变、对话框和弹出式窗口 |
| 低于 API 33 | 仍有用户量的旧系统设备 | 回退效果、空白、崩溃、布局错位和点击区域 |
| 常见屏幕尺寸 | 紧凑、普通与大屏设备 | 模糊渐变范围、多边形裁剪、弹窗尺寸和文字布局 |
| 连续业务路径 | 列表到详情再返回 | 状态清理、列表缓存、返回顶部按钮和退出动画 |
| 性能路径 | 长列表、图片密集页和快速滚动 | 帧表现、内存、重组频率和首次绘制 |
渐进式模糊应分别在 API 33 及以上和更低系统上验证,低版本不能以“没有效果但仍能运行”为验收标准,而应保证回退方案仍然成立。
状态与动画的连续路径需要单独测试。可以按音乐列表场景模拟:用户滚动列表后出现“回到顶部”按钮,再进入歌曲详情,关闭详情并立即清空当前选中歌曲,观察状态更新、列表缓存和退出动画是否保持一致。 只测试单个页面的正常流程,往往发现不了这类跨组件生命周期问题。
Material 3 已到 1.5.0 稳定版,升级后应重新走一遍项目已经使用的主题、按钮、弹窗、列表和动画页面,并保存升级前后的截图对照。 验收时不必预设某个组件一定发生了变化,重点是用户实际看到的尺寸、排版、颜色、遮罩和动画是否偏离原有基线。
对于官方提到的文本、布局、性能更新以及弃用和行为变化,应逐项对照完整发布说明,而不是只确认项目能够通过编译。 编译警告应全部处理;对无法立即修改的弃用项,要记录影响范围和后续处理时间。对存在行为差异的组件,应同时准备低、中、高三个 Android 版本下的验证结果。
性能对比至少保留四类数据:关键交互的帧表现、内存占用、State 写入到 Recomposition 的路径,以及升级前后的截图。Perfetto 能帮助定位重组链路,但不能替代设备上的真实帧率和内存测量。 如果新 API 在单个页面上改善明显,却让长列表内存持续升高,就不应因为新版本“更先进”而直接全量采用。
发布策略上,应保留独立升级提交、测试记录和最终依赖版本。高风险图形效果或列表策略可以通过功能开关逐步启用;一旦出现回归,可以先关闭新能力,再恢复 BOM、工具链和相关配置。 这样可以把“依赖升级造成的兼容问题”和“新功能实现问题”分开定位。
升级任务可用下面这份清单逐项核对:
- [ ] 已记录升级前的依赖图、关键截图、交互结果和性能基线。
- [ ] Kotlin 已达到 2.2 或更高版本,
compileSdk已达到 37.1。 - [ ] Compose BOM 已改为
2026.11.01,并通过依赖图确认核心模块和 Material 3 的实际解析版本。 - [ ] 已清理或核对项目中单独声明的 Compose 固定版本。
- [ ] 已逐项检查官方发布说明中的弃用项、行为变化、文本、布局和性能更新。
- [ ] 已在 API 33 及以上环境验证渐进式模糊、多边形和弹窗效果。
- [ ] 已在低版本系统验证回退方案,不出现空白、崩溃或布局错位。
- [ ] 已覆盖列表滚动、返回顶部、进入详情、关闭详情、清空状态和退出动画的连续路径。
- [ ] 已对比升级前后的截图、帧表现、内存和 Recomposition 路径。
- [ ] 已保留独立升级提交、功能开关和可执行的回退方案。
建议先选一个非核心页面完成最小升级,让它依次通过构建、功能回归、旧系统测试和性能对比,再决定是否全量发布。Jetpack Compose 1.13 的价值不在于 API 数量突然增加,而在于它为模糊、形状、状态和列表处理中的若干工程问题提供了更直接的能力;这些变化应逐项验证、按业务需要启用,让采用范围保持可控,无需为了版本号把所有代码一次性重写。
[email protected]
。
我们承诺在核实信息后,将第一时间删除相关内容或断开链接。
























暂无评论内容