Android自定义Toolbar展开菜单后菜单项为空的问题

问题现象 #

应用内集成自定义Toolbar，Toolbar自身的标题、背景都能正常渲染，但是点击触发溢出菜单展开后，所有菜单项都呈现无内容的空白状态，看不到代码里定义的菜单标题文本。

现有实现代码 #

菜单配置文件 toolbar_menu.xml #

<menu 
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item
        android:id="@+id/about"
        android:title="About"
        app:showAsAction="never"/>
</menu>

页面布局 activity_layout.xml #

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:visibility="visible"
    tools:context=".MainActivity">

    <androidx.appcompat.widget.Toolbar
        android:id="@+id/toolbar"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:background="?attr/colorPrimary"
        android:minHeight="?attr/actionBarSize"
        android:theme="?attr/actionBarTheme"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:title="Welcome"/>

    <!-- 其他页面控件在此处定义 -->

</androidx.constraintlayout.widget.ConstraintLayout>

页面逻辑 MainActivity.java #

// 导入相关依赖
public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(final Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main_activity);

        Toolbar toolbar = findViewById(R.id.toolbar);
        setSupportActionBar(toolbar);
    }

    @Override
    public boolean onCreateOptionsMenu(final Menu menu) {
        getMenuInflater().inflate(R.menu.toolbar_menu, menu);
        return true;
    }
}

问题原因与修复方案 #

• 这个空白显示本质是菜单项的文字颜色和弹出菜单的背景颜色完全一致，导致内容视觉上不可见：
  • 现有代码中Toolbar直接绑定了?attr/actionBarTheme，这个主题默认会让菜单文字采用和Toolbar标题一致的浅色（通常为白色，适配Toolbar本身的深色colorPrimary背景）；但代码没有单独给Toolbar关联的弹出溢出菜单指定主题，弹出菜单默认采用白色背景，白字落在白底上就会呈现完全空白的效果。
  • 具体修复时，只需要给Toolbar的弹出菜单单独配置主题即可，常见实现方式：
    • 直接使用系统内置的主题快速修复
      给Toolbar补充app:popupTheme属性，指定弹出菜单的样式为浅色系，比如：

      <androidx.appcompat.widget.Toolbar
          ...
          android:theme="?attr/actionBarTheme"
          app:popupTheme="@style/ThemeOverlay.AppCompat.Light"/>
      

      这个配置下，弹出菜单会采用浅白背景、深灰文字的默认样式，不需要额外写自定义代码就能正常显示内容。
    • 自定义菜单弹出样式
      如果需要调整菜单的文字大小、选中效果等，可以在themes.xml里自定义专属的弹出主题：

      <style name="CustomToolbarPopupTheme" parent="ThemeOverlay.AppCompat.Light">
          <item name="android:textColor">@color/your_menu_text_color</item>
          <item name="android:background">@color/your_menu_background</item>
      </style>
      

      再把Toolbar的app:popupTheme属性指向这个自定义样式即可。
    • 全局排查主题配置
      如果上述配置修改后仍然空白，需要检查项目全局主题里的文本颜色配置，确认没有被异常设置为白色的全局文本颜色属性，避免连带影响菜单的文字渲染。

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