StatusBar

用于控制应用状态栏的组件。状态栏是屏幕顶部的区域，通常显示当前时间、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 引入的边到边强制执行，在 API 级别 35 中设置状态栏背景色已被弃用，并且设置后不会生效。你可以在这里阅读更多关于我们的 边到边建议。

Type	Required	Default
color	No	default system StatusBar background color, or 'black' if not defined

---

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 引入的边到边强制执行，在 API 级别 35 中将状态栏设置为半透明已被弃用，并且设置后不会生效。你可以在这里阅读更多关于我们的 边到边建议。

Type	Default
boolean	false

方法

popStackEntry()

React TSX

static popStackEntry(entry: StatusBarProps);

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

参数：

Name	Type	Description
entry Required	any	来自 pushStackEntry 返回的条目。

---

pushStackEntry()

React TSX

static pushStackEntry(props: StatusBarProps): StatusBarProps;

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

参数：

Name	Type	Description
props Required	any	包含要在堆栈条目中使用的 StatusBar 属性的对象。

---

replaceStackEntry()

React TSX

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

使用新属性替换现有的 StatusBar 堆栈条目。

参数：

Name	Type	Description
entry Required	any	要替换的、来自 pushStackEntry 返回的条目。
props Required	any	包含要用于替换堆栈条目的 StatusBar 属性的对象。

---

setBackgroundColor()

Android

React TSX

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

设置状态栏的背景色。

注意

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

参数：

Name	Type	Description
color Required	string	背景色。
animated	boolean	设置样式更改时添加动画。

---

setBarStyle()

React TSX

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

设置状态栏样式。

参数：

Name	Type	Description
style Required	StatusBarStyle	要设置的状态栏样式。
animated	boolean	设置样式更改时添加动画。

---

setHidden()

React TSX

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

显示或隐藏状态栏。

参数：

Name	Type	Description
hidden Required	boolean	隐藏状态栏。
animation iOS	StatusBarAnimation	更改状态栏 hidden 属性时的动画。

---

🗑️ setNetworkActivityIndicatorVisible()

iOS

Deprecated

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

React TSX

static setNetworkActivityIndicatorVisible(visible: boolean);

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

参数：

Name	Type	Description
visible Required	boolean	显示指示器。

---

setTranslucent()

Android

React TSX

static setTranslucent(translucent: boolean);

控制状态栏的半透明性。

注意

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

参数：

Name	Type	Description
translucent Required	boolean	设为半透明。

类型定义

StatusBarAnimation

用于 iOS 上过渡效果的状态栏动画类型。

类型
枚举

常量：

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

---

StatusBarStyle

状态栏样式类型。

类型
枚举

常量：

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