n-safe-area 安全区

为顶部状态区域或底部手势区域提供真实高度占位，不自行固定定位，不预设设备型号或固定安全区高度。

实现说明

机制	组件做法	融合说明
上下方向	type 选择 top/bottom，默认 bottom	覆盖顶部和底部，默认优先常见的手势条避让
安全区来源	复用系统 safeAreaInsets 读数	不混用屏幕和窗口坐标，不为没有安全区的设备伪造高度
背景	background、transparent 与主题令牌	透明只影响背景，保留占位；背景独立绘制，切换背景不销毁插槽
插槽	默认插槽提供占位内的装饰内容	占位不是内容容器，操作按钮放在占位之前
位置与高度	原生 view，文档流占位，固定为所选安全区高度	父级决定固定或流式布局，高度不被外观样式另行覆盖

基础用法

<n-safe-area />
<n-safe-area type="top" transparent />

带原生导航栏时，内容视口已避让顶部，通常不要再使用 type="top"。没有手势条的设备或桌面浏览器，底部占位可以是 0，这是正常结果。横竖屏和窗口变化后读数会刷新。

自定义导航页需要给状态栏绘制背景或固定在窗口顶部时，改用 n-status-bar（读系统状态栏高度）；本组件面向通用安全区避让。同一页只用其中一个负责顶部，避免叠出两份高度。

与 n-page.footer 配合

安全区只由一层负责：n-page 默认 safeArea=true，footer 已自动避让，不需要再放 n-safe-area。

自行绘制安全区背景时，关闭页面自动补偿，再由组件占位：

<n-page :safe-area="false">
  <view>页面内容</view>
  <template #footer>
    <view style="padding:16px"><n-button text="提交" block /></view>
    <n-safe-area background="#10b981" />
  </template>
</n-page>

n-page 测量包含此占位的 footer 实际高度，为主体保留足够空间；无需再给主体叠加同一份安全区高度。无 footer 且选择自行处理时，把 n-safe-area 放在主体末尾。已有原生 tabBar 或业务底栏负责避让时，不重复添加。

属性

属性	类型	默认值	说明
type	NSafeAreaType	bottom	top 顶部状态区域，bottom 底部手势区域
background	string	空串	背景颜色或方向关键词渐变；空串跟随主题
transparent	boolean	false	背景透明，保留占位；覆盖 background
customClass	string	空串	根节点自定义类，类须定义在组件内
customStyle	string	空串	外观、宽度与外间距；高度、布局、变换、内边距及边框宽度由组件管理

事件

无组件事件；这是布局占位，不承载点击或请求行为。

插槽

名称	参数	说明
default	无	占位区域内的装饰内容；不要把业务操作按钮塞进安全区

样式

--n-safe-area-background 设置默认背景颜色。transparent=true 时不绘制背景；渐变请通过 background 传入 linear-gradient(to right, ...)。组件内提供 n-safe-area--muted 类，将整体透明度设为 0.5。根 customStyle 接受主题令牌、背景、颜色、透明度、阴影、圆角、边框颜色、宽度与外间距。高度、布局方向、定位、变换、内边距与边框宽度不作为定制通道，包括逻辑方向声明；固定位置由父级容器处理。样式解析保留引号和函数值内的分号。连续修改渐变会重建背景层，插槽实例保持不变。显式背景独立于主题变量绘制，允许 background 引用 var(--n-safe-area-background)。

平台兼容性

高度读自 uni.getWindowInfo().safeAreaInsets，各端取值口径一致：iPhone 异形屏底部约 34px、顶部约 47~59px；Android 手势条机型有值，三键导航、无刘海设备与桌面浏览器通常为 0——占位高度为 0 是正常结果，组件不人为补高度。横竖屏与窗口尺寸变化后读数自动刷新。

限制：真机旋转、键盘弹出场景与鸿蒙端尚未在本地验证；如遇与系统手势区域不贴合等异常，以系统读数为基准反馈。