StatusBar

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

与 Navigator 一起使用

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

TypeScript

JavaScript

命令式 API

在某些情况下，使用组件可能不是理想选择，因此也提供了一个命令式 API，它作为组件上的静态函数公开。但不建议对同一属性同时使用静态 API 和组件，因为静态 API 设置的任何值都会在下一次渲染中被组件设置的值覆盖。

---

参考

常量

currentHeight

Android

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

---

属性

animated

状态栏属性更改之间的过渡是否应 animated。backgroundColor、barStyle 和 hidden 属性支持此属性。

类型	必需	默认值
布尔值	否	false

---

backgroundColor

Android

状态栏的背景颜色。

warning

由于 Android 15 中引入的 edge-to-edge 强制执行，在 API 级别 35 中设置状态栏的背景颜色已被弃用。

类型	必需	默认值
颜色	否	默认系统 StatusBar 背景颜色，如果未定义则为 'black'

---

barStyle

设置状态栏文本的颜色。

在 Android 上，这仅对 API 版本 23 及以上版本有效。

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

---

hidden

状态栏是否隐藏。

类型	必需	默认值
布尔值	否	false

---

networkActivityIndicatorVisible

iOS

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

类型	默认值
布尔值	false

---

showHideTransition

iOS

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

类型	默认值
StatusBarAnimation	'fade'

---

translucent

Android

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

类型	默认值
布尔值	false

方法

popStackEntry()

tsx

static popStackEntry(entry: StatusBarProps);

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

参数

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

---

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 级别 35 中设置状态栏的背景颜色已被弃用。

参数

名称	类型	描述
颜色 必需	字符串	背景颜色。
animated	布尔值	动画样式更改。

---

setBarStyle()

tsx

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

设置状态栏样式。

参数

名称	类型	描述
样式 必需	StatusBarStyle	要设置的状态栏样式。
animated	布尔值	动画样式更改。

---

setHidden()

tsx

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

显示或隐藏状态栏。

参数

名称	类型	描述
hidden 必需	布尔值	隐藏状态栏。
动画 iOS	StatusBarAnimation	更改状态栏 hidden 属性时的动画。

---

setNetworkActivityIndicatorVisible()

iOS

tsx

static setNetworkActivityIndicatorVisible(visible: boolean);

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

参数

名称	类型	描述
visible 必需	布尔值	显示指示器。

---

setTranslucent()

Android

tsx

static setTranslucent(translucent: boolean);

控制状态栏的半透明度。

参数

名称	类型	描述
translucent 必需	布尔值	设置为半透明。

类型定义

StatusBarAnimation

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

类型
枚举

常量

值	类型	描述
'fade'	字符串	淡入动画
'slide'	字符串	滑动动画
'none'	字符串	无动画

---

StatusBarStyle

状态栏样式类型。

类型
枚举

常量

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