cordova-plugin-statusbar

Android Testsuite Chrome Testsuite iOS Testsuite Lint Test

StatusBar 对象提供了一些函数来自定义 iOS 和 Android 状态栏。

安装

此安装方法需要 cordova 5.0+

cordova plugin add cordova-plugin-statusbar

也可以直接通过仓库 URL 安装（不稳定）

cordova plugin add https://github.com/apache/cordova-plugin-statusbar.git

首选项

config.xml

  • StatusBarOverlaysWebView（布尔值，默认为 true）。使状态栏在启动时覆盖或不覆盖 WebView。

     <preference name="StatusBarOverlaysWebView" value="true" />

    ##### Android 特性

    仅在 Android 5 或更高版本上受支持。早期版本将忽略此首选项。

  • StatusBarBackgroundColor（颜色十六进制字符串，无默认值）。在启动时通过十六进制字符串（#RRGGBB）设置状态栏的背景颜色。如果未设置此值，则背景颜色将为透明。如果 StatusBarOverlaysWebView 设置为 true，则可以选择使用 8 位十六进制（#AARRGGBB）字符串来定义透明度。

      <preference name="StatusBarBackgroundColor" value="#000000" />

  • StatusBarStyle（状态栏样式，默认为 lightcontent）。设置状态栏样式（例如文本颜色）。可用选项：default、lightcontent。

      <preference name="StatusBarStyle" value="lightcontent" />

  • StatusBarDefaultScrollToTop（布尔值，默认为 false）。在 iOS 上，允许 Cordova WebView 使用默认的滚动到顶部行为。默认为 false，因此您可以监听“statusTap”事件（如下所述）并自定义行为。

      <preference name="StatusBarDefaultScrollToTop" value="false" />

Android 特性

Android 5+ 指南指定使用与主应用程序颜色不同的颜色作为状态栏颜色（与许多 iOS 应用程序的统一状态栏颜色不同），因此您可能希望在运行时通过 StatusBar.backgroundColorByHexString 或 StatusBar.backgroundColorByName 设置状态栏颜色。一种方法是

if (cordova.platformId == 'android') {
    StatusBar.backgroundColorByHexString("#333");
}

也可以使状态栏半透明。Android 使用十六进制 ARGB 值，格式为 #AARRGGBB。前一对字母 AA 代表 alpha 通道。您必须将十进制不透明度值转换为十六进制值。您可以阅读更多关于它的信息 这里。

例如，一个不透明度为 20% 的黑色状态栏

if (cordova.platformId == 'android') {
    StatusBar.overlaysWebView(true);
    StatusBar.backgroundColorByHexString('#33000000');
}

iOS 特性

从 iOS 11 开始，如果您希望状态栏覆盖 webview，则必须在视窗元标记中包含 viewport-fit=cover

<meta name="viewport" content="initial-scale=1, width=device-width, viewport-fit=cover">

启动时隐藏

在运行时，您可以使用下面的 StatusBar.hide 函数，但如果您希望状态栏在 iOS 上的应用程序启动时隐藏，则必须修改应用程序的 Info.plist 文件。

如果不存在，请添加/编辑这两个属性。将“状态栏最初隐藏”设置为“YES”，并将“基于视图控制器的状态栏外观”设置为“NO”。如果您在没有 Xcode 的情况下手动编辑它，则键和值是

<key>UIStatusBarHidden</key>
<true/>
<key>UIViewControllerBasedStatusBarAppearance</key>
<false/>

方法

此插件定义了全局 StatusBar 对象。

虽然在全局范围内，但在 deviceready 事件之后才能使用它。

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(StatusBar);
}
  • StatusBar.overlaysWebView
  • StatusBar.styleDefault
  • StatusBar.styleLightContent
  • StatusBar.backgroundColorByName
  • StatusBar.backgroundColorByHexString
  • StatusBar.hide
  • StatusBar.show

属性

  • StatusBar.isVisible

事件

  • statusTap

StatusBar.overlaysWebView

使状态栏覆盖或不覆盖 WebView。

StatusBar.overlaysWebView(true);

描述

设置为 true 使状态栏覆盖在应用程序顶部。确保您相应地调整样式，以便应用程序的标题栏或内容不会被覆盖。设置为 false 使状态栏变为实心，并且不覆盖您的应用程序。然后，您可以使用其他函数设置适合的样式和背景颜色。

支持的平台

  • iOS
  • Android 5+

快速示例

StatusBar.overlaysWebView(true);
StatusBar.overlaysWebView(false);

StatusBar.styleDefault

使用默认状态栏（深色文本，用于浅色背景）。

StatusBar.styleDefault();

支持的平台

  • iOS
  • Android 6+

StatusBar.styleLightContent

使用 lightContent 状态栏（浅色文本，用于深色背景）。

StatusBar.styleLightContent();

支持的平台

  • iOS
  • Android 6+

StatusBar.backgroundColorByName

在 iOS 上，当您将 StatusBar.overlaysWebView 设置为 false 时，您可以通过颜色名称设置状态栏的背景颜色。

StatusBar.backgroundColorByName("red");

支持的颜色名称是

black, darkGray, lightGray, white, gray, red, green, blue, cyan, yellow, magenta, orange, purple, brown

支持的平台

  • iOS
  • Android

StatusBar.backgroundColorByHexString

通过十六进制字符串设置状态栏的背景颜色。

StatusBar.backgroundColorByHexString("#C0C0C0");

也支持 CSS 简写属性。

StatusBar.backgroundColorByHexString("#333"); // => #333333
StatusBar.backgroundColorByHexString("#FAB"); // => #FFAABB

在 iOS 上，当您将 StatusBar.overlaysWebView 设置为 false 时，您可以通过十六进制字符串（#RRGGBB）设置状态栏的背景颜色。

在 Android 上，当 StatusBar.overlaysWebView 为 true 时，以及在 WP7&8 上，您也可以将值指定为 #AARRGGBB，其中 AA 是 alpha 值。

支持的平台

  • iOS
  • Android

StatusBar.hide

隐藏状态栏。

StatusBar.hide();

支持的平台

  • iOS
  • Android

StatusBar.show

显示状态栏。

StatusBar.show();

支持的平台

  • iOS
  • Android

StatusBar.isVisible

读取此属性以查看状态栏是否可见。

if (StatusBar.isVisible) {
	// do something
}

支持的平台

  • iOS
  • Android

statusTap

监听此事件以了解状态栏是否被点击。

window.addEventListener('statusTap', function() {
    // scroll-up with document.body.scrollTop = 0; or do whatever you want
});

支持的平台

  • iOS