1. 小程序 iOS 软键盘弹起挡住 input 输入框用 onKeyboardHeightChange 做精准避让小程序在 iOS 真机上软键盘弹起遮挡 input 输入框是个老生常谈的问题。你可能会发现安卓上跑得好好的页面一到 iOS 就翻车输入框被键盘顶到屏幕外或者页面整体上推后底部留出一大块空白键盘收起后布局又回不到原位。这个问题的核心在于 iOS 的键盘处理机制和安卓差异很大微信小程序默认的adjust-position自动上推策略在 iOS 上经常出现错位。onKeyboardHeightChange就是官方给出的解法——它能实时告诉你键盘弹起了多高你拿着这个高度自己去控制输入框容器的位置避让逻辑完全掌握在自己手里。这篇内容适合正在做小程序表单、聊天输入框、评论区的开发者尤其是被 iOS 真机键盘问题折磨过的朋友。下面我会从问题复现讲起给出可复制的页面配置和监听代码骨架再说明怎么在真机上验证避让生效、键盘收起后布局复位。2. 先搞清楚 iOS 上 input 被挡住的真实原因2.1 默认 adjust-position 在 iOS 上的表现小程序 input 组件有个属性叫adjust-position默认值是true意思是键盘弹起时页面自动上推。这个机制在安卓上基本够用但在 iOS 上页面整体上推后如果输入框本身靠近底部或者页面有固定定位的容器就会出现两种典型错位一种是输入框被推到键盘上方后光标位置和视觉位置对不上另一种是键盘收起时页面没有完全回弹底部残留一段空白。我试过在一个聊天页面里用cursor-spacing去控制光标和键盘的距离安卓上没问题iOS 上直接错位。后来才转向onKeyboardHeightChange手动控制。2.2 为什么需要手动监听键盘高度onKeyboardHeightChange是uni或wx提供的全局回调键盘弹起和收起时都会触发回调参数里的res.height就是当前键盘的高度单位 px。拿到这个值后你可以把它赋给输入框容器的bottom样式让容器始终贴在键盘上方。这样做的好处是避让逻辑完全由你控制不依赖系统的自动上推iOS 和安卓表现一致。关键点在于input 组件上要加:adjust-positionfalse关掉系统自动上推否则系统上推和你的手动避让会打架错位更严重。3. 前置准备TaoToken 接入与页面基础配置在动手改代码之前如果你打算把输入框的交互逻辑接到大模型对话能力上比如做一个 AI 聊天输入框可以先把 TaoToken 的接入准备好。TaoToken 是一个大模型 API 聚合平台官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它支持模型对话、Coding Plan、控制台管理、API Keys 等能力适合做小程序里的 AI 输入场景。3.1 获取 API Key进入控制台后创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。拿到 Key 后你可以在小程序的云函数或后端服务里调用模型对话接口地址是 https://taotoken.net/api 。如果你只是做纯前端避让这一步可以跳过直接看第 4 节的代码。3.2 页面结构规划避让的核心思路是给 input 外面套一个容器容器用fixed或relative定位动态设置bottom值。input 本身加:adjust-positionfalse。页面 data 里维护一个inputHeight初始为null或0。4. 可复制的配置与监听代码骨架4.1 模板结构template view classchat-page !-- 消息列表 -- scroll-view classmsg-list scroll-y !-- 消息内容 -- /scroll-view !-- 输入框容器动态 bottom -- view classinput-bar :style{ bottom: inputHeight - 1 px } input typetext placeholder你得说点什么.. :focusfocus :adjust-positionfalse bluronBlur v-modelinputValue / /view /view /template注意bottom那里减了 1px这是 iOS 上的经验值不减的话输入框和键盘之间会有一条细缝。4.2 样式配置.chat-page { position: relative; height: 100vh; overflow: hidden; } .msg-list { height: 100%; padding-bottom: 100rpx; } .input-bar { position: fixed; left: 0; right: 0; bottom: 0; padding: 20rpx; background: #fff; border-top: 1rpx solid #eee; transition: bottom 0.2s; }容器用fixed定位bottom由inputHeight驱动。加个transition让避让过程平滑一点。4.3 监听键盘高度变化export default { data() { return { inputHeight: 0, focus: false, inputValue: }; }, onLoad() { this.initKeyboardListener(); }, onUnload() { uni.offKeyboardHeightChange(); }, methods: { initKeyboardListener() { uni.offKeyboardHeightChange(); uni.onKeyboardHeightChange(res { this.inputHeight res.height; }); }, onBlur() { // 安卓上键盘收起时 height 可能不归零手动复位 this.inputHeight 0; } } };这里有几个细节要说明。第一onLoad里先offKeyboardHeightChange再on避免页面多次进入时重复注册。第二onUnload里注销监听防止内存泄漏。第三onBlur里把inputHeight重置为 0这是针对安卓的兜底——安卓上键盘收起时res.height有时不会变成 0导致输入框悬在半空。4.4 参数对照表参数/属性作用推荐值adjust-position键盘弹起是否自动上推页面falseinputHeight键盘高度驱动容器 bottom初始 0bottom偏移iOS 上避免细缝inputHeight - 1onBlur复位安卓键盘收起兜底inputHeight 0offKeyboardHeightChange注销监听onUnload 调用5. 验证请求与真机调试结果5.1 真机验证步骤代码写完后在微信开发者工具里点「真机调试」用 iOS 手机扫码。打开页面后点击输入框观察三件事键盘弹起时输入框是否紧贴键盘上方、输入框是否完整可见、键盘收起后输入框是否回到屏幕底部。如果输入框紧贴键盘且没有细缝说明bottom: inputHeight - 1生效了。如果键盘收起后输入框回到原位说明onBlur复位逻辑正常。5.2 接入模型对话验证如果你把输入框接到了 TaoToken 的模型对话能力上可以在输入框里发一条消息看请求是否正常返回。模型对话入口是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 你可以在那里先测试接口连通性。小程序端调用时把 API Key 放在后端或云函数里不要直接暴露在前端代码中。5.3 成功结果说明避让生效的表现是iOS 真机上键盘弹起输入框容器 bottom 值等于键盘高度减 1输入框完整显示在键盘上方键盘收起onKeyboardHeightChange触发res.height为 0容器 bottom 回到 0输入框回到屏幕底部。整个过程没有页面整体上推也没有底部空白残留。6. 本篇常见错排查6.1 输入框和键盘之间有条缝这是 iOS 上的典型问题原因是bottom值没有减 1px。把inputHeight - 1改成inputHeight - 1即可。如果减 1 还不够可以试减 2不同机型可能有细微差异。6.2 键盘收起后输入框悬在半空这是安卓上的常见问题res.height在键盘收起时没有归零。解决办法就是在 input 上加blur事件失焦时把inputHeight重置为 0。注意blur和键盘收起不一定完全同步但实际表现足够用。6.3 页面整体还是被上推了检查 input 上是否加了:adjust-positionfalse。如果没加系统自动上推和你的手动避让会同时生效页面会被推两次错位更严重。6.4 监听重复触发或页面卡顿检查onLoad里是否先调了offKeyboardHeightChange。如果页面多次进入而没有注销旧监听会累积多个回调导致inputHeight被反复赋值页面抖动。onUnload里也要记得注销。6.5 输入框被键盘挡住但 bottom 没变确认onKeyboardHeightChange是否真的触发了。可以在回调里加console.log(res.height)真机调试时看控制台输出。如果没输出检查uni或wx对象是否正确引入以及基础库版本是否支持该 API。7. 语义一致 CTA避让逻辑调通后如果你要把输入框接到大模型对话、Coding Plan 或 Agent 场景建议先把 API Key 和接入文档过一遍。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。长期做编码或 Agent 的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。ClaudeCodeAnthropic 相关入口在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。模型对话测试用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。