Capacitor 应用键盘遮挡、滚动与配件栏处理

在 Capacitor 的 iOS/Android 应用中监听键盘事件、配置缩放模式，解决输入框被键盘遮挡、滚动错位和 iOS 缩放等问题。

适用场景

解决思路

1. 安装插件并同步原生工程：npm install @capacitor/keyboard，然后 npx cap sync。
2. 基础调用：从 @capacitor/keyboard 导入 Keyboard，用 await Keyboard.show() 显示键盘、await Keyboard.hide() 隐藏键盘。
3. 注册键盘事件监听：Keyboard.addListener('keyboardWillShow', (info) => {...}) 读取 info.keyboardHeight，Keyboard.addListener('keyboardWillHide', () => {...}) 处理隐藏。
4. 在 capacitor.config.ts 的 plugins.Keyboard 中配置：resize（'body' | 'ionic' | 'native' | 'none'）、style（'dark' | 'light' | 'default'）、resizeOnFullScreen: true。
5. 按场景选择 resize 模式：body 缩放宽体元素、ionic 交给 Ionic 键盘处理、native 由原生 WebView 缩放、none 不做自动缩放。
6. 用 Capacitor.isNativePlatform() 判断是否原生平台，仅在原生下监听 keyboardWillShow/keyboardWillHide，把 keyboardHeight 写入 document.body.style 的 CSS 变量 --keyboard-height，隐藏时置为 '0px'。
7. 用该 CSS 变量布局输入区：.chat-input 用 position: fixed，bottom: calc(var(--keyboard-height, 0px) + env(safe-area-inset-bottom))，left/right: 0。
8. 键盘弹出时滚动到当前输入框：在 keyboardWillShow 回调里取 document.activeElement，先 await new Promise(r => setTimeout(r, 100)) 等键盘动画，再调用 scrollIntoView({ behavior: 'smooth', block: 'center' })。
9. iOS 配件栏用 await Keyboard.setAccessoryBarVisible({ isVisible: true }) 显示、传 false 隐藏。
10. 表单防缩放：给 input 设置 font-size: 16px（或更大），避免 iOS 聚焦时自动放大页面。
11. 表单提交处理：在 submit 里 e.preventDefault()，先 await Keyboard.hide()，再执行业务逻辑。
12. 输入框回车跳转：监听 keypress，当 e.key === 'Enter' 时聚焦下一个输入框；若没有下一个输入框则调用 Keyboard.hide() 收起键盘。
13. 按排障表定位问题：内容被遮挡→配置 resize 模式；动画卡顿→改用 keyboardWillShow；iOS 缩放→字号设为 16px；Android 重叠→设置 windowSoftInputMode。
14. 参考资料见 Capacitor Keyboard 官方文档：https://capacitorjs.com/docs/apis/keyboard。

适用边界 · 注意事项

• 非 Capacitor 的纯 Web 应用或 React Native/Flutter 项目：这些环境没有 @capacitor/keyboard 插件，应改用浏览器原生 API（如 visualViewport）或对应框架的键盘方案。
• 如果已启用 resize 模式（body/ionic/native）让系统自动处理键盘高度，不要再叠加自定义的键盘高度补偿，否则会出现双重偏移/抖动。
• 不要只依赖 keyboardDidShow 之类的“已显示”事件做布局动画，容易造成动画迟缓；需要跟随键盘动画时应使用 keyboardWillShow。