Android Studio预览MDC FloatingActionButton显示异常报错

架构老林

2026-9-1

问题现象

使用Material Components开发时，Android Studio布局预览中FloatingActionButton从正常圆形变为方形，同时抛出主题相关报错，Git回退历史版本问题仍存在，真机运行时组件可正常显示为圆形。

预览异常样式：
真机正常显示效果：
预览报错提示：

核心报错堆栈：

java.lang.IllegalArgumentException: The style on this component requires your app theme to be Theme.AppCompat (or a descendant).
    at com.google.android.material.internal.ThemeEnforcement.checkTheme(ThemeEnforcement.java:243)
    at com.google.android.material.internal.ThemeEnforcement.checkAppCompatTheme(ThemeEnforcement.java:213)
    at com.google.android.material.internal.ThemeEnforcement.checkCompatibleTheme(ThemeEnforcement.java:148)
    at com.google.android.material.internal.ThemeEnforcement.obtainStyledAttributes(ThemeEnforcement.java:76)
    at com.google.android.material.floatingactionbutton.FloatingActionButton.<init>(FloatingActionButton.java:212)
    at com.google.android.material.floatingactionbutton.FloatingActionButton.<init>(FloatingActionButton.java:201)
    at org.jetbrains.android.uipreview.ViewLoader.createNewInstance(ViewLoader.java:339)
    at org.jetbrains.android.uipreview.ViewLoader.loadView(ViewLoader.java:136)
    at com.android.tools.idea.rendering.LayoutlibCallbackImpl.loadView(LayoutlibCallbackImpl.java:301)

已尝试无效操作：

Clean项目后Rebuild
Invalidate Caches/Restart
升级Android Studio至最新版本

当前环境配置：

Gradle版本：7.0.2
Material依赖版本：1.3.0
主题父类：Theme.MaterialComponents.Light.NoActionBar.Bridge

当前主题配置：

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">

    <style name="Theme.Base" parent="Theme.MaterialComponents.Light.NoActionBar.Bridge">
        <item name="colorPrimary">@color/HH_BandColor_1</item>
        <item name="colorPrimaryVariant">@color/HH_BandColor_1</item>
        <item name="colorOnPrimary">@color/white</item>
        <item name="colorSecondary">@color/teal_200</item>
        <item name="colorSecondaryVariant">@color/teal_700</item>
        <item name="colorOnSecondary">@color/black</item>
        <item name="android:statusBarColor" tools:targetApi="l">?attr/colorPrimaryVariant</item>
        <item name="android:forceDarkAllowed">true</item>
    </style>
    <style name="TabRadioButton_center">
        <item name="android:padding">5dp</item>
        <item name="android:gravity">center</item>
        <item name="android:button">@null</item>
        <item name="android:textSize">14sp</item>
        <item name="android:textColor">@color/GrayScale_100</item>
    </style>
    <style name="TabRadioButton_left">
        <item name="android:padding">5dp</item>
        <item name="android:gravity">left</item>
        <item name="android:button">@null</item>
        <item name="android:textSize">14sp</item>
        <item name="android:textColor">@color/GrayScale_100</item>
    </style>
    <declare-styleable name="MaxHeightRecyclerView">
        <attr name="maxHeight" format="dimension" />
    </declare-styleable>
</resources>

解决方案

按以下顺序操作，每步做完刷新布局预览验证，不需要全做：

快速修复预览问题：打开出问题的布局XML，在根布局或者FloatingActionButton控件上添加tools:theme="@style/Theme.Base"属性，确保根节点已经导入tools命名空间xmlns:tools="http://schemas.android.com/tools"。绝大多数场景下加完这行预览会立刻恢复正常。
检查Manifest配置：打开AndroidManifest.xml，确认<application>标签的android:theme属性值为@style/Theme.Base，不要指向其他没有继承AppCompat/Material主题的style。布局预览不会读取Activity代码中setTheme()设置的主题，只会读取Manifest的静态配置，这也是真机正常但预览报错的常见原因。
升级Material依赖版本：你当前使用的material:1.3.0存在多个已知的布局预览兼容性bug，且和新版Android Studio的渲染引擎适配有问题。把依赖替换为适配Gradle7.0.2的稳定版com.google.android.material:material:1.6.1，同步项目后重启预览即可，不需要升级Gradle版本。
切换预览渲染引擎：如果以上操作都无效，打开Android Studio设置，找到Experimental分类，取消勾选Use new Layout Preview rendering engine选项，重启Android Studio。旧版渲染引擎对Material Bridge主题的兼容性更好。

注意：不需要把主题父类改成纯Theme.AppCompat系列，你当前使用的Theme.MaterialComponents.Light.NoActionBar.Bridge本身就是AppCompat的合法子类，堆栈的报错是预览没读到正确主题的误报，改父类会导致Material组件样式丢失。

问题原因

这个问题是Android Studio布局预览渲染引擎的已知bug，和业务代码无关：

真机运行时会走完整的应用启动流程，加载Manifest、代码中设置的全部主题配置，所以组件显示正常
布局预览使用阉割版的layoutlib渲染，不会执行Activity生命周期代码，仅读取XML静态配置、Manifest配置和tools属性，一旦主题拾取链路异常，就会回退到系统默认的基础主题，FAB加载不到Material定义的圆形样式、主题校验不通过就会报对应错误
Git回退代码无效是因为问题本身是Android Studio缓存、渲染引擎或者依赖版本兼容问题，不是提交的代码变更导致的

内容的提问来源于stack exchange，提问作者mhh