n-status-bar 状态栏占位

用于隐藏原生导航栏后的自定义页面，按系统状态栏高度填充顶部空间。它绘制应用内容中的背景与占位，不改变系统时间、电量、图标颜色或状态栏显隐。

实现说明

机制	参考做法	本库做法与取舍
自动高度	读取系统状态栏高度，组件不开放任意高度	使用 `uni.getWindowInfo().statusBarHeight`，以 px 渲染；挂载、页面尺寸改变及返回页面时重新读取，不用底部安全区或导航栏高度代算
背景	透明默认，提供背景色；另一实现接受渐变	统一为 `bgColor`，默认透明，支持实色、CSS 变量及方向关键词形式的 linear-gradient；与本库导航栏命名一致
固定及占位	固定顶部，可独立开启等高占位	统一为 `fixed` 与 `placeholder`；非固定始终占据一个状态栏高度，固定时仅 placeholder=true 才留空间；不重复拼接 px 单位
层级	固定时可设 z-index，默认 99	`zIndex` 默认 99，仅 fixed=true 时作用于栏体
内容	默认插槽位于状态栏内部	默认插槽保留，内容裁切在真实状态栏范围内；用于装饰，避免放交互控件或与系统图标争用空间
初始化	回传带 px 单位的高度字符串	`init` 在挂载后触发一次，返回 `{ statusBarHeight: number }`，单位 px，供布局直接计算
定制	个别实现有不同根样式入口	沿用统一 customClass/customStyle；完整解析声明并以对象绑定，保留引号和函数内的分号；外观、宽度与外间距可定制，系统几何、定位和变换不可覆盖

平台兼容性

支持 Web、微信小程序与 App(Android/iOS/鸿蒙) 的窗口信息 API。普通 Web 无系统状态栏时高度为 0，不人为补高度。iOS 横屏可能返回 0，Android 横屏返回值以系统 API 为准。

在 pages.json 为页面配置 "navigationStyle": "custom" 后使用；已有原生导航栏或 n-navbar 已垫状态栏时，不要再次叠加。组件不处理微信胶囊区域；需要完整导航栏时使用 n-navbar。

与 n-safe-area 的分工：给状态栏绘制背景或做等高占位用本组件（读系统状态栏高度，支持固定与层级）；只需要通用的顶部避让、不涉及状态栏背景时（如钉顶横幅避开异形屏）用 n-safe-area type="top"（读顶部安全区）。自定义导航页两个读数一致；同一页只用其中一个负责顶部，避免叠出两份高度。

基本用法

vue

<template>
  <n-page>
    <n-status-bar bg-color="var(--n-bg-1, #ffffff)" @init="onInit" />
    <view><text>页面内容</text></view>
  </n-page>
</template>
<script setup lang="uts">
import { ref } from "vue";
import type { NStatusBarInit } from "@/uni_modules/new-ui/components/n-status-bar/props";
const initialHeight = ref(0);
function onInit(detail: NStatusBarInit): void {
  initialHeight.value = detail.statusBarHeight;
}
</script>

固定且为正文保留等高空间：

vue

<n-status-bar fixed placeholder :z-index="99" bg-color="linear-gradient(to right, #6366f1, #a855f7)" />

CSS 变量可用于实色，渐变请传完整 linear-gradient(...) 表达式，其中的颜色也可引用变量。

默认透明背景可由主题令牌 --n-status-bar-bg 或编译时 $n-status-bar-bg 统一设置；显式 bgColor 优先。customStyle 作用于根占位节点，背景定制应使用 bgColor；页面自定义 class 无法穿透样式隔离。

customStyle 支持颜色、透明度、阴影、圆角、--n- 主题变量、宽度和外间距。高度、内边距（包括逻辑方向）、边框宽度、flex、定位和变换由组件管理，相关声明不会进入渲染层，避免改变系统高度或固定栏体的定位基准。

API

Props

属性	类型	默认值	说明
bgColor	string	""	栏体背景；空值使用透明背景令牌，支持实色、变量与线性渐变
fixed	boolean	false	是否固定在窗口顶部
placeholder	boolean	false	固定时是否保留等高占位；非固定时始终自然占位
zIndex	number	99	固定栏体的层级
customClass	string	""	根节点类，须定义在组件样式表内
customStyle	string	""	根节点外观、主题变量、宽度与外间距；系统几何、定位和变换不可覆盖

Events

事件	参数	说明
init	NStatusBarInit	挂载后触发一次，statusBarHeight 为数值，单位 px；窗口变化会刷新布局，不重复触发 init

Slots

插槽	说明
default	状态栏内部装饰内容，裁切在真实高度内；不提供交互语义

公共方法

无。

官方平台依据：窗口信息、组件生命周期。

n-status-bar 状态栏占位 ​

实现说明 ​

平台兼容性 ​

基本用法 ​

API ​

Props ​

Events ​

Slots ​

公共方法 ​