StatusBar プラグイン

テスト環境 ( バージョン番号 ) : 2.4.3

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

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

プラグイン ID

cordova-plugin-statusbar

プラグインの追加方法

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

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

config.xml

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

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

• StatusBarBackgroundColor ( 16 進数の文字列で示すカラーコード、デフォルトはなし )。アプリ起動時のスタータスバーの背景色を、16進数の文字列 ( #RRGGBB ) で設定します。この値が設定されていない場合、背景色は透明になります。[ 翻訳者メモ : 原文には、「 on iOS 7 」 とありますが、他のバージョンでも使用されていることから、この表現を削除しています ]

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

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

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

• StatusBarDefaultScrollToTop ( ブール値、デフォルトは false ) 。iOS 7 では、Cordova WebView は、デフォルトの scroll-to-top 動作を使用できます。 デフォルトでは false に設定されているため、 "statusTap" イベント（後述）を使用し、動作をカスタマイズすることができます。

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

Android 特有の動作

Android 5+ を対象とする、多くのガイドラインでは、スタータスバーとアプリのテーマに、別々の色を指定するように推奨されています ( 一方、iOS 7+ 向けのアプリでは、スタータスバーとアプリのカラーを統一する方が多いようです )。ここでは、ステータスバーの色をあらかじめ設定するのではなく ( StatusBar.backgroundColorByHexString または StatusBar.backgroundColorByName を設定 )、動的 ( プログラムの実行時 ) に設定する方法の一例を記します。

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

アプリ起動時の非表示設定

アプリの実行中は、後述する StatusBar.hide 関数を使用できます。また、アプリ起動時にステータスバーを非表示にしたい場合は、アプリの 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.styleBlackTranslucent

• StatusBar.styleBlackOpaque

• StatusBar.backgroundColorByName

• StatusBar.backgroundColorByHexString

• StatusBar.hide

• StatusBar.show

StatusBar.overlaysWebView

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

    StatusBar.overlaysWebView(true);

解説

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

対象プラットフォーム

• iOS

例

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

StatusBar.styleDefault

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

    StatusBar.styleDefault();

対象プラットフォーム

• iOS

• Android 6+

StatusBar.styleLightContent

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

    StatusBar.styleLightContent();

対象プラットフォーム

• iOS

• Android 6+

StatusBar.styleBlackTranslucent

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

    StatusBar.styleBlackTranslucent();

対象プラットフォーム

• iOS

StatusBar.styleBlackOpaque

blackOpaque のステータスバーを使用します ( 白の文字、不透明な黒の背景 )。

    StatusBar.styleBlackOpaque();

対象プラットフォーム

• iOS

• Android 6+

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

対象プラットフォーム

• iOS

• Android 5+

StatusBar.backgroundColorByHexString

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

    StatusBar.backgroundColorByHexString("#C0C0C0");

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

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

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

対象プラットフォーム

• iOS

• Android 5+

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

パーミッション

config.xml

    <feature name="StatusBar">
        <param name="ios-package" value="CDVStatusBar" onload="true" />
    </feature>