1. textarea 调起软键盘为什么在 uni-app 里总出幺蛾子如果你正在用 uni-app 做聊天、评论、表单这类带输入框的页面大概率遇到过下面这几种情况软键盘一弹起来固定在顶部的导航栏被顶飞了输入框明明在屏幕中间键盘一出来就被盖住用户根本看不到自己打的字或者键盘收起后页面布局没还原留一大块空白。这些都不是玄学而是 textarea、uni-input 和软键盘三者配合时页面高度、定位方式、光标间距没对齐导致的。这篇就围绕 textarea 调起软键盘的兼容坑把 manifest.json 和 uni.css 这两个关键位置拆开讲。适合刚接触 uni-app、被软键盘顶起和遮挡问题卡住的同学也适合已经写过几版但一直没系统整理过的老手。我会先给一份可以直接抄的 manifest.json 软键盘字段骨架再给 uni.css 的布局修正片段最后用真机跑一遍弹起和收起的验证步骤。整个过程不需要你改业务逻辑先把配置层理顺很多问题自己就消失了。需要说明的是软键盘行为在不同系统、不同机型上差异很大Android 和 iOS 的表现尤其不一样。所以下面的配置我会标注哪些是通用项、哪些是平台专属你按自己的目标平台取舍不要一股脑全开。2. 先把 TaoToken 的接入环境准备好在动手排查之前建议先把调试用的模型接口环境搭好这样你改完配置能立刻在真机上验证输入和请求是否正常。我平时用 TaoToken 来做这类联调它的接口地址是 https://taotoken.net/api 控制台在 https://taotoken.net/console 。如果你还没建过 Key先去 API Keys 页面生成一个地址是 https://taotoken.net/api-keys 生成后复制保存后面配置请求头要用。对于只是想在真机上验证 textarea 输入、软键盘弹起收起这种场景用模型对话页面手动发几条消息就够了地址是 https://taotoken.net/models 。如果你是要做长期的编码调试或者 Agent 类项目反复改配置、反复跑真机那用 Coding Plan 会更省事地址是 https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 遇到字段不确定的时候翻一下比猜快。这里要提醒一句TaoToken 只是提供模型调用的接口能力它不替代你的编辑器也不替代 uni-app 本身的配置。软键盘的问题还是要在 manifest.json 和 uni.css 里解决接口环境只是让你改完之后有个稳定的地方验证。3. manifest.json 软键盘相关字段骨架manifest.json 是 uni-app 的全局配置文件软键盘相关的行为主要在这里控制。打开项目根目录的 manifest.json找到app-plus节点下面这些字段和软键盘直接相关。我给的是一份骨架你按需保留{ app-plus: { softinput: { mode: adjustResize, navBar: auto, auxiliary: true, softinputNavBar: none }, popGesture: close, titleNView: false } }逐个说清楚。softinput.mode是最关键的字段它决定软键盘弹起时页面怎么响应。可选值有adjustResize、adjustPan、nothing。adjustResize会让页面高度重新计算适合输入框在页面底部、需要整体上移的场景adjustPan是平移页面适合输入框位置固定、不想改变整体布局的场景nothing就是什么都不做一般不推荐除非你自己完全接管了键盘处理。softinput.navBar控制原生导航栏在键盘弹起时的行为auto让它自动判断。softinput.auxiliary是 iOS 上键盘上方那条辅助工具栏如果你不需要可以设成 false能省一点高度。softinputNavBar设成none可以去掉键盘上方的原生导航条避免它和你的自定义头部打架。这里有个坑要单独说adjustResize和adjustPan不能同时生效你只能选一个。我试过在聊天页面用adjustResize结果固定头部被顶上去后来换成adjustPan才正常。所以选哪个取决于你的页面结构不是越智能越好。改完 manifest.json 后一定要重新编译热更新有时候不会让这些原生配置生效。真机运行前先杀掉 App 进程再启动避免旧配置残留。4. uni.css 布局修正片段配置层搞定后剩下的遮挡和顶起问题基本都在 CSS 里。uni-app 官方提供的 uni.css 里有一个关键类uni-input它必须和cursor-spacing同时使用才能让输入框在键盘弹起时自动上移。很多人只加了cursor-spacing属性却没引入 uni.css或者类名写错了结果完全没效果。先确认你的页面引入了 uni.css。在App.vue或者页面的 style 里import /common/uni.css;然后在 textarea 或 uni-input 上同时写类名和属性textarea classuni-input cursor-spacing20 :adjust-positiontrue placeholder请输入内容 /cursor-spacing的值是光标和键盘之间的间距单位 px一般给 20 到 40 比较舒服。:adjust-position是 uni-app 的属性设为 true 时输入框会自动上移避开键盘。这两个配合起来大部分遮挡问题就解决了。如果你的页面有固定头部键盘弹起时头部被顶上去那问题出在定位方式上。固定头部如果用position: fixed在adjustResize模式下页面高度变化会把它一起顶走。修正方式是给头部容器加一个独立的层级和高度约束.header-fixed { position: fixed; top: 0; left: 0; right: 0; height: 88rpx; z-index: 999; background: #fff; } .content-wrap { padding-top: 88rpx; min-height: 100vh; box-sizing: border-box; }内容区用padding-top给固定头部让位而不是用margin-top这样在页面高度重算时不会塌陷。底部输入框区域建议用position: fixed; bottom: 0;配合padding-bottom给安全区留空间iOS 上还要加env(safe-area-inset-bottom)。5. 真机验证软键盘弹起与收起配置和样式改完后必须上真机验证模拟器不可靠。操作步骤如下。第一步用 HBuilderX 连接真机运行到 App或者用自定义基座。确保 manifest.json 的改动已经编译进去可以在启动日志里确认。第二步进入带 textarea 的页面点击输入框调起软键盘。观察三件事固定头部有没有被顶走、输入框有没有被遮挡、页面底部有没有异常空白。第三步输入几个字然后点击键盘上的收起按钮或者点击页面空白处让输入框失焦。观察页面布局有没有还原固定头部有没有回到原位底部有没有残留空白。第四步切换横竖屏再测一次部分机型在旋转后软键盘行为会变。如果横屏下遮挡可能需要针对横屏单独写媒体查询。第五步在 Android 和 iOS 上各测一遍。Android 的adjustResize表现通常更明显iOS 则更依赖cursor-spacing和adjust-position。如果 iOS 上键盘弹起后页面没动检查adjust-position是不是被设成了 false。验证的时候可以配合 TaoToken 的模型对话页面发一条消息确认输入框内容能正常提交这样既测了软键盘也测了请求链路。地址还是 https://taotoken.net/models 发完看返回是否正常。6. 本篇常见错排查清单下面这些是我在实际项目里踩过的坑按出现频率排。第一个cursor-spacing加了但没引入 uni.css或者类名写成了uni-input以外的名字。这个类名是固定的不能改。第二个manifest.json 里softinput.mode设成了nothing然后奇怪为什么键盘弹起页面没反应。除非你自己接管了键盘否则别用这个值。第三个固定头部用了position: absolute而不是fixed在页面滚动时位置错乱。固定定位就用 fixed配合内容区 padding 让位。第四个改完 manifest.json 没重新编译热更新不生效。原生配置必须重新打包或重新运行。第五个iOS 上键盘辅助工具栏占了高度导致输入框还是被挡。把softinput.auxiliary设成 false 试试。第六个textarea 的:adjust-position写成了adjust-position没加冒号属性没生效。Vue 里动态属性要加冒号。第七个页面用了scroll-view包裹输入框键盘弹起时 scroll-view 的高度没跟着变。这种情况要给 scroll-view 设:scroll-y并监听键盘高度手动调整或者干脆不用 scroll-view 包输入区。如果排查完还是有问题去接入文档 https://taotoken.net/doc 翻一下平台相关的注意事项或者到 API Keys 页面 https://taotoken.net/api-keys 确认你的请求配置没问题排除是接口层导致的假象。长期做编码调试的话Coding Plan https://taotoken.net/coding-plan 能帮你把环境固定下来减少变量。 
长河君 · 2026/9/28 4:24:54 · 阅读 1.2k textarea 调起软键盘的兼容坑：从 manifest.json 到 uni.css 的排查清单
1. textarea 调起软键盘为什么在 uni-app 里总出幺蛾子如果你正在用 uni-app 做聊天、评论、表单这类带输入框的页面大概率遇到过下面这几种情况软键盘一弹起来固定在顶部的导航栏被顶飞了输入框明明在屏幕中间键盘一出来就被盖住用户根本看不到自己打的字或者键盘收起后页面布局没还原留一大块空白。这些都不是玄学而是 textarea、uni-input 和软键盘三者配合时页面高度、定位方式、光标间距没对齐导致的。这篇就围绕 textarea 调起软键盘的兼容坑把 manifest.json 和 uni.css 这两个关键位置拆开讲。适合刚接触 uni-app、被软键盘顶起和遮挡问题卡住的同学也适合已经写过几版但一直没系统整理过的老手。我会先给一份可以直接抄的 manifest.json 软键盘字段骨架再给 uni.css 的布局修正片段最后用真机跑一遍弹起和收起的验证步骤。整个过程不需要你改业务逻辑先把配置层理顺很多问题自己就消失了。需要说明的是软键盘行为在不同系统、不同机型上差异很大Android 和 iOS 的表现尤其不一样。所以下面的配置我会标注哪些是通用项、哪些是平台专属你按自己的目标平台取舍不要一股脑全开。2. 先把 TaoToken 的接入环境准备好在动手排查之前建议先把调试用的模型接口环境搭好这样你改完配置能立刻在真机上验证输入和请求是否正常。我平时用 TaoToken 来做这类联调它的接口地址是 https://taotoken.net/api 控制台在 https://taotoken.net/console 。如果你还没建过 Key先去 API Keys 页面生成一个地址是 https://taotoken.net/api-keys 生成后复制保存后面配置请求头要用。对于只是想在真机上验证 textarea 输入、软键盘弹起收起这种场景用模型对话页面手动发几条消息就够了地址是 https://taotoken.net/models 。如果你是要做长期的编码调试或者 Agent 类项目反复改配置、反复跑真机那用 Coding Plan 会更省事地址是 https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 遇到字段不确定的时候翻一下比猜快。这里要提醒一句TaoToken 只是提供模型调用的接口能力它不替代你的编辑器也不替代 uni-app 本身的配置。软键盘的问题还是要在 manifest.json 和 uni.css 里解决接口环境只是让你改完之后有个稳定的地方验证。3. manifest.json 软键盘相关字段骨架manifest.json 是 uni-app 的全局配置文件软键盘相关的行为主要在这里控制。打开项目根目录的 manifest.json找到app-plus节点下面这些字段和软键盘直接相关。我给的是一份骨架你按需保留{ app-plus: { softinput: { mode: adjustResize, navBar: auto, auxiliary: true, softinputNavBar: none }, popGesture: close, titleNView: false } }逐个说清楚。softinput.mode是最关键的字段它决定软键盘弹起时页面怎么响应。可选值有adjustResize、adjustPan、nothing。adjustResize会让页面高度重新计算适合输入框在页面底部、需要整体上移的场景adjustPan是平移页面适合输入框位置固定、不想改变整体布局的场景nothing就是什么都不做一般不推荐除非你自己完全接管了键盘处理。softinput.navBar控制原生导航栏在键盘弹起时的行为auto让它自动判断。softinput.auxiliary是 iOS 上键盘上方那条辅助工具栏如果你不需要可以设成 false能省一点高度。softinputNavBar设成none可以去掉键盘上方的原生导航条避免它和你的自定义头部打架。这里有个坑要单独说adjustResize和adjustPan不能同时生效你只能选一个。我试过在聊天页面用adjustResize结果固定头部被顶上去后来换成adjustPan才正常。所以选哪个取决于你的页面结构不是越智能越好。改完 manifest.json 后一定要重新编译热更新有时候不会让这些原生配置生效。真机运行前先杀掉 App 进程再启动避免旧配置残留。4. uni.css 布局修正片段配置层搞定后剩下的遮挡和顶起问题基本都在 CSS 里。uni-app 官方提供的 uni.css 里有一个关键类uni-input它必须和cursor-spacing同时使用才能让输入框在键盘弹起时自动上移。很多人只加了cursor-spacing属性却没引入 uni.css或者类名写错了结果完全没效果。先确认你的页面引入了 uni.css。在App.vue或者页面的 style 里import /common/uni.css;然后在 textarea 或 uni-input 上同时写类名和属性textarea classuni-input cursor-spacing20 :adjust-positiontrue placeholder请输入内容 /cursor-spacing的值是光标和键盘之间的间距单位 px一般给 20 到 40 比较舒服。:adjust-position是 uni-app 的属性设为 true 时输入框会自动上移避开键盘。这两个配合起来大部分遮挡问题就解决了。如果你的页面有固定头部键盘弹起时头部被顶上去那问题出在定位方式上。固定头部如果用position: fixed在adjustResize模式下页面高度变化会把它一起顶走。修正方式是给头部容器加一个独立的层级和高度约束.header-fixed { position: fixed; top: 0; left: 0; right: 0; height: 88rpx; z-index: 999; background: #fff; } .content-wrap { padding-top: 88rpx; min-height: 100vh; box-sizing: border-box; }内容区用padding-top给固定头部让位而不是用margin-top这样在页面高度重算时不会塌陷。底部输入框区域建议用position: fixed; bottom: 0;配合padding-bottom给安全区留空间iOS 上还要加env(safe-area-inset-bottom)。5. 真机验证软键盘弹起与收起配置和样式改完后必须上真机验证模拟器不可靠。操作步骤如下。第一步用 HBuilderX 连接真机运行到 App或者用自定义基座。确保 manifest.json 的改动已经编译进去可以在启动日志里确认。第二步进入带 textarea 的页面点击输入框调起软键盘。观察三件事固定头部有没有被顶走、输入框有没有被遮挡、页面底部有没有异常空白。第三步输入几个字然后点击键盘上的收起按钮或者点击页面空白处让输入框失焦。观察页面布局有没有还原固定头部有没有回到原位底部有没有残留空白。第四步切换横竖屏再测一次部分机型在旋转后软键盘行为会变。如果横屏下遮挡可能需要针对横屏单独写媒体查询。第五步在 Android 和 iOS 上各测一遍。Android 的adjustResize表现通常更明显iOS 则更依赖cursor-spacing和adjust-position。如果 iOS 上键盘弹起后页面没动检查adjust-position是不是被设成了 false。验证的时候可以配合 TaoToken 的模型对话页面发一条消息确认输入框内容能正常提交这样既测了软键盘也测了请求链路。地址还是 https://taotoken.net/models 发完看返回是否正常。6. 本篇常见错排查清单下面这些是我在实际项目里踩过的坑按出现频率排。第一个cursor-spacing加了但没引入 uni.css或者类名写成了uni-input以外的名字。这个类名是固定的不能改。第二个manifest.json 里softinput.mode设成了nothing然后奇怪为什么键盘弹起页面没反应。除非你自己接管了键盘否则别用这个值。第三个固定头部用了position: absolute而不是fixed在页面滚动时位置错乱。固定定位就用 fixed配合内容区 padding 让位。第四个改完 manifest.json 没重新编译热更新不生效。原生配置必须重新打包或重新运行。第五个iOS 上键盘辅助工具栏占了高度导致输入框还是被挡。把softinput.auxiliary设成 false 试试。第六个textarea 的:adjust-position写成了adjust-position没加冒号属性没生效。Vue 里动态属性要加冒号。第七个页面用了scroll-view包裹输入框键盘弹起时 scroll-view 的高度没跟着变。这种情况要给 scroll-view 设:scroll-y并监听键盘高度手动调整或者干脆不用 scroll-view 包输入区。如果排查完还是有问题去接入文档 https://taotoken.net/doc 翻一下平台相关的注意事项或者到 API Keys 页面 https://taotoken.net/api-keys 确认你的请求配置没问题排除是接口层导致的假象。长期做编码调试的话Coding Plan https://taotoken.net/coding-plan 能帮你把环境固定下来减少变量。