状态栏
用于控制应用状态栏的组件。状态栏是屏幕顶部的区域，通常会显示当前时间、Wi‑Fi 和蜂窝网络信息、电池电量和/或其他状态图标。
与 Navigator 一起使用
可以同时挂载多个 StatusBar 组件。属性会按照 StatusBar 组件的挂载顺序进行合并。
- TypeScript
- JavaScript
命令式 API
对于不适合使用组件的场景，也提供了一个作为组件静态函数暴露的命令式 API。不过，不建议对同一属性同时使用静态 API 和组件，因为通过静态 API 设置的任何值都会在下一次渲染时被组件设置的值覆盖。
参考
常量
currentHeight Android
状态栏的高度，如果存在刘海屏，则包含刘海的高度。
属性
animated
如果状态栏属性更改之间的过渡应当带有动画。支持 backgroundColor、barStyle 和 hidden 属性。
| Type | Required | Default |
|---|---|---|
| boolean | No | false |
backgroundColor Android
状态栏的背景颜色。
由于 Android 15 引入了 edge-to-edge 强制执行，在 API 级别 35 中设置状态栏背景颜色已被弃用，并且设置后不会产生任何效果。你可以在这里阅读更多关于我们的 edge-to-edge 建议。
| Type | Required | Default |
|---|---|---|
| color | No | 默认系统 StatusBar 背景颜色；如果未定义，则为 'black' |
barStyle
设置状态栏文字的颜色。
在 Android 上，这只会对 API 版本 23 及以上产生影响。
| Type | Required | Default |
|---|---|---|
| StatusBarStyle | No | 'default' |
hidden
状态栏是否隐藏。
| Type | Required | Default |
|---|---|---|
| boolean | No | false |
networkActivityIndicatorVisible iOS
网络活动指示器是否应当可见。
| Type | Default |
|---|---|
| boolean | false |
showHideTransition iOS
使用 hidden 属性显示和隐藏状态栏时的过渡效果。
| Type | Default |
|---|---|
| StatusBarAnimation | 'fade' |
translucent Android
状态栏是否半透明。将 translucent 设为 true 时，应用会在状态栏下方绘制内容。这在使用半透明状态栏颜色时很有用。
由于 Android 15 引入了 edge-to-edge 强制执行，在 API 级别 35 中将状态栏设为半透明已被弃用，并且设置后不会产生任何效果。你可以在这里阅读更多关于我们的 edge-to-edge 建议。
| Type | Default |
|---|---|
| boolean | false |
方法
popStackEntry()
static popStackEntry(entry: StatusBarProps);
获取并移除栈中的最后一个 StatusBar 条目。
参数：
| Name | Type | Description |
|---|---|---|
| entry Required | any | 从 pushStackEntry 返回的条目。 |
pushStackEntry()
static pushStackEntry(props: StatusBarProps): StatusBarProps;
将一个 StatusBar 条目压入栈中。完成后应将返回值传递给 popStackEntry。
参数：
| Name | Type | Description |
|---|---|---|
| props Required | any | 包含要在栈条目中使用的 StatusBar 属性的对象。 |
replaceStackEntry()
static replaceStackEntry(
entry: StatusBarProps,
props: StatusBarProps
): StatusBarProps;
用新的属性替换现有的 StatusBar 栈条目。
参数：
| Name | Type | Description |
|---|---|---|
| entry Required | any | 要替换的、由 pushStackEntry 返回的条目。 |
| props Required | any | 包含要用于替换栈条目的 StatusBar 属性的对象。 |
setBackgroundColor() Android
static setBackgroundColor(color: ColorValue, animated?: boolean);
设置状态栏的背景颜色。
由于 Android 15 引入了 edge-to-edge 强制执行，在 API 级别 35 中设置状态栏背景颜色已被弃用，并且设置后不会产生任何效果。你可以在这里阅读更多关于我们的 edge-to-edge 建议。
参数：
| Name | Type | Description |
|---|---|---|
| color Required | string | 背景颜色。 |
| animated | boolean | 为样式更改添加动画。 |
setBarStyle()
static setBarStyle(style: StatusBarStyle, animated?: boolean);
设置状态栏样式。
参数：
| Name | Type | Description |
|---|---|---|
| style Required | StatusBarStyle | 要设置的状态栏样式。 |
| animated | boolean | 为样式更改添加动画。 |
setHidden()
static setHidden(hidden: boolean, animation?: StatusBarAnimation);
显示或隐藏状态栏。
参数：
| Name | Type | Description |
|---|---|---|
| hidden Required | boolean | 隐藏状态栏。 |
| animation iOS | StatusBarAnimation | 更改状态栏 hidden 属性时的动画。 |
🗑️ setNetworkActivityIndicatorVisible() iOS
状态栏网络活动指示器不受 iOS 13 及更高版本支持。此功能将在未来的版本中移除。
static setNetworkActivityIndicatorVisible(visible: boolean);
控制网络活动指示器的可见性。
参数：
| Name | Type | Description |
|---|---|---|
| visible Required | boolean | 显示指示器。 |
setTranslucent() Android
static setTranslucent(translucent: boolean);
控制状态栏的半透明效果。
由于 Android 15 引入了 edge-to-edge 强制执行，在 API 级别 35 中将状态栏设为半透明已被弃用，并且设置后不会产生任何效果。你可以在这里阅读更多关于我们的 edge-to-edge 建议。
参数：
| Name | Type | Description |
|---|---|---|
| translucent Required | boolean | 设为半透明。 |
类型定义
StatusBarAnimation
iOS 上过渡动画的状态栏动画类型。
| 类型 |
|---|
| enum |
常量：
| 值 | 类型 | 描述 |
|---|---|---|
'fade' | string | 淡出动画 |
'slide' | string | 滑动动画 |
'none' | string | 无动画 |
StatusBarStyle
状态栏样式类型。
| 类型 | | ---- | ---- | | enum |
常量：
| 值 | 类型 | 描述 |
|---|---|---|
'default' | string | 默认状态栏样式（iOS 为深色，Android 为浅色） |
'light-content' | string | 白色文本和图标 |
'dark-content' | string | 深色文本和图标（Android 需要 API>=23） |