# StatusBar プラグイン

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

このプラグインの詳細は、 [こちらの原文 ( GitHub )](https://github.com/apache/cordova-plugin-statusbar) をご確認ください。

### プラグイン ID

```javascript
cordova-plugin-statusbar
```

### プラグインの追加方法

このプラグインを使用する場合には、Monaca クラウド IDE の \[ Cordova プラグインの管理 ] 上で、`StatusBar` プラグインを[有効](https://ja.docs.monaca.io/products_guide/monaca_ide/dependencies/cordova_plugin#cordova-puraguin-noinpto)にします。

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

#### config.xml

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

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

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

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

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

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

* **StatusBarDefaultScrollToTop** ( ブール値、デフォルトは false ) \
  \
  iOSの場合、Cordova WebViewがデフォルトのスクロールトゥトップ動作を使用することを許可します。デフォルトは false で、代わりに "statusTap" イベント (後述) をリッスンして動作をカスタマイズすることができます。

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

#### Android 特有の動作

Android 5+のガイドラインでは、ステータスバーにメインアプリの色とは異なる色を使用することが指定されています（多くのiOSアプリのステータスバーの色が統一されているのとは異なります）ので、ステータスバーの色を`StatusBar.backgroundColorByHexString`または`StatusBar.backgroundColorByNameで`実行時に設定することが望ましいかもしれません。そのための一つの方法として、次のようなものがあります：

```javascript
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` イベントの発火後まで使用できません。

```javascript
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 の上書きではありません )。

```javascript
    StatusBar.overlaysWebView(true);
```

#### 解説

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

#### 例

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

### StatusBar.styleDefault

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

```javascript
    StatusBar.styleDefault();
```

### StatusBar.styleLightContent

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

```javascript
    StatusBar.styleLightContent();
```

### StatusBar.backgroundColorByName

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

```javascript
    StatusBar.backgroundColorByName("red");
```

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

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

### StatusBar.backgroundColorByHexString

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

```javascript
    StatusBar.backgroundColorByHexString("#C0C0C0");
```

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

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

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

### StatusBar.hide

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

```javascript
    StatusBar.hide();
```

### StatusBar.show

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

```javascript
    StatusBar.show();
```

## プロパティ

### StatusBar.isVisible

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

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

## イベント

### statusTap

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

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