将 Android XML View 迁移到…

在 Android 项目中把单个遗留 XML 布局安全、视觉一致地迁移为声明式 Jetpack Compose UI 时使用。

适用场景

解决思路

1. 确定迁移目标：若用户已明确指定 XML 布局则直接进入第 2 步；否则分析代码库，按 references/identify-optimal-xml-candidate.md 的逻辑选出最合适的迁移候选。
2. 分析项目与布局：分析目标 XML View 的结构、层级与实现细节，参考 references/analysis-of-the-project-and-layout.md 对布局及周边项目上下文做技术审计。
3. 制定计划：基于第 1、2 步的分析结果生成分步迁移计划；若支持用户交互，先展示给用户并请求批准后再继续，否则按计划直接进入第 4 步。
4. 捕获 XML View UI：若支持用户交互，请用户上传 XML View UI 的截图或提供文件的绝对路径，作为第 7 步布局迁移的视觉参照；否则若能运行 Android 模拟器，查找该 XML 候选已有的截图测试，若不存在则用项目现有测试框架创建，若没有框架则用 UI Automator 或 Espresso 以最小必要配置创建截图测试，运行测试并截取 XML UI 的基线截图；否则直接进入第 5 步。
5. 配置 Compose 依赖与编译器：检查 build.gradle 或 libs.versions.toml 中的 Compose 依赖与编译器配置，若缺失则参考 references/android/develop/ui/compose/setup-compose-dependencies-and-compiler.md 进行配置，并运行 sync 确保依赖解析无错误。
6. 配置 Compose 主题：若项目已配置 Compose 主题则进入第 7 步；若缺失则初始化。基于 Material 的项目遵循 references/android/develop/ui/compose/designsystems/migrate-xml-theme-to-compose.md 的 Material 3 迁移指南；自定义设计系统则凭专家判断迁移 XML 主题并匹配现有样式。约束：不要迁移整个主题，只实现该 XML 候选所需的最小主题；保留原有 XML 主题以维持互操作性；保持项目现有的代码约定、模式、命名与取值。
7. 迁移 XML View 到 Compose：参考 references/xml-layout-migration.md 和第 4 步的截图，将 XML 候选转换为 Jetpack Compose 代码，并且必须为新创建的 composable 添加 Compose Preview 以便视觉验证。
8. 替换使用处：将迁移后的 XML 布局的使用处替换为新的 Compose 组件。在 Views 中使用 Compose 参考 references/android/develop/ui/compose/migrate/interoperability-apis/compose-in-views.md；在 Compose 中使用 Views 参考 references/android/develop/ui/compose/migrate/interoperability-apis/views-in-compose.md。
9. 验证迁移：将第 4 步的基线截图与新 composable 渲染出的 Compose Preview 对比，忽略字符串内容，聚焦布局与样式，迭代修改 Compose 代码直到视觉一致；验证通过后为新 composable 编写 Compose UI 测试。
10. 删除 XML 代码：删除已迁移的 XML 文件及其关联的遗留测试。注意：只删除未被项目其他部分引用的代码与资源。

适用边界 · 注意事项

• 仅迁移 UI（XML 到 Jetpack Compose），不涉及非 UI 逻辑的迁移。
• 不要迁移整个主题，只实现该 XML 候选所需的最小主题，并保留原有 XML 主题以维持互操作性。
• 删除 XML 文件及遗留测试时，不要删除被项目其他部分引用的代码或资源。