跳到主要内容
版本：v8

@capacitor/status-bar

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

安装​

npm install @capacitor/status-bar
npx cap sync

Android 16+ 行为更改​

对于使用 Capacitor 8 面向 Android 16(API 级别 36) 及更高版本的应用,以下状态栏配置选项不再起作用：

  • overlaysWebView
  • backgroundColor

这些选项依赖于能够选择退出 Android 的边到边系统 UI 行为,该行为允许应用控制状态栏覆盖方式及其背景颜色。

在 Android 15(API 级别 35) 中,仍可能通过在应用布局文件中设置 windowOptOutEdgeToEdgeEnforcement 属性来选择退出此强制行为。如果没有该属性,应用将假定 overlaysWebView 始终为 true。 在 Android 文档中查看更多详细信息：https://developer.android.com/reference/android/R.attr#windowOptOutEdgeToEdgeEnforcement

从 Android 16 开始,此选择退出不再可用,并且该行为由系统强制执行。 因此,overlaysWebView 和 backgroundColor 配置选项不再起任何作用。

iOS 注意事项​

此插件需要在 Info.plist 中将"基于视图控制器的状态栏外观"(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();
};

配置​

这些配置值可用：

PropTypeDescriptionDefaultSince
overlaysWebViewboolean状态栏是否覆盖。在 Android 15+ 上不可用。true1.0.0
stylestring状态栏文本的样式。default1.0.0
backgroundColorstring状态栏背景的颜色,十六进制格式,#RRGGBB。如果 overlaysWebView 为 true 则不起作用。在 Android 15+ 上不可用。#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>

设置状态栏的当前样式。

ParamType
options
StyleOptions

Since: 1.0.0

setBackgroundColor(...)​

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

设置状态栏的背景颜色。 如果样式设置为默认值,则调用此函数会更新状态栏的前景色,但在 iOS 17 以下的版本中除外。 在 Android 15+ 上不可用。

ParamType
options
BackgroundColorOptions

Since: 1.0.0

show(...)​

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

显示状态栏。 在 iOS 上,如果状态栏最初隐藏且初始样式设置为 UIStatusBarStyleLightContent,首次显示调用可能会在动画上显示故障,将文本显示为深色然后过渡到浅色。建议在第一次调用时使用 Animation.None 作为动画。

ParamType
options
AnimationOptions

Since: 1.0.0

hide(...)​

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

隐藏状态栏。

ParamType
options
AnimationOptions

Since: 1.0.0

getInfo()​

getInfo() => Promise<StatusBarInfo>

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

Returns: 

Promise<StatusBarInfo>

Since: 1.0.0

setOverlaysWebView(...)​

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

设置状态栏是否应覆盖 webview 以允许使用其下方的空间。 在 Android 15+ 上不可用。

ParamType
options
SetOverlaysWebViewOptions

Since: 1.0.0

Interfaces​

StyleOptions​

PropTypeDescriptionSince
style
Style
状态栏文本的样式。1.0.0

BackgroundColorOptions​

PropTypeDescriptionSince
colorstring状态栏颜色设置的十六进制颜色。1.0.0

AnimationOptions​

PropTypeDescriptionDefaultSince
animation
Animation
显示或隐藏时使用的状态栏动画类型。此选项仅在 iOS 上支持。Animation.Fade1.0.0

StatusBarInfo​

PropTypeDescriptionSince
visibleboolean状态栏是否可见。1.0.0
style
Style
当前状态栏样式。1.0.0
colorstring当前状态栏颜色。1.0.0
overlaysboolean状态栏是否覆盖。1.0.0

SetOverlaysWebViewOptions​

PropTypeDescriptionSince
overlayboolean是否覆盖状态栏。1.0.0

Enums​

Style​

MembersValueDescriptionSince
Dark'DARK'深色背景的浅色文本。1.0.0
Light'LIGHT'浅色背景的深色文本。1.0.0
Default'DEFAULT'样式基于设备外观。如果设备使用深色模式,状态栏文本将为浅色。如果设备使用浅色模式,状态栏文本将为深色。1.0.0

Animation​

MembersValueDescriptionSince
None'NONE'显示/隐藏期间没有动画。1.0.0
Slide'SLIDE'显示/隐藏期间的滑动动画。在 iOS 15+ 上不起作用。1.0.0
Fade'FADE'显示/隐藏期间的淡入淡出动画。1.0.0

Contents

编辑此页