migrate-xml-views-to-jetpack-compose

此技能将指导你完成将现有 Android XML View 迁移到 Jetpack Compose 的流程。通过遵循结构化的 10 步方法，实现稳定、安全且视觉效果一致的迁移。此技能仅迁移 UI（XML 到 Jetpack Compose）。

目标

系统地将单个旧版 XML 布局转换为现代的声明式 Jetpack Compose UI，同时保持像素级的视觉一致性和功能完整性。

10 步迁移流程概要

1. 确定最适合迁移的 XML 候选项
2. 分析项目和布局
3. 制定计划
4. 捕获 XML View UI
5. 设置 Compose 依赖项和编译器
6. 设置 Compose 主题
7. 将 XML 布局迁移到 Compose
8. 验证迁移
9. 替换用法
10. 删除 XML 代码

详细步骤

步骤 1：确定最适合迁移的 XML 候选项

如果用户明确指定了目标 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 依赖项和编译器。如果缺少，请使用 Setup Compose Dependencies and Compiler。运行同步，确保依赖项解析无误。

步骤 6：设置 Compose 主题

如果项目已设置 Compose 主题，则继续执行步骤 7。如果缺少 Compose 主题，则进行初始化。对于基于 Material 的项目，请遵循 Material 3 migration guidelines。 对于自定义设计系统，请运用专业判断迁移 XML 主题并匹配现有样式。 **约束：**不要迁移整个主题。仅实现特定 XML 候选项所需的最低限度主题。保留原有 XML 主题以确保互操作性。遵循项目现有的代码约定、模式、名称和值。

步骤 7：将 XML View 迁移到 Compose

将 XML 候选项转换为 Jetpack Compose 代码，参考 references/xml-layout-migration.md 和步骤 4 中的图像。 必须为新创建的可组合项添加 Compose Preview，以便进行视觉验证。

第 8 步：替换用法

将已迁移 XML 布局的用法替换为新的 Compose 组件。

• 要在 View 中添加 Compose，请参阅 在 View 中使用 Compose。
• 要在 Compose 中添加 View，请参阅 在 Compose 中使用 View。

第 9 步：验证迁移

将第 4 步中的基准截图与新可组合项渲染出的 Compose Preview 进行比较。忽略字符串内容，重点关注布局和样式。不断调整 Compose 代码，直至视觉效果一致。验证通过后，为新的可组合项编写 Compose UI 测试。

第 10 步：移除 XML 代码

删除已迁移的 XML 文件及其相关旧版测试。注意： 仅移除项目其他部分未引用的代码和资源。