如何在移动端键盘弹出时动态调整模态框高度

本文介绍在 next.js 应用中，当输入框获得焦点触发软键盘时，通过 react 状态驱动方式自动缩放模态框高度（如从 100% 缩至 55%），避免输入框被遮挡的完整实现方案。

本文介绍在 next.js 应用中，当输入框获得焦点触发软键盘时，通过 react 状态驱动方式自动缩放模态框高度（如从 100% 缩至 55%），避免输入框被遮挡的完整实现方案。

在移动端 Web 应用（尤其是 ios safari 和 android chrome）中，软键盘弹出会引发视口（viewport）压缩、滚动偏移及元素重排等不可预测行为。若模态框（Modal）内含聊天输入框，键盘常会覆盖输入区域，严重影响用户体验。直接操作 dom（如遍历 getElementsByclassName 并修改 style.height）不仅违背 React 的声明式原则，还易因渲染时机、服务端与客户端不一致（SSR hydration mismatch）或元素未挂载而失效。

✅ 推荐做法：使用 React 状态控制模态框尺寸，配合 onFocus/onBlur 生命周期事件响应键盘状态变化。该方案具备可预测性、可维护性与跨平台兼容性。

核心实现逻辑

1. 定义一个 height 状态变量，默认为 ‘100%’；
2. 在输入框的 onFocus 中调用 setHeight(‘55%’)，触发模态框收缩；
3. 在 onBlur（或更健壮的 onFocusOut）中恢复为 ‘100%’；
4. 将 height 动态绑定至模态内容容器的 style.height 或 CSS 类中。

示例代码（Next.js 兼容版）

'use client'; // 必须标记为客户端组件（Next.js 13+ App router）  import { useState, useEffect } from 'react';  export default function ChatModal() {   const [height, setHeight] = useState<string>('100%');    // 可选：监听窗口 resize 或键盘高度变化（进阶）   useEffect(() => {     const handleResize = () => {       // 某些场景下可结合 window.visualViewport?.height 判断键盘是否打开       // 但 onFocus/Blur 已足够可靠，此处省略复杂检测     };      window.addEventListener('resize', handleResize);     return () => window.removeEventListener('resize', handleResize);   }, []);    const handleInputFocus = () => setHeight('55%');   const handleInputBlur = () => setHeight('100%');    return (     <div className="fixed inset-0 bg-black/50 flex items-end z-50">       {/* 模态框容器 —— 高度由 state 控制 */}       <div          className="w-full bg-white rounded-t-2xl shadow-lg transition-all duration-300"         style={{ height }}       >         {/* 模态头部 */}         <div className="p-4 border-b">           <h2 className="font-semibold">Chat</h2>         </div>          {/* 聊天消息区（可设 flex: 1 + overflow-y-auto） */}         <div className="h-[calc(100%-120px)] p-4 overflow-y-auto">           <div className="text-gray-600 text-sm">Messages appear here...</div>         </div>          {/* 输入区 —— 绑定焦点事件 */}         <div className="p-4 border-t">           <input             type="text"             placeholder="Type a message..."             className="w-full px-4 py-3 rounded-lg border border-gray-300 focus:outline-none focus:ring-2 focus:ring-blue-500"             onFocus={handleInputFocus}             onBlur={handleInputBlur}           />         </div>       </div>     </div>   ); }

注意事项与最佳实践

• ✅ 必须添加 ‘use client’：因涉及 DOM 事件和 useState，需明确声明为客户端组件（Next.js App Router）；
• ✅ 避免直接操作 DOM：原问题中 document.getElementsByClassName 返回的是实时集合（HTMLCollection），且在 SSR 环境下 document 未定义，极易报错；React 状态驱动更安全；
• ✅ 优先使用 onBlur 而非 onFocusOut：onBlur 兼容性更好，且能准确捕获失焦（包括点击其他区域、切换 Tab、键盘收起等场景）；
• ⚠️ iOS Safari 特别提示：部分 iOS 版本中 blur 可能在键盘收起前触发。如遇极端情况，可结合 setTimeout 延迟恢复高度（通常无需）；
• ? 响应式增强建议：可进一步根据 window.visualViewport?.height 计算实际可视区域高度，实现更精准的自适应（适用于复杂布局）；
• ? 与 ui 库集成：若使用 Headless UI、Radix UI 或 Ant Design 等库，应将 height 作为 style prop 透传至其内部 content 元素，而非硬编码 class 名。

通过状态驱动的高度控制，你不仅能解决键盘遮挡问题，还能轻松扩展动画、适配不同设备、并保持组件的可测试性与可组合性。记住：让 UI 成为状态的函数，而非 DOM 操作的副产品。