用途:为 Jetpack Compose 应用提供 edge-to-edge 迁移的结构化流程,解决内容被状态栏、导航栏遮挡以及输入法(IME)遮挡输入框的问题,优先级标注为 P1(HIGH)。
前置条件:项目必须使用 Jetpack Compose;必须面向 SDK 35 及以上,若低于则需将 compileSdk 提升到 35。
主要步骤:一、规划。找出所有 Activity 类,对未调用 enableEdgeToEdge() 的逐个补充;定位需要 inset 处理的列表、FAB 和文本输入框;若存在 TextField/OutlinedTextField,需规划 IME inset 处理。二、启用 edge-to-edge。在每个 Activity.onCreate 的 setContent 之前添加 enableEdgeToEdge();对有软键盘的 Activity 在 AndroidManifest 中添加 android:windowSoftInputMode="adjustResize"。三、应用 insets。每个组件只选一种方式以避免双重 padding:优先使用 Scaffold,将 PaddingValues 传入 content lambda;Material 3 组件(TopAppBar、NavigationBar 等)使用内置 inset 处理;Scaffold 之外使用 Modifier.safeDrawingPadding() 或 windowInsetsPadding。四、处理 IME。在 manifest 中设置 adjustResize(不要用已废弃的 SOFT_INPUT_ADJUST_RESIZE),给内容容器添加 imePadding() 或 fitInside(WindowInsetsRulers.Ime.current),且 imePadding 要放在 verticalScroll() 之前。五、列表与 FAB。inset padding 应施加到 LazyColumn/LazyRow 的 contentPadding,而不是父级的 Modifier.padding();Scaffold 内的 FAB 自动处理,Scaffold 外的 FAB 使用 safeDrawingPadding()。
验证清单:每个 Activity 都调用 enableEdgeToEdge();键盘相关 Activity 在 manifest 中设置 adjustResize;文本框具备 IME inset 处理;列表项可通过 contentPadding 滚动到系统栏之后;./gradlew build 构建成功。
反模式:不要在同一内容上同时使用 contentWindowInsets = WindowInsets.safeDrawing 与 imePadding(),否则 IME 打开时会出现双重 padding;不要给列表父级加 padding,否则会裁剪滚动内容;不要使用已废弃的 SOFT_INPUT_ADJUST_RESIZE。更多 RIGHT/WRONG 代码示例见其 inset patterns 参考。具体官方文档与更多细节暂未提供。