Vue3 Capacitor Android WebView 虚拟导航栏遮挡解决方案

// Capacitor 安全区域适配
const setupSafeArea = async () => {
  try {
    const { Capacitor } = await import('@capacitor/core');

    // 只在原生平台上执行
    if (!Capacitor.isNativePlatform()) {
      console.log('ℹ️ 非原生平台，跳过设置');
      return;
    }

    console.log('🔍 [安全区域] 检测到原生平台，开始设置...');

    // 获取屏幕尺寸
    const screenWidth = window.screen.width;
    const screenHeight = window.screen.height;

    // 通过屏幕比例估算状态栏和导航栏高度
    // 经验值：状态栏 ≈ 4% 屏幕高度，导航栏 ≈ 5% 屏幕高度
    const estimatedStatusBarHeight = Math.min(
      Math.round(screenHeight * 0.04), // 4% 屏幕高度
      50 // 最大 50px
    );
    const estimatedNavBarHeight = Math.min(
      Math.round(screenHeight * 0.05), // 5% 屏幕高度
      56 // 最大 56px
    );

    console.log('🔍 [安全区域] 屏幕尺寸:', screenWidth, 'x', screenHeight);
    console.log('🔍 [安全区域] 估算值 - 状态栏:', estimatedStatusBarHeight, '导航栏:', estimatedNavBarHeight);

    // 设置 CSS 变量
    const root = document.documentElement;
    root.style.setProperty('--sat', `${estimatedStatusBarHeight}px`);
    root.style.setProperty('--sab', `${estimatedNavBarHeight}px`);

    // 更新 body 的 padding
    const body = document.body;
    body.style.paddingTop = `${estimatedStatusBarHeight}px`;
    body.style.paddingBottom = `${estimatedNavBarHeight}px`;

    console.log('✅ [安全区域] 已设置 - 顶部:', estimatedStatusBarHeight, '底部:', estimatedNavBarHeight);
  } catch (e: any) {
    console.log('⚠️ [安全区域] 设置失败:', e.message);
  }
};

// 应用挂载时执行
app.mount('#app').$nextTick(async () => {
  await setupSafeArea();
  // ... 其他初始化逻辑
});

2. CSS 变量应用

将所有使用 env(safe-area-inset-*) 的地方替换为 var(--sat, 0) 和 var(--sab, 0)。

src/style.css

body {
  /* 顶部和底部安全区域通过 JS 动态设置 CSS 变量 */
  padding-top: var(--sat, 0);
  padding-bottom: var(--sab, 0);
  transition: padding-top 0.3s ease, padding-bottom 0.3s ease;
}

/* 页面容器 */
.page-container {
  padding: 16px;
  padding-top: calc(16px + var(--sat, 0));
  padding-bottom: calc(80px + var(--sab, 0));
  min-height: 100vh;
  min-height: 100dvh;
}

src/App.vue

.app-container {
  width: 100%;
  height: 100%;
  min-height: 100vh;
  min-height: 100dvh;
  position: relative;
  padding-top: var(--sat, 0); /* 顶部安全区域 */
  padding-bottom: calc(80px + var(--sab, 0)); /* 底部安全区域 + 导航栏高度 */
  box-sizing: border-box;
}

.tab-bar {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  height: auto;
  min-height: calc(56px + var(--sab, 0));
  display: flex;
  justify-content: space-around;
  align-items: flex-start;
  background: #fff;
  border-top: 1px solid #f0f0f0;
  z-index: 1000;
  padding-top: 10px;
  padding-bottom: calc(10px + var(--sab, 0));
  box-shadow: 0 -2px 8px rgba(0, 0, 0, 0.05);
}

针对具体页面的调整，例如 Login.vue 和 Tasks.vue，只需根据实际布局修改 calc() 中的基数即可。

3. Android 原生层配置

保持沉浸式布局，但关键是要移除隐藏系统栏的标志，让内容延伸到系统栏后面，通过 padding 留出安全区域。

MainActivity.java

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // 启用边缘到边缘显示 (沉浸式)
  WindowCompat.setDecorFitsSystemWindows(getWindow(), false);
  // 设置透明状态栏和导航栏
  setupTransparentSystemBars();
}

private void setupTransparentSystemBars() {
  getWindow().setStatusBarColor(android.graphics.Color.TRANSPARENT);
  getWindow().setNavigationBarColor(android.graphics.Color.TRANSPARENT);

  // 设置窗口标志以实现沉浸式
  int flags = WindowManager.LayoutParams.FLAG_LAYOUT_NO_LIMITS;
  getWindow().setFlags(flags, flags);

  // 设置为边缘到边缘布局，但不隐藏系统栏
  View decorView = getWindow().getDecorView();
  int uiOptions = View.SYSTEM_UI_FLAG_LAYOUT_STABLE
      | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
      | View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION;
  decorView.setSystemUiVisibility(uiOptions);
}

@Override
public void onWindowFocusChanged(boolean hasFocus) {
  super.onWindowFocusChanged(hasFocus);
  if (hasFocus) {
    View decorView = getWindow().getDecorView();
    int uiOptions = View.SYSTEM_UI_FLAG_LAYOUT_STABLE
        | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
        | View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION;
    decorView.setSystemUiVisibility(uiOptions);
  }
}

关键点说明：

• 移除了 SYSTEM_UI_FLAG_FULLSCREEN 和 SYSTEM_UI_FLAG_HIDE_NAVIGATION。
• 移除了 SYSTEM_UI_FLAG_IMMERSIVE_STICKY。
• 只保留 LAYOUT_FULLSCREEN 和 LAYOUT_HIDE_NAVIGATION 实现边缘到边缘布局。
• 不隐藏系统栏，而是让内容延伸过去，依靠 CSS padding 留出安全区域。

4. HTML viewport 配置

确保 index.html 中包含以下 meta 标签以启用全面屏适配：

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />

常见问题解答

为什么 CSS env() 不生效？

CSS 的 env(safe-area-inset-*) 主要是 iOS Safari 引入的特性。Android WebView 和 Chrome 对此支持不完善，往往返回空值。在 Android 上需要手动实现安全区域适配。

为什么使用估算而非精确值？

Capacitor 的 StatusBar 和 NavigationBar 插件虽然能获取精确值，但会增加依赖包体积。为了轻量化，我们使用屏幕比例估算。经验值：状态栏约为屏幕高度的 4%，导航栏约为 5%。同时设置上限避免极端情况（状态栏最大 50px，导航栏最大 56px）。

CSS 变量的优势是什么？

• 一次设置，全局使用
• 支持动态更新
• 保持样式层简洁
• fallback 机制：var(--sat, 0) 确保非原生平台正常显示

沉浸式布局的关键点

• WindowCompat.setDecorFitsSystemWindows(getWindow(), false) 启用边缘到边缘
• 透明状态栏和导航栏
• 使用 LAYOUT_FULLSCREEN 和 LAYOUT_HIDE_NAVIGATION 让内容延伸到系统栏后面
• 不隐藏系统栏，而是通过 padding 留出安全区域

参考资料

• Capacitor 官方文档 - Status Bar
• MDN - CSS env()
• Android Developers - WindowInsets
• Vue 3 + Capacitor 最佳实践