跳到主要内容

状态栏

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

与 Navigator 一起使用​

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

命令式 API​

对于使用组件不太理想的情况，还提供了一个以组件上的静态函数形式暴露的命令式 API。不过，不建议对同一个属性同时使用静态 API 和组件，因为静态 API 设置的任何值都会在下一次渲染时被组件设置的值覆盖。

参考

常量​

currentHeight
Android
​

状态栏的高度，如果存在刘海屏，则包括刘海高度。

Props​

animated​

如果状态栏属性变化之间的过渡应该进行动画。支持 backgroundColor、barStyle 和 hidden 属性。

TypeRequiredDefault
booleanNofalse

backgroundColor
Android
​

状态栏的背景颜色。

注意

由于 Android 15 引入的全屏边到边强制要求，在 API 级别 35 中设置状态栏背景颜色已被弃用，并且设置后不会产生任何效果。你可以在这里阅读更多关于我们的 全屏边到边建议。

TypeRequiredDefault
colorNo默认系统 StatusBar 背景颜色，或在未定义时为 'black'

barStyle​

设置状态栏文本的颜色。

在 Android 上，这只会对 API 版本 23 及以上产生影响。

TypeRequiredDefault
StatusBarStyleNo'default'

hidden​

状态栏是否隐藏。

TypeRequiredDefault
booleanNofalse

networkActivityIndicatorVisible
iOS
​

网络活动指示器是否应可见。

TypeDefault
booleanfalse

showHideTransition
iOS
​

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

TypeDefault
StatusBarAnimation'fade'

translucent
Android
​

状态栏是否为半透明。将 translucent 设为 true 时，应用会在状态栏下方绘制内容。这在使用半透明状态栏颜色时很有用。

注意

由于 Android 15 引入的全屏边到边强制要求，在 API 级别 35 中将状态栏设为半透明已被弃用，并且设置后不会产生任何效果。你可以在这里阅读更多关于我们的 全屏边到边建议。

TypeDefault
booleanfalse

方法​

popStackEntry()​

React TSX
static popStackEntry(entry: StatusBarProps);

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

参数：

名称类型描述
entry
必填
any从 pushStackEntry 返回的条目。

pushStackEntry()​

React TSX
static pushStackEntry(props: StatusBarProps): StatusBarProps;

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

参数：

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

replaceStackEntry()​

React TSX
static replaceStackEntry(
  entry: StatusBarProps,
  props: StatusBarProps
): StatusBarProps;

使用新的 props 替换现有的 StatusBar 栈条目。

参数：

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

setBackgroundColor()
Android
​

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

设置状态栏的背景色。

注意

由于 Android 15 中引入的边到边（edge-to-edge）强制要求，在 API 级别 35 中设置状态栏背景色已被弃用，设置后将不起作用。你可以在这里阅读更多关于我们的边到边建议。

参数：

名称类型描述
color
必填
string背景色。
animatedboolean是否为样式更改添加动画。

setBarStyle()​

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

设置状态栏样式。

参数：

名称类型描述
style
必填
StatusBarStyle要设置的状态栏样式。
animatedboolean是否为样式更改添加动画。

setHidden()​

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

显示或隐藏状态栏。

参数：

名称类型描述
hidden
必填
boolean隐藏状态栏。
animation
iOS
StatusBarAnimation更改状态栏隐藏属性时的动画。

🗑️ setNetworkActivityIndicatorVisible()
iOS
​

Deprecated

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

React TSX
static setNetworkActivityIndicatorVisible(visible: boolean);

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

参数：

名称类型描述
visible
必填
boolean显示指示器。

setTranslucent()
Android
​

React TSX
static setTranslucent(translucent: boolean);

控制状态栏的透明度。

注意

由于 Android 15 中引入的边到边（edge-to-edge）强制要求，在 API 级别 35 中将状态栏设为半透明已被弃用，设置后将不起作用。你可以在这里阅读更多关于我们的边到边建议。

参数：

名称类型描述
translucent
必填
boolean设为半透明。

Type Definitions​

StatusBarAnimation​

iOS 上过渡时的状态栏动画类型。

类型
枚举

常量：

值类型描述
'fade'string淡出动画
'slide'string滑动动画
'none'string无动画

StatusBarStyle​

状态栏样式类型。

类型
枚举

常量：

值类型描述
'default'string默认状态栏样式（iOS 为深色，Android 为浅色）
'light-content'string白色文本和图标
'dark-content'string深色文本和图标（Android 上需要 API>=23）