Back to Details

migrate-xml-views-to-jetpack-compose

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
This skill guides through the process of migrating an existing Android XML View to Jetpack Compose. It performs a stable, safe and visually consistent transition by following a structured, 10-step methodology. This skill migrates UI (XML to Jetpack Compose) only.
本技能指导你完成将现有Android XML View迁移至Jetpack Compose的流程。通过遵循结构化的10步方法，实现稳定、安全且视觉一致的过渡。本技能仅负责UI（从XML到Jetpack Compose）的迁移。

Objective

目标

To systematically convert a single legacy XML layout into modern, declarative Jetpack Compose UI while maintaining pixel-perfect visual parity and functional integrity.
在保持像素级视觉一致性和功能完整性的前提下，将单个传统XML布局系统地转换为现代声明式Jetpack Compose UI。

Summary of the 10-step migration process

10步迁移流程概述

  1. Identify the optimal XML candidate for migration
  2. Analyze the project and layout
  3. Create a plan
  4. Capture the XML View UI
  5. Set up Compose dependencies and compiler
  6. Set up Compose theming
  7. Migrate the XML layout to Compose
  8. Validate the migration
  9. Replace usages
  10. XML code removal
  1. 确定最优的XML迁移候选对象
  2. 分析项目与布局
  3. 制定迁移计划
  4. 捕获XML View的UI
  5. 配置Compose依赖与编译器
  6. 配置Compose主题
  7. 将XML布局迁移至Compose
  8. 验证迁移结果
  9. 替换原有引用
  10. 删除XML代码

Detailed steps

详细步骤

Step 1: Identify the optimal XML candidate for migration

步骤1：确定最优的XML迁移候选对象

If the user has explicitly specified a target XML layout, proceed to Step 2. Otherwise, analyze the codebase to identify the best candidate for migration by following the logic in references/identify-optimal-xml-candidate.md.
如果用户已明确指定目标XML布局，则直接进入步骤2。否则，按照references/identify-optimal-xml-candidate.md中的逻辑分析代码库，确定最佳迁移候选对象。

Step 2: Analyze the project and layout

步骤2：分析项目与布局

Analyze the identified XML View's structure, hierarchy, and implementation details. Use references/analysis-of-the-project-and-layout.md to guide your technical audit of the layout and surrounding project context.
分析已确定的XML View的结构、层级和实现细节。使用references/analysis-of-the-project-and-layout.md指导你对布局及项目周边环境进行技术审计。

Step 3: Create a plan

步骤3：制定迁移计划

Using the outputs and analysis done in the Step 1 and 2, generate a step-by-step plan for the migration. If you support user interaction, present to the user and ask for approval before proceeding. If user interaction is not supported, proceed to Step 4 following the generated plan.
利用步骤1和步骤2的输出结果与分析内容，生成迁移的分步计划。如果支持用户交互，将计划呈现给用户并在继续前获得批准。如果不支持用户交互，则按照生成的计划进入步骤4。

Step 4: Capture the XML View UI

步骤4：捕获XML View的UI

IF you support user interaction, ask the user to upload a screenshot of the XML View UI or provide an absolute path to a file. Use this image as a visual reference for the layout migration in Step 7. ELSE IF you are able to run an Android emulator, locate an existing screenshot test for the XML candidate. If none exists, create one using the existing project testing framework. If no framework exists, use UI Automator or Espresso to create a screenshot test with minimum required setup. Run the test and take a baseline screenshot of the XML UI. ELSE proceed to Step 5.
如果支持用户交互，请用户上传XML View UI的截图或提供文件的绝对路径。将此图片作为步骤7中布局迁移的视觉参考。 否则，如果你能够运行Android模拟器，查找该XML候选对象现有的截图测试。如果不存在，则使用现有项目测试框架创建一个。如果没有测试框架，则使用UI Automator或Espresso创建一个最低配置的截图测试。运行测试并获取XML UI的基准截图。 否则直接进入步骤5。

Step 5: Set up Compose dependencies and compiler

步骤5：配置Compose依赖与编译器

Check 
build.gradle
or 
libs.versions.toml
for Compose dependencies and compiler setup. If missing, use Setup Compose Dependencies and Compiler. Run a sync to ensure dependencies resolve without errors.
检查
build.gradle
或
libs.versions.toml
中的Compose依赖与编译器配置。如果缺失，请参考Setup Compose Dependencies and Compiler进行配置。执行同步操作确保依赖项可正常解析。

Step 6: Set up Compose theming

步骤6：配置Compose主题

If the project already has Compose theming set up, proceed to Step 7. If Compose theming is missing, initialize it. For Material-based projects, follow Material 3 migration guidelines. For custom design systems, apply expert judgment to migrate XML theming and match existing styles. Constraints: Do not migrate the entire theme. Implement only the minimum theming required for the specific XML candidate. Maintain original XML themes for interoperability. Maintain existing project code conventions, patterns, names and values.
如果项目已配置Compose主题，则直接进入步骤7。如果未配置Compose主题，则进行初始化。对于基于Material的项目，请遵循Material 3迁移指南。对于自定义设计系统，请运用专业判断迁移XML主题并匹配现有样式。 约束条件： 不要迁移整个主题。仅实现该XML候选对象所需的最少主题配置。保留原始XML主题以保证互操作性。遵循现有项目的代码规范、模式、命名和取值。

Step 7: Migrate the XML View to Compose

步骤7：将XML布局迁移至Compose

Convert the XML candidate to Jetpack Compose code, referencing references/xml-layout-migration.md and the image from Step 4. You must include a Compose Preview for the newly created composable to facilitate visual verification.
参考references/xml-layout-migration.md和步骤4中的图片，将XML候选对象转换为Jetpack Compose代码。必须为新创建的可组合函数添加Compose Preview，以便进行视觉验证。

Step 8: Replace usages

步骤8：替换原有引用

Replace the usages of the migrated XML layout to use the new Compose component.
  • To add Compose in Views, use Compose in Views.
  • To add Views in Compose, use Views in Compose.
将原有XML布局的引用替换为新的Compose组件。
  • 如需在Views中添加Compose，请参考Compose in Views。
  • 如需在Compose中添加Views，请参考Views in Compose。

Step 9: Validate the migration

步骤9：验证迁移结果

Compare the baseline screenshot image from Step 4 with the rendered Compose Preview of the new composable. Ignore string content; focus on layout and styling. Iterate on the Compose code until visual parity is achieved. Once verified, write a Compose UI test for the new composable.
将步骤4中的基准截图与新可组合函数的Compose Preview渲染效果进行对比。忽略字符串内容，重点关注布局和样式。反复调整Compose代码直至实现视觉一致性。验证完成后，为新可组合函数编写Compose UI测试。

Step 10: XML code removal

步骤10：删除XML代码

Delete the migrated XML file and its associated legacy tests. Caution: Only remove code and resources that are not referenced by other parts of the project.
删除已迁移的XML文件及其相关的传统测试。注意： 仅删除未被项目其他部分引用的代码和资源。