全面屏设备底部的手势横条已经成了很多小程序页面隐藏的布局杀手。自定义 modal 底部弹窗最常见的故障不是样式写错，而是弹窗按钮恰好落在系统横条上，用户点不到、内容也被遮住。解决这个问题不能靠猜测高度，需要把安全区域数据真正接入弹窗布局。
为什么自定义 modal 在全面屏上会出现底部遮挡？
微信小程序中，系统提供的原生弹窗组件（如 wx.showModal）已经由微信客户端处理了安全区域，开发者无需关心底部横条问题。但一旦使用自定义 view 来绘制 modal，弹窗的定位就完全交给开发者控制。很多实现会直接把底部按钮容器设置成 position: fixed; bottom: 0; 或者给弹窗底部设置固定 padding，这种写法在非全面屏上看起来合适，在带有底部手势条的设备上就会让按钮和横条重叠。
原因在于全面屏的安全区域是一个“凹”形区域，页面可视区域底部有一部分被系统手势条占用，而 WXML 中的普通元素默认可以延伸到这一区域。小程序 WebView 提供的 CSS 常量 env(safe-area-inset-bottom) 可以获取底部安全距离，但前提是页面 viewport 需要正确设置 viewport-fit=cover。如果忽略这个设置，iOS 上 env() 取值会一直是 0，适配自然失效。
另外，Android 厂商对底部手势区的处理并不统一，部分设备返回的 safeArea 数据可能为 0 或者返回系统导航栏高度，需要结合 JS 动态计算。只有同时理解 CSS 常量与小程序 API 的差异，才能在各类设备上获得一致效果。
获取安全区域的核心方法：CSS 常量与 JS 数据
微信小程序的安全区域适配主要依赖两种数据来源。第一种是 WXSS 中的 CSS 环境变量，写法如下：
/* 需要在页面根节点声明 viewport-fit=cover */
.modal-box {
padding-bottom: constant(safe-area-inset-bottom); /* iOS 11.0-11.2 兼容 */
padding-bottom: env(safe-area-inset-bottom); /* iOS 11.2+ 及部分 Android */
}
其中 constant() 是 iOS 11.0 到 11.2 的旧写法，env() 是新标准，两者最好同时保留。需要注意的是，env(safe-area-inset-bottom) 只有在页面 viewport 设置为 cover 时才会产生非零值。在小程序中，可以通过在页面 WXML 顶部加入 <page-meta page-style="viewport-fit: cover;" /> 来开启，也可以在页面配置中设置 viewportFit 字段。
<!-- 页面 WXML 顶部 --> <page-meta page-style="viewport-fit: cover;" />
第二种方法是通过小程序 API wx.getSystemInfoSync() 获取设备安全区域信息。返回对象中包含 safeArea 字段，例如 { top: 44, bottom: 34, left: 0, right: 375 }，其中 bottom 表示从屏幕顶部到安全区域底部的距离，所以底部安全区高度等于屏幕高度减去 safeArea.bottom 的值。也可以通过 wx.getWindowInfo() 获取 screenHeight 和 safeArea.bottom 来计算。
const windowInfo = wx.getWindowInfo ? wx.getWindowInfo() : wx.getSystemInfoSync();
const { screenHeight, safeArea } = windowInfo;
const bottomSafeHeight = screenHeight - safeArea.bottom;
console.log('底部安全区高度:', bottomSafeHeight);
这个高度可以动态写入 data 中，再通过内联样式绑定到弹窗容器上。JS 方式的好处是不依赖 CSS 环境变量，低版本基础库也能工作，但需要处理异步加载和多次计算。通常做法是在页面 onLoad 或组件 attached 生命周期中获取一次，并存入 data。
最佳实践：自定义 modal 的结构与样式适配
自定义 modal 通常由遮罩层、弹窗主体、顶部标题栏和底部按钮区组成。适配的核心原则是：弹窗主体的高度不要写死为全屏高度，底部按钮区需要预留 padding-bottom 或 margin-bottom 来容纳安全区域高度。推荐的结构如下：
<view class="modal-mask" wx:if="{{visible}}">
<view class="modal-container" style="padding-bottom: {{bottomSafeHeight}}px;">
<view class="modal-header">标题</view>
<scroll-view scroll-y class="modal-content">
<!-- 内容区域 -->
</scroll-view>
<view class="modal-footer">
<button>取消</button>
<button>确认</button>
</view>
</view>
</view>
在上面的结构中，给 modal-container 设置内联样式 padding-bottom 而不是直接设置 bottom: 0，这样底部按钮区域就不会被手势条遮挡。同时，在 WXSS 中还要加上 CSS 常量作为兜底，当 JS 计算失败时仍能生效：
.modal-container {
display: flex;
flex-direction: column;
max-height: 85vh;
padding-bottom: constant(safe-area-inset-bottom);
padding-bottom: env(safe-area-inset-bottom);
background: #fff;
border-radius: 24rpx 24rpx 0 0;
}
需要注意的是，弹窗主体如果设置了 max-height，底部 padding 会把可用内容高度压缩，因此滚动区域需要设置 flex: 1 和 min-height: 0，避免内容溢出。另外遮罩层建议使用 position: fixed; top: 0; left: 0; right: 0; bottom: 0;，这样遮罩可以覆盖整个屏幕包括安全区域，不会出现底部漏出。
除了底部安全距离，顶部刘海区域对自定义 modal 影响较小，因为弹窗通常从底部弹出，不需要考虑顶部。但如果弹窗是居中或全屏，也要相应使用 env(safe-area-inset-top)。
兼容低版本与 Android/iOS 差异处理
iOS 对 env() 的支持比较成熟，但在 iOS 11.0 到 11.2 之间需要使用 constant() 前缀；Android 设备虽然在 WebView 中支持 env()，但不同厂商的返回差异较大。部分 Android 全面屏设备的底部安全区高度可能为 0，系统手势条会悬浮在应用内容上方，导致底部按钮仍然被遮挡。此时仅靠 CSS 常量无法解决问题，需要 JS 动态探测。
实践中可以建立一个工具函数，优先尝试 wx.getSystemInfoSync() 获取 safeArea，如果返回的 safeArea.bottom 接近屏幕高度或者为 0，就回退到经验值（例如 20px 或 34px），或者结合 wx.getMenuButtonBoundingClientRect() 判断设备类型。下面是一个兼容性较好的函数：
function getBottomSafeHeight() {
let info = wx.getSystemInfoSync ? wx.getSystemInfoSync() : null;
if (info && info.safeArea && info.safeArea.bottom) {
let height = info.screenHeight - info.safeArea.bottom;
if (height > 0 && height < 60) {
return height;
}
}
// 回退：常见全面屏底部安全区为 34px，部分 Android 为 0 不处理
return 0;
}
module.exports = { getBottomSafeHeight };
这段代码中 height < 60 的判断用于过滤异常值，避免某些 Android 设备返回导航栏高度（可能超过 60px）被误当成底部安全区。如果返回 0，则不给弹窗加额外 padding，维持原有设计。
低版本基础库可能没有 safeArea 字段，此时 wx.getSystemInfoSync() 可能不返回该字段，需要做兼容。另外在自定义导航栏场景下，页面本身已经占满全屏，安全区域的计算还应考虑顶部状态栏高度，弹窗底部适配不要与顶部逻辑混用。
完整代码示例与常见问题
把结构、样式和逻辑整合起来，可以得到一个可直接使用的底部弹窗组件。WXML 部分如下，注意 <page-meta> 用于开启 viewport-fit：
<page-meta page-style="viewport-fit: cover;" />
<view class="modal-mask" wx:if="{{show}}">
<view class="modal-box" style="padding-bottom: {{safeBottom}}px;">
<view class="modal-title">操作确认</view>
<scroll-view scroll-y class="modal-body">
这里是弹窗内容...
</scroll-view>
<view class="modal-actions">
<button class="btn-cancel" bindtap="onCancel">取消</button>
<button class="btn-confirm" bindtap="onConfirm">确认</button>
</view>
</view>
</view>
对应的 WXSS：
.modal-mask {
position: fixed;
top: 0;
left: 0;
right: 0;
bottom: 0;
background: rgba(0, 0, 0, 0.5);
z-index: 999;
}
.modal-box {
position: fixed;
left: 0;
right: 0;
bottom: 0;
background: #fff;
border-radius: 24rpx 24rpx 0 0;
padding-bottom: constant(safe-area-inset-bottom);
padding-bottom: env(safe-area-inset-bottom);
box-shadow: 0 -4rpx 20rpx rgba(0, 0, 0, 0.08);
}
.modal-body {
max-height: 40vh;
min-height: 100rpx;
}
.modal-actions {
display: flex;
gap: 20rpx;
padding: 20rpx 30rpx;
}
组件 JS 逻辑：
Component({
data: {
show: false,
safeBottom: 0
},
lifetimes: {
attached() {
this.setData({ safeBottom: this.getSafeBottom() });
}
},
methods: {
getSafeBottom() {
const info = wx.getWindowInfo ? wx.getWindowInfo() : wx.getSystemInfoSync();
if (info.safeArea && info.safeArea.bottom) {
const height = info.screenHeight - info.safeArea.bottom;
if (height > 0 && height < 60) return height;
}
return 0;
},
onCancel() { this.setData({ show: false }); },
onConfirm() { this.setData({ show: false }); }
}
});
常见问题包括：设置了 padding-bottom 后弹窗内部滚动区域不能滚动，通常是因为 scroll-view 没有设置固定高度或者 flex 容器层级不对；使用 env() 时不要在 calc() 中嵌套错误；在开发者工具上可能看不到安全区域效果，需要用真机预览验证。只要遵循以上的结构和方法，自定义 modal 在全面屏设备上就能保持稳定的底部间距。