解决 Telegram Web View 在 iOS 上软键盘遮挡输入框的问题

本文介绍如何通过 css 变量与滚动控制，修复 telegram web view（ios）中软键盘弹出时覆盖底部 textarea 的经典兼容性问题。

在 Telegram Web View 中，尤其是 iOS 端（如 iOS 16.1.2 + Telegram 9.3.2），当用户聚焦于底部 或 <input> 元素时，系统软键盘常会错误地遮盖输入区域——即使页面已设置 position: absolute; bottom: 15px，也无法随键盘弹出自动上移。这是因为 Telegram iOS 的 WebView 容器未正确响应 visualViewport 变化，且不触发标准的 resize 或 focusin 布局重排。

✅ 核心解决方案：利用 Telegram 提供的 CSS 自定义属性

Telegram Web Apps 运行时会注入两个关键 CSS 自定义属性：

• --tg-viewport-stable-height：键盘收起时视口高度（即“稳定高度”，通常接近 window.innerHeight）
• --tg-viewport-stable-width：对应稳定宽度（本例中无需）

将容器高度绑定至 --tg-viewport-stable-height，可强制其在键盘弹出时保持“视觉稳定”布局，避免内容被挤压或错位：

.container {
  overscroll-behavior-x: none;
  overscroll-behavior-y: none;
  height: var(--tg-viewport-stable-height, 100vh);
  min-height: var(--tg-viewport-stable-height);
}

⚠️ 注意：

Replit Ghostwrite

一种基于 ML 的工具，可提供代码完成、生成、转换和编辑器内搜索功能。

下载

• overscroll-behavior-* 用于禁用 iOS 滚动回弹（防止键盘触发意外弹性滚动）；
• min-height 是冗余保护，确保在变量未注入时仍具备基础高度；
• 此方案必须作用于最外层容器（如
  ），而非仅 .chat 或 textarea 父元素。

  ? 补充修复：重置滚动位置

  启用上述 CSS 后，部分场景下页面可能出现异常滚动偏移（尤其在键盘收起后）。此时需在 focus 或 input 事件中主动重置滚动：

  document.querySelector('textarea').addEventListener('focus', () => {
    // 强制滚动到顶部，消除因键盘导致的视图偏移
    window.scrollTo(0, 0);
  });

  更健壮的做法是监听 keyboardDidShow / keyboardDidHide（需配合 Telegram WebApp SDK）：

  if (window.Telegram?.WebApp) {
    Telegram.WebApp.onEvent('keyboardDidShow', () => {
      window.scrollTo(0, 0);
    });
    Telegram.WebApp.onEvent('keyboardDidHide', () => {
      window.scrollTo(0, 0);
    });
  }

  ? 注意事项与局限性

  • 此方案为 Telegram iOS 特定 workaround，非 W3C 标准行为，未来版本可能变更；
  • 不适用于所有 Telegram 客户端（Android 和桌面版通常无此问题）；
  • 若使用 position: fixed 或 transform 等复杂布局，需额外测试层级与定位兼容性；
  • 当前官方仍未修复该问题，相关 issue 仍处于 open 状态（#1410, #1475）。

  建议在项目中封装为可复用的初始化函数，并结合 @supports (height: env(safe-area-inset-bottom)) 做安全降级。只要合理组合 --tg-viewport-stable-height 与 window.scrollTo(0, 0)，即可在绝大多数 Telegram iOS 场景下实现输入框始终可见的体验。