cordova-plugin-statusbar

Android Testsuite Chrome Testsuite iOS Testsuite Lint Test

StatusBar 物件提供一些功能來自訂 iOS 和 Android 狀態列。

安裝

此安裝方法需要 Cordova 5.0+

cordova plugin add cordova-plugin-statusbar

也可以直接透過 repo 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 meta 標籤中包含 viewport-fit=cover

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

啟動時隱藏

在執行期間，您可以使用下面的 StatusBar.hide 函數，但如果您希望狀態列在 iOS 上應用程式啟動時隱藏，則必須修改應用程式的 Info.plist 檔案。

如果不存在，請新增/編輯這兩個屬性。將「Status bar is initially hidden」設定為「YES」，並將「View controller-based status bar appearance」設定為「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