StatusBar
控制应用状态栏的组件。状态栏是一个区域，通常位于屏幕顶部，显示当前时间、Wi-Fi 和蜂窝网络信息、电池电量和/或其他状态图标。
¥Component to control the app's status bar. The status bar is the zone, typically at the top of the screen, that displays the current time, Wi-Fi and cellular network information, battery level and/or other status icons.
与导航器一起使用
¥Usage with Navigator
可以同时安装多个 StatusBar 组件。属性将按照 StatusBar 组件的安装顺序合并。
¥It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.
- TypeScript
- JavaScript
命令式 API
¥Imperative API
对于使用组件不理想的情况，还有一个命令式 API 在组件上公开为静态函数。然而，不建议对同一个 prop 使用静态 API 和组件，因为静态 API 设置的任何值都将被组件在下一次渲染中设置的值覆盖。
¥For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.
参考
¥Reference
常量
¥Constants
currentHeight Android
状态栏的高度，包括凹口高度（如果存在）。
¥The height of the status bar, which includes the notch height, if present.
属性
¥Props
animated
如果状态栏属性变化之间的过渡应该是动画的。支持 backgroundColor、barStyle 和 hidden 属性。
¥If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden properties.
| 类型 | 必需的 | 默认 |
|---|---|---|
| boolean | 不 | false |
backgroundColor Android
状态栏的背景颜色。
¥The background color of the status bar.
由于 Android 15 中引入了边到边强制执行，在 API 级别 35 中已弃用设置状态栏的背景颜色。
¥Due to edge-to-edge enforcement introduced in Android 15, setting background color of the status bar is deprecated in API level 35.
| 类型 | 必需的 | 默认 |
|---|---|---|
| color | 不 | 默认系统 StatusBar 背景颜色，如果未定义则为 'black' |
barStyle
设置状态栏文本的颜色。
¥Sets the color of the status bar text.
在 Android 上，这只会对 API 版本 23 及更高版本产生影响。
¥On Android, this will only have an impact on API versions 23 and above.
| 类型 | 必需的 | 默认 |
|---|---|---|
| StatusBarStyle | 不 | 'default' |
hidden
如果状态栏被隐藏。
¥If the status bar is hidden.
| 类型 | 必需的 | 默认 |
|---|---|---|
| boolean | 不 | false |
networkActivityIndicatorVisible iOS
网络活动指示器是否应该可见。
¥If the network activity indicator should be visible.
| 类型 | 默认 |
|---|---|
| boolean | false |
showHideTransition iOS
使用 hidden 属性显示和隐藏状态栏时的过渡效果。
¥The transition effect when showing and hiding the status bar using the hidden prop.
| 类型 | 默认 |
|---|---|
| StatusBarAnimation | 'fade' |
translucent Android
如果状态栏是半透明的。当半透明设置为 true 时，应用将在状态栏下方绘制。当使用半透明状态栏颜色时这非常有用。
¥If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.
| 类型 | 默认 |
|---|---|
| boolean | false |
方法
¥Methods
popStackEntry()
static popStackEntry(entry: StatusBarProps);
获取并从堆栈中删除最后一个 StatusBar 条目。
¥Get and remove the last StatusBar entry from the stack.
参数：
¥Parameters:
| 名称 | 类型 | 描述 |
|---|---|---|
| 条目 必填 | any | 从 pushStackEntry 返回的条目。 |
pushStackEntry()
static pushStackEntry(props: StatusBarProps): StatusBarProps;
将 StatusBar 条目推入堆栈。完成后，返回值应传递给 popStackEntry。
¥Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.
参数：
¥Parameters:
| 名称 | 类型 | 描述 |
|---|---|---|
| 属性 必填 | any | 包含要在堆栈条目中使用的 StatusBar 属性的对象。 |
replaceStackEntry()
static replaceStackEntry(
entry: StatusBarProps,
props: StatusBarProps
): StatusBarProps;
用新的 props 替换现有的 StatusBar 堆栈条目。
¥Replace an existing StatusBar stack entry with new props.
参数：
¥Parameters:
| 名称 | 类型 | 描述 |
|---|---|---|
| 条目 必填 | any | 从 pushStackEntry 返回的条目要替换。 |
| 属性 必填 | any | 包含要在替换堆栈条目中使用的 StatusBar 属性的对象。 |
setBackgroundColor() Android
static setBackgroundColor(color: ColorValue, animated?: boolean);
设置状态栏的背景颜色。
¥Set the background color for the status bar.
由于 Android 15 中引入了边到边强制执行，在 API 级别 35 中已弃用设置状态栏的背景颜色。
¥Due to edge-to-edge enforcement introduced in Android 15, setting background color of the status bar is deprecated in API level 35.
参数：
¥Parameters:
| 名称 | 类型 | 描述 |
|---|---|---|
| 颜色 必填 | string | 背景颜色。 |
| animated | boolean | 以动画方式改变样式。 |
setBarStyle()
static setBarStyle(style: StatusBarStyle, animated?: boolean);
设置状态栏样式。
¥Set the status bar style.
参数：
¥Parameters:
| 名称 | 类型 | 描述 |
|---|---|---|
| 样式 必填 | StatusBarStyle | 要设置的状态栏样式。 |
| animated | boolean | 以动画方式改变样式。 |
setHidden()
static setHidden(hidden: boolean, animation?: StatusBarAnimation);
显示或隐藏状态栏。
¥Show or hide the status bar.
参数：
¥Parameters:
| 名称 | 类型 | 描述 |
|---|---|---|
| 隐藏 必填 | boolean | 隐藏状态栏。 |
| 动画 iOS | StatusBarAnimation | 更改状态栏隐藏属性时的动画。 |
setNetworkActivityIndicatorVisible() iOS
static setNetworkActivityIndicatorVisible(visible: boolean);
控制网络活动指示器的可见性。
¥Control the visibility of the network activity indicator.
参数：
¥Parameters:
| 名称 | 类型 | 描述 |
|---|---|---|
| 可见 必填 | boolean | 显示指标。 |
setTranslucent() Android
static setTranslucent(translucent: boolean);
控制状态栏的半透明度。
¥Control the translucency of the status bar.
参数：
¥Parameters:
| 名称 | 类型 | 描述 |
|---|---|---|
| 半透明 必需 | boolean | 设置为半透明。 |
类型定义
¥Type Definitions
StatusBarAnimation
iOS 上过渡的状态栏动画类型。
¥Status bar animation type for transitions on the iOS.
| 类型 |
|---|
| enum |
常量：
¥Constants:
| 值 | 类型 | 描述 |
|---|---|---|
'fade' | string | 淡入淡出动画 |
'slide' | string | 幻灯片动画 |
'none' | string | 无动画 |
StatusBarStyle
状态栏样式类型。
¥Status bar style type.
| 类型 |
|---|
| enum |
常量：
¥Constants:
| 值 | 类型 | 描述 |
|---|---|---|
'default' | string | 默认状态栏样式（iOS 为深色，Android 为浅色） |
'light-content' | string | 白色文本和图标 |
'dark-content' | string | 深色文本和图标（Android 上需要 API>=23） |