企业官网建设流程全解析

1. 为什么我决定把项目全面切到 Material Design 3

去年下半年接手一个存量的 Android 项目，界面还停留在 Material Design 2 那套视觉语言上，主题色写死在colors.xml里，按钮圆角、阴影、字体全部靠自定义 drawable 硬堆。产品那边提了个需求，说要支持深色模式跟随系统、要能换主题色、还要在折叠屏上不出错。我第一反应是这活儿用 MD2 那套东西做起来会非常别扭，因为 MD2 的色彩体系是静态的，深色模式基本靠手动维护两套资源，换主题色更是要重新生成一堆色值。

后来花了两天时间把 Material Design 3（下称 M3）的设计规范和 Android 侧的com.google.android.material库文档过了一遍，结论很明确：M3 的动态色彩（Dynamic Color）、基于 tonal palette 的色彩体系、以及组件层面的 token 化改造，正好对上产品提的这几个需求。于是决定把项目整体迁移到 M3，而不是打补丁。

这篇文章就是这次迁移的完整复盘。我会讲清楚 M3 在 Android 上到底改了哪些东西、主题体系怎么搭、组件怎么换、动态色彩怎么接、迁移过程中踩了哪些坑。适合两类人看：一类是手上有个 MD2 老项目想升级的，另一类是新项目想直接按 M3 规范起步的。哪怕你只写过几个页面，跟着文里的步骤也能把一套 M3 主题跑起来。

先说清楚一个前提：M3 不是换个库版本就完事的东西，它是一整套设计语言的重构。色彩、排版、形状、组件形态、状态层（state layer）全都变了。你要是只把material库升到 1.9 以上然后什么都不改，界面不会崩，但你会得到一套“看起来还是 MD2、但某些组件偷偷变了样”的缝合怪。所以迁移的核心不是升级依赖，而是重建主题体系。

2. M3 到底改了什么：核心概念拆解

2.1 从“主色+辅色”到“角色化色彩系统”

MD2 的色彩模型很简单：一个 primary、一个 primaryVariant、一个 secondary，再加背景和表面色。你在colors.xml里定义，主题里引用，完事。问题在于这套模型表达能力太弱，深色模式要另写一套，组件内部不同状态（hover、pressed、disabled）的颜色也没有统一来源。

M3 换了个思路，叫角色化色彩（Color Roles）。它不再问你“主色是什么”，而是问你“这个颜色在界面里扮演什么角色”。核心角色包括：

• Primary / On Primary / Primary Container / On Primary Container：主操作色及其容器变体
• Secondary / Tertiary：辅助色和强调色，用于区分信息层级
• Surface / On Surface / Surface Variant：表面色体系，承载大部分背景
• Error / On Error：错误态专用
• Outline / Outline Variant：描边色

每个角色都配一个On前缀的“前景色”，专门用于在该角色背景上放文字或图标，保证对比度。这套体系的好处是：组件只认角色，不认具体色值。你换主题色的时候，只需要重新生成一整套角色色值，所有组件自动跟着变。

我实测下来，这套模型最爽的地方是深色模式。M3 的深色模式不是简单地把浅色反相，而是基于同一套 tonal palette 取不同 tone 值。浅色主题下 primary 取 tone 40，深色主题下取 tone 80，这样既保证了对比度，又保持了色相一致性。你不需要维护两套colors.xml，只需要维护一套 tonal palette。

2.2 Tonal Palette：色彩的地基

Tonal palette 是 M3 色彩体系的底层。简单说，就是把一个色相（hue）按明度（tone）从 0 到 100 切成 13 个档位：0、10、20、30、40、50、60、70、80、90、95、99、100。0 是纯黑，100 是纯白，中间是不同明度的同色相颜色。

M3 规定了一套映射规则，比如：

这套映射不是拍脑袋定的，而是为了保证 WCAG 对比度标准。Primary 用 tone 40、On Primary 用 tone 100，对比度足够放白字；深色下反过来，Primary 用 tone 80、On Primary 用 tone 20，同样保证可读性。

