在 Compose 中将 XML 主题迁移到 Material 3

在现有应用中引入 Compose 时，您需要迁移 Material XML 主题才能对 Compose 组件使用 MaterialTheme。这意味着应用的主题将会有 2 个可信来源：基于 View 的主题以及 Compose 主题。样式上的任何更改都需要在多处实施。应用完全迁移到 Compose 后，请移除 XML 主题设置。

您可以使用 Material Theme Builder 工具迁移颜色。

开始从 XML 迁移到 Compose 时，请将主题迁移到 Material 3 Compose 主题。

术语库

术语 定义
MaterialTheme 为 Compose 界面组件提供主题（颜色、排版、形状）的可组合函数。
Shape 一个 Compose 对象，用于为 MaterialTheme 定义自定义组件形状。
Typography 用于为 MaterialTheme 定义自定义文本样式（字体系列、大小、粗细）的 Compose 对象。
Color 用于为 MaterialTheme 定义自定义配色方案的 Compose 对象。
XML 主题 View 系统使用的在 XML 文件中定义的 Android 主题设置系统。

限制

在迁移之前，请注意以下限制：

  • 本指南仅重点介绍如何迁移到 Material 3。如需了解如何从其他设计系统迁移，请参阅 Material 2 或 Compose 中的自定义设计系统。
  • 最终目标是完全迁移到 Compose，这样就可以移除 XML 主题设置。本指南介绍了如何迁移，但未介绍如何最终移除 XML 主题设置。

第 1 步：评估设计系统

确定 XML 视图项目中使用的设计系统。 分析迁移路径和必要步骤，以便在 Compose 中将现有设计系统迁移到 Material 3。

第 2 步：确定主题源文件

确定并找到主题设置所需的所有 XML 资源和文件：浅色和深色配色方案、主题、形状、尺寸、排版、样式和其他相关文件。

字符串等资源可按原样重复使用，无需迁移。

第 3 步：迁移颜色

将深色和浅色配色方案从 XML 迁移到 Material 3 Compose 中的等效方案。

第 4 步：迁移自定义形状和排版

  • 如果您的应用使用自定义形状：

    1. 在 Compose 代码中，定义一个 Shape 对象来复制 XML 形状定义。

    2. 将此 Shape 对象提供给 MaterialTheme。

      如需了解详情，请参阅形状。

  • 如果您的应用使用自定义排版：

    1. 在您的 Compose 代码中，定义一个 Typography 对象，以复制 XML 文本样式和字体定义。

    2. 将此 Typography 对象提供给 MaterialTheme。

      如需了解详情，请参阅排版。

第 5 步：验证主题迁移

始终使用原始 XML 主题中的现有主题值作为 Compose 中新 Material 主题的真实来源。在迁移期间，切勿创建新的主题值，以保持品牌一致性并避免视觉效果退化。

验证所有新的 Compose 主题值是否与现有的 XML 值一致。 请勿对任何迁移的值进行硬编码。