Ionicオーバーレイ

IonicモーダルなどのWebオーバーレイをEngine管理下のネイティブコンテンツより上に表示する場合に、このアダプターを使います。ネイティブ登録はキャプチャと復元を処理しますが、ネイティブビューからIonicの表示ライフサイクルを推定することはできません。この共有モニターが、すべての登録に対して被覆を判定します。

まずCapacitorまたはCordovaのガイドに従ってプラグインを組み込みます。Ionic以外のアプリケーションは独自のライフサイクル通知を使い、このアダプターを導入しません。

たとえば、Ionicの設定モーダルを開くと、背景のネイティブタブバーは覆いながら、モーダル自身のネイティブの閉じるボタンは操作可能に保つ必要があります。一律の非表示通知では、この関係を表せません。共有モニターはオーバーレイの積み重なりに対して各ホストを評価するため、独立したプラグインでも同じ被覆ルールを使えます。

一度だけ有効化する

Ionicアプリケーションでは、アプリの起動時に一度だけ呼び出します。アプリから直接呼び出す場合は、@webview-native-ui/engineをアプリの直接依存としてインストールしてください。

import { enableSupportIonicOverlays } from '@webview-native-ui/engine/ionic';

enableSupportIonicOverlays();

プラグインのメンテナーは、アプリのセットアップ手順にこのコードを記載するか、既存のJS初期化関数内で呼び出せます。@rdlabo/capacitor-native-uiは内部で同じ初期化関数を呼び出しているため、その利用者による追加の呼び出しは不要です。Ionic以外のアプリでは省略します。ネイティブ登録だけではIonicイベントのリスナーは追加されません。

被覆とライフタイム

npmモジュールとSwift/Androidから注入されたランタイムの間でも、ドキュメントごとに1つのモニターを共有します。繰り返し初期化してもリスナーは増えず、明示した設定も消えません。1つの投影を破棄しても、その購読だけを解除し、他のプラグインが使うモニターは停止しません。モニターはドキュメントとともに存続します。

デフォルトではModal、Popover、Alert、Action Sheet、Loading、Picker、Toast、Menuのライフサイクルイベントを扱います。各投影のDOMと有効なオーバーレイスタックを比較し、最前面のモーダル内のコンテンツはネイティブのまま、覆われたコンテンツは一時的に準備済み画像を使います。Toastや有効でないシートの背景は、サーフェスを覆いません。オーバーレイが入れ子の場合、残りのスタックが復元を許可するまで被覆を維持します。画像がなければ通常のWebフォールバックを保ちます。この一時的な被覆で、プラグインが明示したwebやnoneの投影先を上書きすることはありません。後から登録された投影も現在の状態を読み取ります。

ネイティブウィンドウに表示されるPopoverは、WebView内に描画されるPopoverとは異なります。そのDOMプレースホルダーを、上を覆うWebオーバーレイとして扱ってはいけません。@rdlabo/capacitor-native-uiプラグインは、このネイティブ表示の所有権をモニターへ通知します。ネイティブ表示に失敗すると所有権を解放し、モニターは通常のWebオーバーレイの被覆判定を再開します。この例外には明示的な連携が必要であり、PopoverのDOMだけから推定するものではありません。

特殊なレイアウトのカスタマイズ

任意の設定はドキュメント全体に適用されます。通常のIonicオーバーレイではデフォルトを維持してください。ネイティブコンテンツを覆うべきでないアプリのオーバーレイにはexcludeを、同じアプリが独自のライフサイクルイベントを持つカスタムダイアログも使う場合にはadditionalを指定します。DOMの包含関係と背景の状態だけでは、その特殊なレイアウトが実際に覆うホストを表せない場合にのみcoversを使います。

enableSupportIonicOverlays({
  exclude: '[data-nonblocking-overlay]',
  additional: [
    {
      selector: 'app-dialog',
      events: {
        willPresent: 'appDialogWillPresent',
        didDismiss: 'appDialogDidDismiss',
      },
    },
  ],
});

登録済みDOM投影に独自の被覆ルールが必要な場合にのみ、covers(overlay, target)を使います。デフォルトに従う場合はundefined、上書きする場合は真偽値を返します。除外指定と明示的なネイティブウィンドウの所有権が優先されます。標準の関係は、任意のCSSスタッキングコンテキストを解釈するのではなく、オーバーレイの順序、DOMの包含関係、背景の状態を使います。特殊なレイアウトは明示的に設定してください。