注意：不要手动去改这些映射关系。我见过有人觉得 tone 40 太深，硬改成 tone 50，结果 On Primary 的对比度就不够了。要调整观感，应该调色相和饱和度，而不是破坏 tone 映射。

2.3 形状、排版、状态层的同步演进

M3 除了色彩，还有两块变化容易被忽略。

形状（Shape）：M3 定义了五档圆角——None（0dp）、Extra Small（4dp）、Small（8dp）、Medium（12dp）、Large（16dp）、Extra Large（28dp）。组件默认用哪一档是有规定的，比如 Filled Button 用 Full（完全圆角），Card 用 Medium，Dialog 用 Extra Large。你可以在主题里覆盖这些值，但建议先按规范来。

排版（Typography）：M3 把字体样式分成五组——Display、Headline、Title、Body、Label，每组三档（Large/Medium/Small），共 15 种样式。相比 MD2 的 13 种，M3 更强调层级清晰。关键是这些样式现在通过MaterialTheme.typography统一管理，不再散落在各个 style 里。

状态层（State Layer）：这是 M3 新增的概念。组件在 hover、focus、pressed、dragged 状态下，会在内容上叠加一层半透明的 On 色。比如按钮按下时，会在按钮内容上叠一层onPrimary的 12% 透明度。这层叠加是自动的，你不需要手动写 selector。但如果你自定义了组件，就要注意别把这层覆盖掉。

3. 迁移前的准备工作：依赖与主题骨架

3.1 依赖版本怎么选

M3 的 Android 实现主要靠com.google.android.material:material库。关键版本节点：

• 1.5.0：首次引入 M3 组件（当时还是实验性的）
• 1.7.0：M3 组件基本稳定，动态色彩支持完善
• 1.9.0：修复了大量 M3 组件的样式问题，推荐作为起步版本
• 1.11.0：当前较稳定的版本，组件覆盖更全

我的建议是直接上 1.11.0 或更高。低版本有些组件的 M3 样式有 bug，比如MaterialButton在某些版本下圆角不生效，BottomNavigationView的 indicator 动画有问题。升级依赖本身不复杂，但如果你项目里还引用了 AppCompat 的老主题，要注意兼容。

// build.gradle (module level) dependencies { implementation 'com.google.android.material:material:1.11.0' // 如果要用动态色彩，还需要 implementation 'androidx.palette:palette-ktx:1.0.0' }

另外，M3 的很多组件依赖Theme.Material3.*系列主题。如果你项目还在用Theme.MaterialComponents.*，需要先切到 M3 主题，否则组件会 fallback 到 MD2 样式。

3.2 主题文件的结构重构

MD2 时代，主题通常写在一个themes.xml里，颜色写在colors.xml里。M3 建议把主题拆成几个文件，职责分明：

• themes.xml：主题定义，引用 color 和 type
• colors.xml：只放品牌色和 tonal palette 的原始色值
• type.xml：字体样式
• shape.xml：形状定义

我实际迁移时是这么组织的：

<!-- res/values/themes.xml --> <style name="Theme.MyApp" parent="Theme.Material3.DayNight.NoActionBar"> <item name="colorPrimary">@color/md_theme_primary</item> <item name="colorOnPrimary">@color/md_theme_onPrimary</item> <item name="colorPrimaryContainer">@color/md_theme_primaryContainer</item> <item name="colorOnPrimaryContainer">@color/md_theme_onPrimaryContainer</item> <!-- 其余角色同理 --> </style>

这里有个关键点：Theme.Material3.DayNight.NoActionBar这个父主题已经内置了深色模式的切换逻辑。你只需要在values-night/下提供深色版的色值，系统会自动切换。但如果你用了动态色彩，深色模式的色值会由系统根据壁纸生成，这时候values-night里的静态色值只作为 fallback。

3.3 用 Material Theme Builder 生成初始色板

手动算 tonal palette 很痛苦，尤其是要保证对比度。官方提供了 Material Theme Builder（一个网页工具），你输入一个种子色，它会自动生成完整的浅色/深色色板，并导出成 Android 的colors.xml和themes.xml。

