跳到主要内容

StatusBar

用于控制应用状态栏的组件。状态栏是屏幕顶部的区域，通常显示当前时间、Wi-Fi 和蜂窝网络信息、电池电量和/或其他状态图标。

和导航器一起使用​

可以同时挂载多个 StatusBar 组件。属性将按照 StatusBar 组件的挂载顺序进行合并。

命令式 API​

对于不适合使用组件的场景，StatusBar 也提供了以组件静态方法形式暴露的命令式 API。不过不推荐同时使用静态 API 和组件来设置同一个属性，因为静态 API 设置的值会在下一次渲染时被组件设置的值覆盖。

参考

常量​

currentHeight
Android
​

状态栏的高度，包括刘海高度（如果有的话）。

Props​

animated​

状态栏属性变化时是否使用动画过渡。支持 backgroundColor、barStyle 和 hidden 属性。

类型必需默认值
boolean否false

backgroundColor
Android
​

状态栏的背景色。

warning

由于 Android 15 引入的全面屏（edge-to-edge）强制要求，在 API level 35 中设置状态栏背景色已被弃用，设置将不会生效。你可以在这里阅读我们的全面屏适配建议。

类型必需默认值
color否默认系统状态栏背景色，如果未定义则为 'black'

barStyle​

设置状态栏文本的颜色。

在 Android 上，此属性仅对 API 23 及以上版本生效。

类型必需默认值
StatusBarStyle否'default'

hidden​

是否隐藏状态栏。

类型必需默认值
boolean否false

networkActivityIndicatorVisible
iOS
​

是否显示网络活动指示器。

类型默认值
booleanfalse

showHideTransition
iOS
​

使用 hidden 属性显示和隐藏状态栏时的过渡效果。

类型默认值
StatusBarAnimation'fade'

translucent
Android
​

指定状态栏是否透明。设置为 true 时，应用会在状态栏下方绘制内容。这在使用半透明状态栏背景色时非常有用。

warning

由于 Android 15 引入的全面屏（edge-to-edge）强制要求，在 API level 35 中设置状态栏透明已被弃用，设置将不会生效。你可以在这里阅读我们的全面屏适配建议。

类型默认值
booleanfalse

方法​

popStackEntry()​

tsx
static popStackEntry(entry: StatusBarProps);

获取并移除栈中最后一个 StatusBar 条目。

参数：

名称类型描述
entry
必需
anypushStackEntry 返回的条目。

pushStackEntry()​

tsx
static pushStackEntry(props: StatusBarProps): StatusBarProps;

将一个 StatusBar 条目压入栈中。返回值应在完成后传递给 popStackEntry。

参数：

名称类型描述
props
必需
any包含要在栈条目中使用的 StatusBar 属性的对象。

replaceStackEntry()​

tsx
static replaceStackEntry(
  entry: StatusBarProps,
  props: StatusBarProps
): StatusBarProps;

用新的属性替换栈中已有的 StatusBar 条目。

参数：

名称类型描述
entry
必需
any要替换的 pushStackEntry 返回的条目。
props
必需
any包含要在替换栈条目中使用的 StatusBar 属性的对象。

setBackgroundColor()
Android
​

tsx
static setBackgroundColor(color: ColorValue, animated?: boolean);

设置状态栏的背景色。

warning

由于 Android 15 引入的全面屏（edge-to-edge）强制要求，在 API level 35 中设置状态栏背景色已被弃用，设置将不会生效。你可以在这里阅读我们的全面屏适配建议。

参数：

名称类型描述
color
必需
string背景色。
animatedboolean是否使用动画过渡。

setBarStyle()​

tsx
static setBarStyle(style: StatusBarStyle, animated?: boolean);

设置状态栏的样式。

参数：

名称类型描述
style
必需
StatusBarStyle要设置的状态栏样式。
animatedboolean是否使用动画过渡。

setHidden()​

tsx
static setHidden(hidden: boolean, animation?: StatusBarAnimation);

显示或隐藏状态栏。

参数：

名称类型描述
hidden
必需
boolean是否隐藏状态栏。
animation
iOS
StatusBarAnimation改变状态栏隐藏属性时的动画效果。

🗑️ setNetworkActivityIndicatorVisible()
iOS
​

已弃用

iOS 13 及更高版本不再支持状态栏网络活动指示器。此方法将在未来版本中移除。

tsx
static setNetworkActivityIndicatorVisible(visible: boolean);

控制网络活动指示器的可见性。

参数：

名称类型描述
visible
必需
boolean是否显示指示器。

setTranslucent()
Android
​

tsx
static setTranslucent(translucent: boolean);

控制状态栏的透明度。

warning

由于 Android 15 引入的全面屏（edge-to-edge）强制要求，在 API level 35 中设置状态栏透明已被弃用，设置将不会生效。你可以在这里阅读我们的全面屏适配建议。

参数：

名称类型描述
translucent
必需
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）