StatusBar プラグイン

StatusBar オブジェクトを使用して、iOS と Android のステータスバーをカスタマイズできます

このプラグインの詳細は、 こちらの原文 ( GitHub ) をご確認ください。

プラグイン ID

cordova-plugin-statusbar

プラグインの追加方法

このプラグインを使用する場合には、Monaca クラウド IDE の [ Cordova プラグインの管理 ] 上で、StatusBar プラグインを有効にします。

Peference を使用したカスタマイズ設定

config.xml

• StatusBarOverlaysWebView ( デフォルトでは true ) アプリの起動時、WebView 上にステータスバーを置くか ( overlay/オーバーレイ ) 否かを設定します。

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

• StatusBarBackgroundColor ( 16 進数の文字列で示すカラーコード、デフォルトはなし ) アプリ起動時のスタータスバーの背景色を、16進数の文字列 ( #RRGGBB ) で設定します。この値が設定されていない場合、背景色は透明になります。StatusBarOverlaysWebViewがtrueに設定されている場合、オプションで8桁の16進数（#AARRGGBB）文字列を使用して、透明度を定義することができる。

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

• StatusBarStyle ( ステータスバーのスタイル、デフォルトは lightcontent ) ステータスバーのスタイル ( 色 ) を設定します。 default、lightcontent、blacktranslucent、blackopaque のいずれかを設定できます。iOS 7 が対象です。

<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");
}

iOS 特有の動作

iOS 11以降、ステータスバーをウェブビューにオーバーレイさせたい場合は、viewport metaタグにviewport-fit=coverを含める必要があります

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

メソッド

このプラグインは、グローバルな 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.overlaysWebView

iOS 7 のステータスバーを上書きします ( WebView の上書きではありません )。

    StatusBar.overlaysWebView(true);

解説

iOS 7 のステータスバーを、iOS 6 のように表示したい場合、false に設定します。

例

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

StatusBar.styleDefault

デフォルトのステータスバーを使用します ( 黒の文字、白の背景 )。

    StatusBar.styleDefault();

StatusBar.styleLightContent

lightContent のステータスバーを使用します ( 白の文字、黒の背景 )。

    StatusBar.styleLightContent();

StatusBar.backgroundColorByName

StatusBar.overlaysWebView を false にした場合 ( iOS 7 上で iOS 6 のようなステータスバーを使用 )、色の名前を指定して、ステータスバーの背景色を設定できます。

    StatusBar.backgroundColorByName("red");

サポート対象の色の名前は、次のとおりです。

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

StatusBar.backgroundColorByHexString

16 進数の文字列を使用して、ステータスバーの背景色を設定します。

    StatusBar.backgroundColorByHexString("#C0C0C0");

CSS のショートハンド プロパティ ( 簡略化表記 ) も使用できます。

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

StatusBar.overlaysWebView を false にした場合 ( iOS 7 上で iOS 6 のようなステータスバーを使用 )、16 進数の文字列 ( #RRGGBB ) を使用して、ステータスバーの背景色を設定できます。

StatusBar.hide

ステータスバーを非表示にします。

    StatusBar.hide();

StatusBar.show

ステータスバーを表示します。

    StatusBar.show();

プロパティ

StatusBar.isVisible

ステータスバーの状態 ( 表示または非表示 ) を確認する場合には、このプロパティを使用します。

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

イベント

statusTap

このイベントを監視して、ステータスバーがタップされたかどうかを確認します。iOSのみ対応。

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