我的做法是：拿品牌主色作为种子色，生成一套色板，然后把导出的文件直接放进项目。这样起步阶段就有一套符合规范的色值，不用自己算 tone。后续如果要微调，再手动改个别角色。

实操心得：Theme Builder 导出的文件里，色值命名是md_theme_primary这种格式。建议保留这个命名，不要改成colorPrimary之类的，因为后续如果重新生成色板，直接覆盖文件就行，不用改主题引用。

4. 动态色彩接入：让 App 跟着壁纸变

4.1 动态色彩的原理与限制

动态色彩（Dynamic Color）是 M3 在 Android 12（API 31）引入的能力。系统会从用户壁纸中提取一个种子色，然后用这套算法生成完整的 tonal palette，App 通过DynamicColors.applyToActivitiesIfAvailable()就能拿到这套色值。

限制很明确：只有 Android 12 及以上才支持。Android 11 及以下没有这个能力，只能 fallback 到静态色板。所以你的代码里必须做版本判断。

另一个限制是：动态色彩生成的角色色值，和你品牌色可能差很远。用户壁纸是绿色，你的 App 就变绿了。这对品牌一致性有要求的 App 是个问题。我的处理方式是：提供一个开关，让用户在“跟随系统”和“使用品牌色”之间切换。默认跟随系统，但品牌色作为可选。

4.2 接入代码与版本判断

接入动态色彩的核心代码就几行，但位置很关键——必须在Activity的onCreate里、setContentView之前调用。

// Application 或 BaseActivity 中 override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // 动态色彩：仅 Android 12+ 且用户开启时应用 if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { val dynamicColorEnabled = preferences.getBoolean("dynamic_color", true) if (dynamicColorEnabled) { DynamicColors.applyToActivitiesIfAvailable(this.application) } } setContentView(R.layout.activity_main) }

applyToActivitiesIfAvailable会自动遍历所有 Activity 并应用动态色彩。如果你只想对特定 Activity 生效，可以用DynamicColors.applyToActivityIfAvailable(activity)。

这里有个坑我踩过：如果你在Application的onCreate里调用applyToActivitiesIfAvailable，它注册的是一个ActivityLifecycleCallbacks，会在每个 Activity 的onActivityPreCreated阶段应用。但如果你在BaseActivity的onCreate里调用，要注意调用顺序必须在super.onCreate之后、setContentView之前。顺序错了，主题不会生效。

4.3 动态色彩与静态色板的共存策略

动态色彩开启时，系统会覆盖你主题里定义的所有colorPrimary等角色色值。但有些颜色你可能不想被覆盖，比如错误色（Error）通常希望保持红色，而不是跟着壁纸变。M3 的动态色彩实现里，Error 角色默认是不被覆盖的，这一点设计得比较合理。

但如果你有自定义的品牌色，比如某个特定按钮必须用品牌绿，那就要注意：动态色彩开启后，colorPrimary会变，你的按钮颜色也会变。解决办法是给这个按钮单独定义一个不参与主题的角色，或者直接用固定色值。

<!-- 不参与动态色彩的自定义色 --> <color name="brand_fixed_green">#1B5E20</color>

然后在按钮上直接引用这个色值，而不是用?attr/colorPrimary。代价是这个按钮在深色模式下不会自动适配，需要你手动处理。

5. 组件迁移实操：从 MD2 到 M3 的逐个替换

5.1 按钮体系的重构

MD2 的按钮主要是MaterialButton配app:backgroundTint，样式靠style="@style/Widget.MaterialComponents.Button"区分。M3 把按钮分成了更明确的几种形态：

• Filled Button：主操作，实心背景
• Filled Tonal Button：次主操作，用 secondary container 色
• Outlined Button：中等强调，描边
• Text Button：低强调，纯文字
• Elevated Button：带阴影的填充按钮

