跳到主要内容
版本：v8

SystemBars

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

此 API 与 Status Bar 插件的区别在于，它仅旨在支持现代的全屏（edge-to-edge）应用场景。如需旧版功能，请使用 Status Bar 插件。

功能System BarsStatus Bar
setOverlaysWebView()不支持在 iOS 和 Android <= 14（或启用 edge-to-edge 退出时为 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) 中存在一个 错误，无法通过 safe-area-inset-x CSS env 变量获取正确的安全区域值。此插件会将正确的插入值注入到名为 --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 = 向 WebView 注入包含正确安全区域插入值的 CSS 变量 (--safe-area-inset-*)。
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

编辑此页