跳到主要内容
版本：v8

SystemBars

SystemBars API 提供了配置设备系统栏/状态栏样式和可见性的方法。此 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) 存在一个 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 } 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
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

编辑此页