迁移时，原来用Widget.MaterialComponents.Button的地方，大部分应该换成Widget.Material3.Button（即 Filled Button）。但要注意，M3 的 Filled Button 默认是完全圆角（pill shape），如果你原来设计是 4dp 圆角，视觉上会有明显变化。

<!-- M3 Filled Button --> <com.google.android.material.button.MaterialButton style="@style/Widget.Material3.Button" android:text="确认" app:icon="@drawable/ic_check" /> <!-- M3 Outlined Button --> <com.google.android.material.button.MaterialButton style="@style/Widget.Material3.Button.OutlinedButton" android:text="取消" />

我迁移时遇到一个细节问题：M3 按钮的insetTop和insetBottom默认值变了，导致按钮实际高度比 MD2 小。如果你的布局对按钮高度有硬性要求，需要显式设置android:minHeight或者调整 inset。

实操心得：不要一次性把所有按钮都换掉。先换一个页面，跑起来看视觉效果，确认没问题再批量替换。M3 按钮的默认内边距和 MD2 不同，批量替换后布局可能会挤。

5.2 卡片与表面色的配合

MD2 的CardView在 M3 里对应MaterialCardView，但样式名变了。M3 的卡片有三种：

• Filled Card：用 surface container 色填充，无阴影
• Elevated Card：带阴影
• Outlined Card：描边

关键变化是：M3 的卡片默认不再用纯白背景，而是用colorSurfaceContainer这类表面容器色。这意味着你的页面背景和卡片背景会有微妙的色差，形成层次感。如果你原来页面背景是白色、卡片也是白色靠阴影区分，迁移后要重新审视这个层次关系。

<com.google.android.material.card.MaterialCardView style="@style/Widget.Material3.CardView.Filled" android:layout_width="match_parent" android:layout_height="wrap_content"> <!-- 内容 --> </com.google.android.material.card.MaterialCardView>

我实测下来，Filled Card 在深色模式下效果最好，因为阴影在深色背景上几乎看不见，靠色差区分层次更可靠。浅色模式下 Elevated Card 也还行，但要注意阴影的 elevation 值，M3 的默认阴影比 MD2 柔和。

5.3 底部导航与 NavigationBar

MD2 的BottomNavigationView在 M3 里建议换成NavigationBar。虽然BottomNavigationView在 material 1.11 里也支持 M3 样式，但NavigationBar是专门为 M3 设计的，支持 indicator 动画、active indicator 色等新特性。

<com.google.android.material.navigation.NavigationBarView android:id="@+id/nav_bar" android:layout_width="match_parent" android:layout_height="wrap_content" app:menu="@menu/bottom_nav_menu" />

迁移时要注意：NavigationBarView的 item 选中态默认有一个 pill 形状的 indicator，颜色是colorSecondaryContainer。如果你原来用的是自定义的选中背景，需要去掉，否则会和 indicator 叠加。

另外，NavigationBarView的高度比BottomNavigationView略高，因为 M3 规范里底部导航的 touch target 更大。如果你的布局里底部导航是固定高度，记得调整。

5.4 输入框与 TextInputLayout 的 M3 样式

TextInputLayout在 M3 里的变化主要是样式名和默认外观。M3 推荐用Widget.Material3.TextInputLayout.OutlinedBox或FilledBox。OutlinedBox 的描边在聚焦时会变成 primary 色，并且描边宽度从 1dp 变成 2dp。

<com.google.android.material.textfield.TextInputLayout style="@style/Widget.Material3.TextInputLayout.OutlinedBox" android:layout_width="match_parent" android:layout_height="wrap_content" android:hint="用户名"> <com.google.android.material.textfield.TextInputEditText android:layout_width="match_parent" android:layout_height="wrap_content" /> </com.google.android.material.textfield.TextInputLayout>

这里有个容易忽略的点：M3 的TextInputLayout默认启用了boxBackgroundMode的自动切换，如果你在代码里动态改了boxBackgroundMode，可能会和样式冲突。我的建议是样式里定死，代码里不要动。

6. 深色模式与主题切换的完整实现

6.1 DayNight 主题的正确用法

