跳到主要内容
版本：v8

SystemBars

SystemBars API 提供了配置设备系统栏/状态栏样式和可见性的方法。此插件随 @capacitor/core 捆绑提供。

此 API 与 Status Bar 插件的不同之处在于，它仅旨在支持未来的现代全屏（edge to edge）使用场景。对于旧版功能，请使用 Status Bar 插件。

特性System BarsStatus Bar
setOverlaysWebView()不支持在 iOS 和 Android <= 14（或在启用了全屏选择退出的情况下为 15）上受支持
setBackgroundColor()不支持支持
setStyle()支持支持 - 仅顶部状态栏
hide()/show()支持支持 - 仅顶部状态栏

iOS 注意​

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

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

Android 注意​

由于某些较旧版本的 Android WebView（< 140）中存在一个 bug，无法通过 CSS env 变量 safe-area-inset-x 获取正确的安全区域值。此插件会将正确的内边距值注入到一个名为 --safe-area-inset-x 的新 CSS 变量中，你可以在前端样式中将其作为后备方案使用：

html {
  padding-top: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));
  padding-bottom: var(--safe-area-inset-bottom, env(safe-area-inset-bottom, 0px));
  padding-left: var(--safe-area-inset-left, env(safe-area-inset-left, 0px));
  padding-right: var(--safe-area-inset-right, env(safe-area-inset-right, 0px));
}

要控制此行为，请使用 insetsHandling 配置设置。

示例​

import { SystemBars, SystemBarsStyle, SystemBarType } from '@capacitor/core';

const setSystemBarStyleDark = async () => {
  await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
};

const setSystemBarStyleLight = async () => {
  await SystemBars.setStyle({ style: SystemBarsStyle.Light });
};

const hideSystemBars = async () => {
  await SystemBars.hide();
};

const showSystemBars = async () => {
  await SystemBars.show();
};

const hideNavigationBar = async () => {
  await SystemBars.hide({
    bar: SystemBarType.NavigationBar
  })
}

// 设置状态栏动画，仅限 iOS
const setStatusBarAnimation = async () => {
  await SystemBars.setAnimation({ animation: "NONE" });
}

配置​

属性类型描述默认值
insetsHandlingstring指定如何处理 Android 上有问题的内边距。此选项仅在 Android 上受支持。
css = 将包含正确安全区域内边距值的 CSS 变量（--safe-area-inset-*）注入到 webview 中。
disable = 禁用 CSS 变量注入。		css
stylestring系统栏文本和图标的样式。DEFAULT
hiddenboolean启动时隐藏系统栏。false
animationstring显示或隐藏时使用的状态栏动画类型。此选项仅在 iOS 上受支持。FADE

示例配置​

在 capacitor.config.json 中：

{
  "plugins": {
    "SystemBars": {
      "insetsHandling": "css",
      "style": "DARK",
      "hidden": false,
      "animation": "NONE"
    }
  }
}

在 capacitor.config.ts 中：

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

const config: CapacitorConfig = {
  plugins: {
    SystemBars: {
      insetsHandling: "css",
      style: "DARK",
      hidden: false,
      animation: "NONE"
    },
  },
};

export default config;

API​

setStyle(...)​

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

设置系统栏当前样式。

参数类型
options
SystemBarsStyleOptions

始于： 8.0.0

show(...)​

show(options?: SystemBarsVisibilityOptions) => Promise<void>

显示系统栏。

参数类型
options
SystemBarsVisibilityOptions

始于： 8.0.0

hide(...)​

hide(options?: SystemBarsVisibilityOptions) => Promise<void>

隐藏系统栏。

参数类型
options
SystemBarsVisibilityOptions

始于： 8.0.0

setAnimation(...)​

setAnimation(options: SystemBarsAnimationOptions) => Promise<void>

设置显示/隐藏状态栏时使用的动画。

仅适用于 iOS。

参数类型
options
SystemBarsAnimationOptions

始于： 8.0.0

接口​

SystemBarsStyleOptions​

属性类型描述默认值始于
style
SystemBarsStyle
系统栏文本和图标的样式。'DEFAULT'8.0.0
bar
SystemBarType
要应用样式的系统栏。null8.0.0

SystemBarsVisibilityOptions​

属性类型描述默认值始于
bar
SystemBarType
要隐藏或显示的系统栏。null8.0.0
animation
SystemBarsAnimation
显示或隐藏时使用的状态栏动画类型。此选项仅在 iOS 上受支持。'FADE'8.0.0

SystemBarsAnimationOptions​

属性类型描述默认值始于
animation
SystemBarsAnimation
显示或隐藏时使用的状态栏动画类型。此选项仅在 iOS 上受支持。'FADE'8.0.0

类型别名​

SystemBarsAnimation​

可用的状态栏动画。仅 iOS。

'FADE' | 'NONE'

枚举​

SystemBarsStyle​

成员值描述始于
Dark'DARK'深色背景上的浅色系统栏内容。8.0.0
Light'LIGHT'浅色背景上的深色系统栏内容。8.0.0
Default'DEFAULT'样式基于设备外观或底层内容。如果设备使用深色模式，系统栏内容将为浅色。如果设备使用浅色模式，系统栏内容将为深色。8.0.0

SystemBarType​

成员值描述始于
StatusBar'StatusBar'Android 和 iOS 上的顶部状态栏。8.0.0
NavigationBar'NavigationBar'Android 和 iOS 上的导航栏（或 iOS 上的手势栏）。8.0.0

Contents

编辑此页