Android Material3中CheckBox自定义button显示空白如何解决

问题原因 #

• Material3主题下的CheckBox实际渲染组件为MaterialCheckBox，并非原生框架CheckBox。组件默认会对android:button属性设置的资源应用主题色着色（buttonTint），默认着色模式为SRC_IN，多色自定义图标经过着色处理后会出现显示异常，甚至完全空白。
• MaterialCheckBox默认通过app:buttonCompat属性接管复选框按钮的绘制逻辑，直接设置android:button会和内部绘制逻辑冲突，导致资源无法正常加载渲染。
• 原有selector资源仅覆盖了启用状态下的选中/未选中逻辑，未匹配禁用等其他状态，状态切换时也可能出现显示错乱。

相关资源参考 #

选中状态自定义图标：

未选中状态自定义图标：

运行异常效果（复选框空白）：

正确实现方案 #

方案1：快速适配现有代码（最小改动） #

直接修改CheckBox布局属性，关闭默认的compat绘制接管和tint着色即可：

注意：布局根节点需要声明xmlns:app="http://schemas.android.com/apk/res-auto"命名空间

<CheckBox
    android:id="@+id/checkRememberMe"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginTop="40dp"
    android:text="记住我"
    android:button="@drawable/ic_checkbox"
    app:buttonCompat="@null"
    app:buttonTint="@null"
    android:paddingStart="8dp" />

同时优化selector资源，补全全状态匹配，避免状态切换异常，优化后的ic_checkbox.xml代码如下：

<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 选中禁用状态，无对应图标可复用启用状态图标加透明度 -->
    <item
        android:drawable="@drawable/checkbox_on_disabled"
        android:state_checked="true"
        android:state_enabled="false"/>
    <!-- 未选中禁用状态，无对应图标可复用启用状态图标加透明度 -->
    <item
        android:drawable="@drawable/ic_checkbox_off_disabled"
        android:state_checked="false"
        android:state_enabled="false"/>
    <!-- 选中启用状态 -->
    <item
        android:drawable="@drawable/checkbox_on_enabled2"
        android:state_checked="true"/>
    <!-- 默认未选中启用状态 -->
    <item
        android:drawable="@drawable/ic_checkbox_off_enabled"/>
</selector>

方案2：样式封装（推荐，可复用） #

通过自定义样式统一配置自定义CheckBox属性，避免每个布局重复写属性，适合多页面复用场景：

1. 在样式文件中新增自定义CheckBox样式，继承Material3默认CheckBox父样式：

<style name="Widget.App.CheckBox.Custom" parent="Widget.Material3.CompoundButton.CheckBox">
    <item name="buttonCompat">@null</item>
    <item name="buttonTint">@null</item>
    <item name="android:button">@drawable/ic_checkbox</item>
    <!-- 可按需调整图标与文字间距 -->
    <item name="android:paddingStart">8dp</item>
</style>

2. 布局中给CheckBox应用该样式即可：

<CheckBox
    android:id="@+id/checkRememberMe"
    style="@style/Widget.App.CheckBox.Custom"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginTop="40dp"
    android:text="记住我"/>

注意事项 #

• 如果自定义图标为矢量图（VectorDrawable），需要在模块级build.gradle中开启矢量图兼容配置：

android {
    defaultConfig {
        vectorDrawables {
            useSupportLibrary true
        }
    }
}

• 多色自定义图标不要设置android:buttonTint或app:buttonTint属性，否则图标会被染为单一纯色。

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