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（カラーの16進数文字列、デフォルト値なし）。起動時に16進数文字列（#RRGGBB）でステータスバーの背景色を設定します。この値が設定されていない場合、背景色は透明になります。StatusBarOverlaysWebViewがtrueに設定されている場合、透明度を定義するために8桁の16進数文字列（#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を使用して、実行時にステータスバーの色を設定することをお勧めします。その方法の1つは、

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

ステータスバーを半透明にすることも可能です。Androidは16進数のARGB値を使用し、#AARRGGBBのようにフォーマットされます。最初の2文字のAAはアルファチャネルを表します。10進数の不透明度値を16進数の値に変換する必要があります。詳細については、こちらを参照してください。

たとえば、不透明度が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でアプリ起動時にStatusBarを非表示にするには、アプリのInfo.plistファイルを変更する必要があります。

存在しない場合は、これらの2つの属性を追加/編集します。「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

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

StatusBar.backgroundColorByHexString("#C0C0C0");

CSSの省略記法プロパティもサポートされています。

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

iOSでは、StatusBar.overlaysWebViewをfalseに設定すると、16進数文字列（#RRGGBB）でステータスバーの背景色を設定できます。

Androidでは、StatusBar.overlaysWebViewがtrueの場合、およびWP7＆8では、#AARRGGBB（AAはアルファ値）として値を指定することもできます。

サポートされているプラットフォーム

  • 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