技能介绍

要解决的问题

App 在浅色与深色模式间切换时，系统状态栏的文字颜色不跟随主题：浅色模式下背景为白色，文字仍为白色，状态栏内容几乎不可见。问题根源在国产 ROM（小米 MIUI、魅族 Flyme）对系统状态栏 API 的定制：@capacitor/status-bar 的 StatusBar.setStyle() 在这些设备上可能被系统 UI 覆盖，导致文字颜色切换静默失效。深色模式看似正常，实际只是碰巧匹配，仍然由同一套机制控制。

核心能力与关键步骤

该技能采用双保险策略，同时使用 Capacitor API 与原生 Bridge：

原生桥接层：在 android/app/src/main/java/com/zhimaquan/app/MainActivity.java 中添加 @JavascriptInterface 桥接方法，并在 onCreate 中注册，让 JS 可以直接驱动原生状态栏控制。
JS 调用层：在 src/app/App.jsx 中结合 Capacitor API 与原生 Bridge 调用，根据当前主题设置文字颜色。
重试机制：JS 注册时 WebView 可能尚未就绪，Bridge 调用最多重试 10 次、间隔 100ms。
版本分流：Android 11+ 使用 WindowInsetsController，Android 6-10 使用 SYSTEM_UI_FLAG_LIGHT_STATUS_BAR。
验证：切换浅色（白底深字）与深色（深蓝底白字），反复切换 2-3 次确认稳定。

适用边界与注意点

setOverlaysWebView({ overlay: true }) 绝对不能开，否则深色模式文字同样不可见，只有 overlay 为 false 时策略才有效。
compileSdk 需 >= 30 才能编译 WindowInsetsController；修改 MainActivity.java 后必须执行 npx cap sync android 同步 Java 源文件，再执行 ./gradlew assembleRelease，否则桥接不生效。
只加原生桥接而不在 JS 端主动调用是不够的——桥接只是通道，需要 JS 主动调用。
import 需按需引入，避免一次性导入版本不兼容的类。