Cordova Android 应用如何保持沉浸模式并正确适配软键盘

在Cordova开发的Android应用中，实现沉浸模式的同时保证软键盘适配正常，需要协调系统配置、Cordova插件和前端逻辑三个部分，避免出现沉浸模式失效或者输入框被遮挡的问题。

一、基础配置调整

1. AndroidManifest配置

首先需要修改AndroidManifest.xml中对应Activity的窗口软键盘模式，避免软键盘弹出时重置沉浸状态。打开platforms/android/app/src/main/AndroidManifest.xml，找到启动Activity的配置，添加或修改android:windowSoftInputMode属性：

<activity
    android:name=".MainActivity"
    android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"
    android:windowSoftInputMode="adjustResize|stateAlwaysHidden"
    android:theme="@style/Theme.AppCompat.NoActionBar">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

这里的adjustResize会让软键盘弹出时调整应用布局大小，避免遮挡输入框；stateAlwaysHidden保证初始状态软键盘不弹出，不会干扰沉浸模式初始化。

2. 沉浸式状态栏配置

如果使用的是cordova-plugin-statusbar插件，需要在config.xml中添加对应配置，保证状态栏沉浸效果稳定：

<preference name="StatusBarOverlaysWebView" value="true" />
<preference name="StatusBarBackgroundColor" value="#00000000" />
<preference name="StatusBarStyle" value="lightcontent" />

二、核心插件使用

推荐使用cordova-plugin-android-immersive插件来稳定维护沉浸模式，避免软键盘弹出时沉浸状态被系统重置。首先安装插件：

cordova plugin add cordova-plugin-android-immersive

安装完成后，在应用启动完成后初始化沉浸模式，代码如下：

document.addEventListener('deviceready', function() {
    // 开启沉浸模式，包含状态栏和导航栏隐藏
    AndroidImmersive.enableImmersiveMode(
        AndroidImmersive.FLAG_IMMERSIVE_STICKY,
        AndroidImmersive.SYSTEM_UI_FLAG_LAYOUT_STABLE |
        AndroidImmersive.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION |
        AndroidImmersive.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN |
        AndroidImmersive.SYSTEM_UI_FLAG_HIDE_NAVIGATION |
        AndroidImmersive.SYSTEM_UI_FLAG_FULLSCREEN
    );
}, false);

该插件的FLAG_IMMERSIVE_STICKY模式会让用户从边缘滑动时临时显示系统栏，几秒后自动恢复隐藏，不会打断应用的交互流程。

三、软键盘适配补充逻辑

1. 输入框焦点处理

为了保证输入框获取焦点时软键盘正常弹出，且布局调整正确，可以添加以下前端逻辑：

// 监听输入框获取焦点事件，主动滚动到可视区域
document.querySelectorAll('input, textarea').forEach(function(el) {
    el.addEventListener('focus', function() {
        // 延迟执行，等待软键盘弹出完成
        setTimeout(function() {
            el.scrollIntoView({ behavior: 'smooth', block: 'center' });
        }, 300);
    });
});

2. 软键盘弹出/收起监听

如果需要处理软键盘状态变化时的额外逻辑，可以使用cordova-plugin-ionic-keyboard插件监听键盘事件：

cordova plugin add cordova-plugin-ionic-keyboard

监听代码如下：

// 监听软键盘弹出事件
window.addEventListener('keyboardWillShow', function(event) {
    console.log('软键盘高度：' + event.keyboardHeight);
    // 可以在这里调整布局，避免内容被遮挡
});

// 监听软键盘收起事件
window.addEventListener('keyboardWillHide', function() {
    // 恢复布局状态，重新开启沉浸模式避免失效
    if (typeof AndroidImmersive !== 'undefined') {
        AndroidImmersive.enableImmersiveMode(
            AndroidImmersive.FLAG_IMMERSIVE_STICKY,
            AndroidImmersive.SYSTEM_UI_FLAG_LAYOUT_STABLE |
            AndroidImmersive.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION |
            AndroidImmersive.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN |
            AndroidImmersive.SYSTEM_UI_FLAG_HIDE_NAVIGATION |
            AndroidImmersive.SYSTEM_UI_FLAG_FULLSCREEN
        );
    }
});

四、常见问题排查

• 如果沉浸模式偶尔失效，检查是否有其他插件修改了系统UI状态，优先在键盘收起事件中重新初始化沉浸模式。
• 如果输入框仍然被遮挡，确认android:windowSoftInputMode是否设置为adjustResize，部分全屏主题会默认覆盖该属性。
• 如果应用包含WebView内嵌页面，需要保证页面本身没有设置overflow: hidden等阻止布局调整的属性。

CordovaAndroid沉浸模式软键盘适配修改时间：2026-06-19 09:00:30