跳到主要内容
版本：v7

@capacitor/status-bar

StatusBar API 提供了配置状态栏样式以及显示或隐藏状态栏的方法。

安装​

npm install @capacitor/status-bar@latest-7
npx cap sync

iOS 注意事项​

此插件需要在 Info.plist 中将 "View controller-based status bar appearance"（UIViewControllerBasedStatusBarAppearance）设置为 YES。有关帮助，请阅读 配置 iOS。

状态栏默认可见，样式默认为 Style.Default。您可以通过在 Info.plist 中添加 UIStatusBarHidden 和/或 UIStatusBarStyle 来更改这些默认值。

示例​

import { StatusBar, Style } from '@capacitor/status-bar';

// 仅 iOS
window.addEventListener('statusTap', function () {
  console.log('状态栏被点击');
});

// 在透明状态栏下显示内容
StatusBar.setOverlaysWebView({ overlay: true });

const setStatusBarStyleDark = async () => {
  await StatusBar.setStyle({ style: Style.Dark });
};

const setStatusBarStyleLight = async () => {
  await StatusBar.setStyle({ style: Style.Light });
};

const hideStatusBar = async () => {
  await StatusBar.hide();
};

const showStatusBar = async () => {
  await StatusBar.show();
};

配置​

以下是可用的配置值：

属性类型描述默认值自版本
overlaysWebViewboolean状态栏是否覆盖。对于目标为 Android 15 的应用程序，除非在应用程序布局文件中添加了 windowOptOutEdgeToEdgeEnforcement 属性，否则此属性无效。否则，应用程序会假定始终覆盖为 true。更多详情请参见 https://developer.android.com/reference/android/R.attr#windowOptOutEdgeToEdgeEnforcementtrue1.0.0
stylestring状态栏文字的 样式。default1.0.0
backgroundColorstring状态栏背景颜色的十六进制格式，格式为 #RRGGBB。如果 overlaysWebView 为 true，则无效。#0000001.0.0

示例​

在 capacitor.config.json 中：

{
  "plugins": {
    "StatusBar": {
      "overlaysWebView": false,
      "style": "DARK",
      "backgroundColor": "#ffffffff"
    }
  }
}

在 capacitor.config.ts 中：

/// <reference types="@capacitor/status-bar" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    StatusBar: {
      overlaysWebView: false,
      style: "DARK",
      backgroundColor: "#ffffffff",
    },
  },
};

export default config;

API​

setStyle(...)​

setStyle(options: StyleOptions) => Promise<void>

设置状态栏的当前样式。

参数类型
options
StyleOptions

自版本: 1.0.0

setBackgroundColor(...)​

setBackgroundColor(options: BackgroundColorOptions) => Promise<void>

设置状态栏的背景颜色。

参数类型
options
BackgroundColorOptions

自版本: 1.0.0

show(...)​

show(options?: AnimationOptions | undefined) => Promise<void>

显示状态栏。 在 iOS 上，如果状态栏最初是隐藏的且初始样式设置为 UIStatusBarStyleLightContent，首次调用 show 可能会在动画中出现文字先显示为深色再过渡为浅色的闪烁问题。建议在首次调用时使用 Animation.None 作为动画。

参数类型
options
AnimationOptions

自版本: 1.0.0

hide(...)​

hide(options?: AnimationOptions | undefined) => Promise<void>

隐藏状态栏。

参数类型
options
AnimationOptions

自版本: 1.0.0

getInfo()​

getInfo() => Promise<StatusBarInfo>

获取状态栏当前状态的信息。

返回: 

Promise<StatusBarInfo>

自版本: 1.0.0

setOverlaysWebView(...)​

setOverlaysWebView(options: SetOverlaysWebViewOptions) => Promise<void>

设置状态栏是否应覆盖 WebView，以允许使用其下方的空间。

参数类型
options
SetOverlaysWebViewOptions

自版本: 1.0.0

addListener('statusBarVisibilityChanged', ...)​

addListener(eventName: 'statusBarVisibilityChanged', listenerFunc: VisibilityChangeListener) => Promise<PluginListenerHandle>

监听状态栏可见性变化。 在调用 hide 或 show 方法时触发。

参数类型
eventName'statusBarVisibilityChanged'
listenerFunc
VisibilityChangeListener

返回: 

Promise<PluginListenerHandle>

自版本: 7.0.0

addListener('statusBarOverlayChanged', ...)​

addListener(eventName: 'statusBarOverlayChanged', listenerFunc: OverlayChangeListener) => Promise<PluginListenerHandle>

监听状态栏覆盖变化。 在调用 setOverlaysWebView 时触发。

参数类型
eventName'statusBarOverlayChanged'
listenerFunc
OverlayChangeListener

返回: 

Promise<PluginListenerHandle>

自版本: 7.0.0

接口​

StyleOptions​

属性类型描述自版本
style
Style
状态栏文字的样式。1.0.0

BackgroundColorOptions​

属性类型描述自版本
colorstring状态栏颜色设置的十六进制颜色。1.0.0

AnimationOptions​

属性类型描述默认值自版本
animation
Animation
显示或隐藏时使用的状态栏动画类型。此选项仅在 iOS 上支持。Animation.Fade1.0.0

StatusBarInfo​

属性类型描述自版本
visibleboolean状态栏是否可见。1.0.0
style
Style
当前状态栏样式。1.0.0
colorstring当前状态栏颜色。1.0.0
overlaysboolean状态栏是否覆盖。1.0.0
heightnumber状态栏的高度。7.0.0

SetOverlaysWebViewOptions​

属性类型描述自版本
overlayboolean是否覆盖状态栏。1.0.0

PluginListenerHandle​

属性类型
remove() => Promise<void>

类型别名​

VisibilityChangeListener​

(info: StatusBarInfo): void

OverlayChangeListener​

(info: StatusBarInfo): void

枚举​

Style​

成员值描述自版本
Dark'DARK'深色背景的浅色文字。1.0.0
Light'LIGHT'浅色背景的深色文字。1.0.0
Default'DEFAULT'样式基于设备外观。如果设备使用深色模式，状态栏文字为浅色。如果设备使用浅色模式，状态栏文字为深色。1.0.0

Animation​

成员值描述自版本
None'NONE'显示/隐藏时无动画。1.0.0
Slide'SLIDE'显示/隐藏时的滑动动画。在 iOS 15+ 上无效。1.0.0
Fade'FADE'显示/隐藏时的淡入淡出动画。1.0.0

Contents

编辑此页