M3 的Theme.Material3.DayNight.*已经内置了深色模式支持。你只需要在values-night/下提供深色版的色值，系统会根据AppCompatDelegate.setDefaultNightMode()的设置自动切换。

// 跟随系统 AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM) // 强制浅色 AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO) // 强制深色 AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)

关键点：调用setDefaultNightMode后，系统会重建所有 Activity。所以不要在onCreate里频繁调用，应该在用户切换设置时调用一次。

6.2 动态色彩与深色模式的叠加逻辑

这两个特性叠加时，逻辑要理清楚：

1. 如果动态色彩开启且系统支持，深色模式的色值由系统根据壁纸生成
2. 如果动态色彩关闭，深色模式的色值从values-night/colors.xml读取
3. 如果系统不支持动态色彩（Android 11 以下），无论开关如何，都走静态色板

我的实现是在Application里统一判断：

fun applyTheme() { val dynamicEnabled = preferences.getBoolean("dynamic_color", true) val nightMode = preferences.getInt("night_mode", AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM) AppCompatDelegate.setDefaultNightMode(nightMode) if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S && dynamicEnabled) { DynamicColors.applyToActivitiesIfAvailable(this) } }

注意：DynamicColors.applyToActivitiesIfAvailable是幂等的，多次调用不会出问题。但如果你在动态色彩开启后又关闭，需要重启 Activity 才能恢复静态色板，因为动态色彩一旦应用，会覆盖主题属性。

6.3 主题切换时的状态保持

Activity 重建会导致状态丢失，这是老生常谈的问题。M3 迁移后，因为主题切换更频繁（用户可能随时切深色模式），状态保持更重要。

我的做法是：所有关键状态用ViewModel持有，UI 状态用SavedStateHandle保存。这样 Activity 重建后状态能恢复。另外，RecyclerView的滚动位置用LinearLayoutManager的onSaveInstanceState自动保存，不需要额外处理。

7. 迁移中的常见问题与排查实录

7.1 组件样式不生效的排查顺序

迁移时最常见的问题是“我明明换了 M3 样式，但组件看起来还是老样子”。排查顺序建议如下：

1. 检查父主题：确认 Activity 或 Application 的主题是Theme.Material3.*，不是Theme.MaterialComponents.*
2. 检查依赖版本：material库版本是否 ≥ 1.7.0
3. 检查样式名拼写：M3 样式名是Widget.Material3.Button，不是Widget.MaterialComponents.Button
4. 检查是否有局部 style 覆盖：有些项目在styles.xml里定义了全局的MaterialButton样式，会覆盖组件默认样式
5. 检查是否被动态色彩覆盖：动态色彩开启时，某些颜色会被系统覆盖，看起来像样式没生效

我遇到过一次，排查了半天发现是项目里有个全局的buttonStyle指向了 MD2 的样式，导致所有按钮都不走 M3 默认样式。这种全局 style 在存量项目里很常见，迁移时一定要全局搜索一遍。

7.2 深色模式下对比度不足

M3 的深色模式色值是经过对比度计算的，但如果你自定义了颜色，就可能出问题。典型场景：你在深色模式下用了一个自定义的灰色背景，上面放?attr/colorOnSurface的文字，结果对比度不够。

排查方法：用 Android Studio 的 Layout Inspector 看实际渲染的颜色值，然后手动算对比度。WCAG AA 标准要求正文对比度 ≥ 4.5:1，大字号 ≥ 3:1。

7.3 动态色彩导致的品牌色丢失

前面提过，动态色彩会覆盖colorPrimary。如果你的 App 有强品牌色需求，比如登录页的按钮必须是品牌色，那就要做隔离。

我的方案是：登录页、启动页这类品牌强相关的页面，不应用动态色彩。具体做法是在这些 Activity 里不调用DynamicColors.applyToActivityIfAvailable，或者在onCreate里手动DynamicColors.applyToActivityIfAvailable之前先判断页面类型。

另一种方案是定义一套“品牌固定色”，在主题里单独声明，不参与动态色彩覆盖：

