全屏模式下PWA软键盘与导航栏重叠问题求助

我之前开发基于xterm.js的Web终端PWA时，刚好踩过一模一样的坑，给你分享下我整理的问题根源和可行的解决方案：

问题根源与官方态度 #

你遇到的两个核心问题，本质是Chromium和Firefox对PWA fullscreen 显示模式的适配缺陷：

• 安卓原生软键盘（IME）弹出时，浏览器不会自动调整viewport尺寸，直接覆盖终端内容，导致输入区域完全不可用
• 软键盘弹出时系统导航栏会重叠在应用顶部，完全浪费了全屏的空间

切换到standalone模式虽然能正常适配软键盘，但又没法利用全屏空间，确实是个两难的局面。我之前查过官方的内部工单，他们把这个标记为极低优先级，理由是fullscreen API原本主要是给视频、游戏这类场景设计的，暂时没有修复计划，Firefox那边也存在同样的问题。另外你的应用是iframe封装的，这也会增加样式调整的难度，很多常规的viewport调整方案会因为iframe的上下文限制失效。

可行的解决方案思路 #

如果你不想用内置HTML5虚拟键盘（OSK），想继续兼容原生IME同时解决viewport适配问题，我有几个实测有效的思路：

1. 利用VisualViewport API手动调整布局 #

通过监听视觉视口的变化，手动调整终端容器的高度，规避软键盘遮挡的问题。如果是iframe封装的应用，需要在iframe内部或者父页面监听这个事件：

// 在终端所在的上下文（iframe或父页面）添加监听
window.visualViewport.addEventListener('resize', () => {
  const terminalContainer = document.getElementById('xterm-container');
  // 直接设置终端容器高度为视觉视口高度
  terminalContainer.style.height = `${window.visualViewport.height}px`;
  // 触发xterm.js重新渲染，确保内容适配新尺寸
  terminal.fit();
  // 自动滚动到终端底部，保证输入区域可见
  terminal.scrollToBottom();
});

这个方法需要注意不同安卓版本和浏览器的兼容性，部分老设备可能需要结合window.innerHeight做降级处理。

2. 动态切换PWA显示模式 #

在用户聚焦终端输入框时，临时把manifest的display切换为standalone，输入完成后再切回fullscreen：

// 监听终端输入聚焦事件
terminal.on('focus', () => {
  // 获取当前manifest链接
  const manifestLink = document.querySelector('link[rel="manifest"]');
  fetch(manifestLink.href)
    .then(res => res.json())
    .then(manifest => {
      manifest.display = 'standalone';
      // 创建临时manifest文件并替换原链接
      const blob = new Blob([JSON.stringify(manifest)], { type: 'application/json' });
      manifestLink.href = URL.createObjectURL(blob);
      // 触发PWA更新，部分浏览器需要手动刷新
      window.location.reload();
    });
});

// 监听终端失焦事件，切回全屏模式
terminal.on('blur', () => {
  // 同理，把manifest.display改回fullscreen后刷新
  // 这里可以复用上面的逻辑，就不重复写了
});

这个方法的缺点是会有页面刷新的体验损耗，但能在输入时保证viewport正常适配，平时保持全屏状态。

3. 使用沉浸式全屏API替代manifest配置 #

放弃manifest的fullscreen设置，改用Web的沉浸式全屏API，这个模式下部分浏览器会自动适配软键盘：

// 进入沉浸式全屏，隐藏导航栏
function enterImmersiveFullscreen() {
  if (document.documentElement.requestFullscreen) {
    document.documentElement.requestFullscreen({
      navigationUI: 'hide'
    });
  }
}

// 在应用启动时调用
enterImmersiveFullscreen();

// 监听全屏变化，确保导航栏保持隐藏
document.addEventListener('fullscreenchange', () => {
  if (!document.fullscreenElement) {
    enterImmersiveFullscreen();
  }
});

这个模式下系统导航栏会在用户交互时暂时显示，平时隐藏，同时部分浏览器在软键盘弹出时会自动调整viewport，但同样需要针对不同设备做兼容性测试。

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