uni-app全面屏适配需分端处理:APP端必须配置manifest.json的safearea,background须与页面背景严格一致,offset设auto并重新运行;小程序/H5需手动获取safeAreaInsets或fallback判断;吸底按钮必须用fixed定位,避免transform/overflow干扰。

uni-app适配全面屏,核心是处理底部安全区(尤其是 iOS 的 Home Indicator 和安卓全面屏的虚拟导航栏),不能靠猜高度、硬编码或仅靠 CSS env(safe-area-inset-bottom) 单一方案——它在 H5 和旧版微信小程序里直接失效,会导致按钮悬空。
必须改 manifest.json 配置(APP 端唯一稳解)
APP 端(iOS/Android)的安全区背景和偏移逻辑由原生层接管,JS 和 CSS 无法覆盖。你写再多 padding-bottom 或动态计算,都盖不住那条白边。
-
"app-plus": { "safearea": { "background": "#1A1A1A", "bottom": { "offset": "auto" } } }——background必须和页面主背景色严格一致(差一个灰度都会露缝) - 改完必须重新运行:
npm run dev或 HBuilderX 点「运行」→「重新运行」;热更新不触发 manifest 生效 - 若用了自定义调试基座,需重启基座;真机调试要删旧 App 再重装
- 别设
offset: "none",除非你确认全页手动避让(比如全屏视频页),否则按钮大概率被截断或消失
微信小程序和 H5 要手动读 safeAreaInsets
微信小程序基础库 ≥2.10.4 才返回 safeAreaInsets.bottom,且不能在 onLoad 里取——此时系统信息还没就绪,基本拿不到值。
- 必须在
onShow或onReady后调用uni.getSystemInfo()(异步)或uni.getSystemInfoSync()(同步) - H5 完全不支持
safeAreaInsets,只能 fallback:用window.screen.height / window.screen.width > 1.8粗筛全面屏,再结合window.innerHeight判断是否存在隐藏导航栏 - fallback 值建议设为
34(iOS 标准值),但注意 OPPO/vivo 等安卓全面屏可能不满足比值,得实测
吸底按钮必须用 fixed + left/right/0,不能靠 flex 或 margin
所谓“吸底”,是指滚动时始终贴在屏幕最底部、不随内容滚动而消失——这只能靠 position: fixed 实现,flex: 1 或 margin-top: auto 只会让按钮沉到内容末尾,不是真吸底。
- 按钮自身或最外层容器必须设
position: fixed; bottom: 0; left: 0; right: 0;——漏掉left和right,横屏或某些安卓全面屏上会错位 - 避免父级有
transform或overflow: hidden,会导致 fixed 定位失效 - CSS 中写
padding-bottom: env(safe-area-inset-bottom);是辅助手段,但必须搭配内联:style="{ paddingBottom: safeBottom + 'px' }"双保险 - 初始化
safeBottom别设成0,设为null或留空,等onShow后再赋值,否则首屏渲染就错位
最易被忽略的一点:uView 的 u-safe-bottom 组件只在 APP 端生效,且若 manifest 已设 offset: "auto",它会和原生占位重复,导致双倍 padding。真正在多端跑通,得按端拆逻辑,而不是寄希望于一个组件包打天下。