<color name="brand_primary_fixed">#00695C</color>

然后在需要品牌色的地方直接用这个色值。代价是深色模式下要手动提供深色版。

7.4 组件默认内边距变化导致的布局错位

M3 组件的默认内边距和 MD2 不同，这是迁移后布局错位的主要原因。我整理了几个高频组件的变化：

按钮变矮这个问题最隐蔽，因为视觉上只是“感觉按钮小了一点”，但如果你布局里按钮是固定高度，就会导致文字被裁。解决办法是显式设置android:minHeight="48dp"，或者调整app:insetTop和app:insetBottom。

8. 我踩过的坑与实操建议

8.1 不要迷信“一键迁移”

网上有些文章说“把依赖升到 1.9 就自动变 M3”，这是误导。依赖升级只是让你能用 M3 组件，但你的主题、样式、布局如果不改，界面还是 MD2 的样子。真正的迁移工作量在主题重建和组件逐个替换上。

我的项目有 40 多个页面，全部迁移花了大约三周。其中主题体系搭建用了两天，组件替换用了两周多，剩下的是排查各种布局错位和对比度问题。如果你项目页面少，可能一周能搞定，但别指望一两天。

8.2 先做主题，再做组件

顺序很重要。我一开始是先换组件再调主题，结果换完组件发现颜色全不对，又回头调主题，来回折腾。正确顺序是：

1. 先搭好 M3 主题骨架（色板、字体、形状）
2. 在一个页面上验证主题生效
3. 再逐个页面替换组件
4. 最后统一排查布局和对比度

这样每一步都有明确的验证点，不会出现“改了一堆但不知道哪里错了”的情况。

8.3 动态色彩要留开关

动态色彩很酷，但不是所有用户都喜欢。我上线后收到反馈，有用户说“我的 App 怎么变粉色了”，因为他的壁纸是粉色。所以一定要留一个开关，让用户能关掉动态色彩、回到品牌色。这个开关放在设置页，默认开启，但用户可以关。

8.4 用截图对比做回归

迁移过程中，我建了一个截图对比的流程：每个页面迁移前后各截一张图，放在一起对比。这样能快速发现布局错位、颜色偏差、间距变化。工具用的是 Android Studio 的 Layout Inspector 加手动截图，虽然土但有效。

实操心得：截图对比时，一定要在浅色和深色两种模式下各截一次。很多问题只在深色模式下暴露，比如阴影看不见、对比度不足。

8.5 字体缩放要测

M3 的排版体系对字体缩放更敏感，因为字号层级更细。我测试时把系统字体调到最大，发现有些按钮文字被裁了。解决办法是给按钮加android:maxLines="1"和app:autoSizeTextType="uniform"，或者调整布局让文字有足够空间。

9. 迁移后的效果与后续优化方向

全部迁移完成后，最直观的变化是深色模式终于能看了。之前 MD2 的深色模式是手动维护的，有些页面漏了改，深色下白底白字。M3 的角色化色彩体系让深色模式变成“自动正确”，只要主题搭对了，组件自动适配。

第二个变化是主题切换变简单了。以前换主题色要改一堆colors.xml，现在只需要换种子色重新生成色板，或者直接开动态色彩让系统生成。产品后来提了个“节日主题”的需求，我半天就做完了，就是换一套种子色。

后续我打算做的优化：一是把形状和排版也 token 化，现在还有些地方硬编码了圆角和字号；二是把动态色彩的开关做成更细粒度的，比如只让部分页面跟随壁纸；三是补一套 M3 的组件使用规范文档，方便团队新人上手。

最后分享一个小技巧：如果你不确定某个组件在 M3 里该用什么样式，去翻material库的res/values/styles.xml，里面所有Widget.Material3.*的样式都有定义，比看文档快。我迁移时基本是靠翻源码确认样式名的，文档有时候更新不及时。

另外，M3 的规范文档里有个“组件映射表”，列出了 MD2 组件到 M3 组件的对应关系。迁移前先把这个表过一遍，心里有个全局图，比逐个页面摸索效率高得多。