记一次微信小程序 textarea 聚焦后页面上下抖动的排查过程
本文详细解析了微信小程序中 textarea 聚焦后页面上下抖动的排查过程:在内容较多的表单页里,
1. 问题背景:页面内容较多时,点击描述输入框出现明显抖动
这次问题发生在宠物小程序的添加记录页面:
text
pet-mini-program/package-tools/pages/add-record/add-record
页面用于添加宠物记录,内容比较多,尤其是“外出活动记录”这类表单,上面会有地图、活动按钮、轨迹控制区,下面还有描述输入框、媒体上传、隐私设置和底部保存按钮。
实际手机端表现是:
- 页面内容较多,描述输入框经常只露出一部分。
- 点击描述输入框时,页面会先自己滚动一下。
- 随后手机键盘弹出,页面又被键盘避让逻辑再次调整。
- 视觉上就变成了上下抖动,像是页面在抢滚动位置。
这个问题不是单纯的样式问题,而是输入框聚焦、键盘弹起、页面滚动、底部固定按钮几个因素叠加造成的交互问题。
2. 初始代码:系统避让和手动滚动同时存在
描述输入框原本使用的是微信小程序 textarea:
xml
<textarea
class="textarea"
placeholder="请输入你想要记的内容~"
value="{{form.desc}}"
auto-height="{{true}}"
adjust-position="{{true}}"
cursor-spacing="100"
bindinput="onInputDesc"
bindfocus="onTextareaFocus"
bindblur="onTextareaBlur"/>
这里最关键的是两个点:
xml
adjust-position="{{true}}"
cursor-spacing="100"
adjust-position 会让微信在键盘弹起时自动调整页面位置,尽量保证当前输入框不被键盘挡住。
cursor-spacing 则表示光标和键盘之间预留的距离。
这本身是合理的,但页面 JS 里又写了一段手动滚动逻辑:
js
onTextareaFocus(e) {
setTimeout(() => {
const query = wx.createSelectorQuery().in(this);
query.select('.textarea').boundingClientRect((rect) => {
if (rect) {
const windowHeight = getSafeWindowHeight();
const inputTop = rect.top;
const keyboardHeight = 300;
const visibleHeight = windowHeight - keyboardHeight;
if (inputTop > visibleHeight - 100) {
const scrollTop = inputTop - visibleHeight + 200;
wx.pageScrollTo({
scrollTop: scrollTop,
duration: 300
});
}
}
}).exec();
}, 300);
}
这样就形成了一个典型的“双重避让”:
- 微信原生
adjust-position会自动滚动页面。 - 页面自己的
onTextareaFocus又延迟执行一次wx.pageScrollTo。 - 两套逻辑都想把输入框滚到合适位置。
- 键盘弹出时间和手动滚动时间又不完全一致。
最终用户看到的就是:输入框刚聚焦,页面先动一下;键盘出来后,页面又被重新调整,于是出现上下抖动。
3. 第一轮误判:把保存按钮跟随键盘上移
排查时很容易把问题归因到“底部固定保存按钮挡住输入区”。
因为页面底部有一个 fixed 保存按钮:
css
.footer {
position: fixed;
bottom: 0;
left: 0;
right: 0;
}
第一版尝试是:
- 关闭
textarea的adjust-position - 监听键盘高度
- 给页面底部增加键盘高度占位
- 让保存按钮跟随键盘上移
结果实际体验并不好。
当键盘弹出时,保存按钮被顶到了键盘上方,反而抢占了输入框应该展示的位置。用户点击描述框,本来期望的是“输入内容贴着键盘上方可见”,结果却看到一个保存按钮横在键盘上方。
这类表单的正常交互不应该是这样。
4. 正常交互应该是什么样?
对这种移动端表单来说,更自然的交互是:
- 输入框聚焦后,由系统负责键盘避让。
- 当前输入区域保持在键盘上方可见。
- 底部保存按钮不跟随键盘上移。
- 键盘弹出期间,保存按钮可以暂时被键盘遮住。
- 用户输入完成后,收起键盘,再点击保存。
原因很简单:
- 键盘弹出时,用户当前任务是输入,不是保存。
- 保存按钮跟着键盘上移,会挤占输入区域。
- 手动控制键盘高度在不同机型、输入法、调试工具中不稳定。
- 小程序已经提供了原生键盘避让能力,重复做一套容易互相干扰。
所以最终方向不是“自己接管键盘布局”,而是:
保留微信原生键盘避让,删除页面自己的二次滚动逻辑。
5. 最终解决方案:删除 textarea 聚焦时的手动滚动
最终修复集中在两个地方。
5.1 删除 onTextareaFocus 中的 pageScrollTo
修复后,描述输入框聚焦时不再主动调用 wx.pageScrollTo:
js
onTextareaFocus(e) {
},
onTextareaBlur(e) {
},
也就是说:
- 不再估算键盘高度
- 不再延迟 300ms 手动滚动
- 不再计算
scrollTop - 不再和微信原生
adjust-position抢滚动位置
这样键盘弹出时,只剩下微信自己的避让逻辑在工作。
5.2 保留 adjust-position,但降低 cursor-spacing
描述输入框仍然保留原生避让:
xml
<textarea
class="textarea"
placeholder="请输入你想要记的内容~"
value="{{form.desc}}"
auto-height="{{true}}"
adjust-position="{{true}}"
cursor-spacing="48"
bindinput="onInputDesc"
bindfocus="onTextareaFocus"
bindblur="onTextareaBlur"/>
这里把 cursor-spacing 从原来的 100 调整为 48。
原因是:
100预留空间偏大,容易让系统为了留白把页面顶得过多。48能保留输入舒适度,又不会产生太激进的滚动。
6. 为什么不再处理保存按钮?
保存按钮仍然保持原来的 fixed 布局:
css
.footer {
position: fixed;
bottom: 0;
left: 0;
right: 0;
background: var(--theme-bg-card);
padding: 24rpx 32rpx;
padding-bottom: calc(24rpx + env(safe-area-inset-bottom));
border-radius: 48rpx 48rpx 0 0;
box-shadow: var(--theme-shadow-card);
z-index: 100;
}
它不再监听键盘高度,也不再跟随键盘上移。
键盘弹起期间,保存按钮被键盘遮住是可以接受的,因为用户此时正在输入。
输入完成后,用户点击键盘上的“完成”或收起键盘,保存按钮自然重新露出。
这比“保存按钮被顶到键盘上方,挡住输入区域”更符合移动端表单习惯。
7. 排查经验总结
这次问题的关键不是某一个 CSS 写错了,而是多个键盘避让策略同时存在:
textarea adjust-positioncursor-spacingonTextareaFocus手动pageScrollTo- 底部 fixed 保存按钮
- 手机输入法弹起动画
其中真正造成抖动的核心是:
系统已经在帮 textarea 做键盘避让,页面 JS 又手动滚动了一次。
解决这类问题时,可以按下面顺序排查:
- 先看输入组件是否开启了
adjust-position。 - 再查
bindfocus里有没有手动pageScrollTo。 - 如果有 fixed 底部按钮,确认它是否跟键盘高度联动。
- 不要一上来就接管键盘高度,优先让系统原生避让单独工作。
- 如果仍然遮挡,再小幅调整
cursor-spacing,不要同时叠加多套滚动策略。
最终原则可以概括成一句话:
移动端输入框键盘避让,最好只保留一个主控方;要么交给系统,要么自己完整接管,不要两边同时滚。