概念と制約
ネイティブビューをWebのスクロール、画面遷移、オーバーレイと共存させたい場合にEngineを使います。たとえばネイティブタブバーは、通常は操作可能なまま、Webモーダルを開いたときは見た目上その下に置けます。画面全体をネイティブで作り直さず、アプリのWebナビゲーションとレイアウトを維持できます。
ブリッジの呼び出しだけでは足りない理由
WebViewの上にあるネイティブビューは、DOMの重なりのツリーの外側にあります。Webモーダルのz-indexを増やしても覆えません。ネイティブビューを隠すと下のWebページの描画が見えますが、外観が異なるかもしれません。レイアウトが安定する前に再表示すると、間違った位置が見えてしまうことがあります。
Engineはレイヤー間の見た目のハンドオフを処理します。ネイティブコンテンツが利用できる間に画像を準備し、必要なときにアプリのDOM内へ表示して、ネイティブの復元が確認されるまで保持します。準備と表示を分けることで、オーバーレイを開くときにキャプチャを待ちません。
目的の異なる3つの表示
| 表示 | ユーザーに見えるもの | 利用する理由 |
|---|---|---|
| ライブのネイティブビュー | 実際に操作できるコントロールや対応するSDKビュー | 通常のネイティブ操作と描画。 |
| Web投影 | DOMコンテナ内の準備済みの操作できない画像 | ネイティブの外観をWebコンテンツとともに動かしたり、Webオーバーレイの下に置いたりできます。 |
| Webフォールバック | アプリ自身のHTML、または選択した空の状態 | 適切な画像を準備できなくても、組み込みを利用可能な状態に保ちます。 |
投影は、2つ目のライブコントロールではありません。クリックを転送せず、動画を動かさず、実際のネイティブビューを個々のDOM要素の下へ並べ替えることもありません。設定する投影先native、web、noneは、コンテンツをどこに置くべきかを表し、Engineがハンドオフの仕組みを選びます。厳密な優先順位と復元のルールは、投影の契約を参照してください。
組み込み側がDOMコンテナを用意する理由
コンテナは、アプリのレイアウトとレイヤー構造内で画像の置き場所を決めます。ネイティブの矩形だけでは、どのモーダル、クリッピングする祖先、スクロール領域に画像を置くべきかをEngineへ伝えられません。コンテナに既存のWebフォールバックがあってもかまいません。コンテンツとリスナーは投影をまたいで維持されます。
広告なら、スクロールフィード内のnative-ad要素かもしれません。タブバーなら、ページのオーバーレイレイヤーの下にあるフォールバックのナビゲーションコンテナかもしれません。意図したレイアウト領域を持つ対応コンテナを選びます。Engineはアプリのレイアウトを作らず、広告やタブバーの実装も提供しません。
要件を満たす最小の組み込みを選ぶ
| 作るもの | 入口 | この方式を使う理由 |
|---|---|---|
| タブバーやキャプチャ可能な広告ビューなど、ネイティブビューを公開するCapacitorプラグイン | Capacitorプラグインガイド | ネイティブ登録がランタイム起動、計測、ハンドオフの確認応答を管理し、既存のプラグインAPIを維持できます。 |
| 同じ要件を持つCordovaプラグイン | Cordovaプラグインガイド | Cordovaのネイティブフックとリソースハンドラーで同じライフサイクルを使います。 |
| ページやモーダルをまたぐ多数のコントロールをすでにバッチ処理するレンダラー | レンダラーガイド | 既存の配置と更新プロトコルを維持し、ライフサイクルごとにコントロールをまとめます。 |
| Engine対応プラグインを使うIonicアプリケーション | Ionicオーバーレイガイド | 1つの共有モニターが、Ionicオーバーレイのライフサイクルと投影の被覆を連携させます。 |
最小の登録と、任意設定・高度なAPIの選び分けは、ネイティブ初期化を参照してください。
Webモーダルがあるだけなら、レンダラーAPIは不要です。複数コントロールの調整をすでに管理していない限り、ネイティブのNativeUIProjection登録から始めます。通常、アプリは自ら登録を作るのではなく、Engineを組み込んだプラグインを通じて対応を得ます。他のWebフレームワークも独自の画面遷移通知を使えます。Ionicは任意です。
責務の境界
| Engine | 利用側のプラグイン |
|---|---|
| DOM計測、画像のジオメトリ、対応するネイティブスクロールバインディング | ネイティブビューの作成、取り付け、配置、サイズ設定 |
| 起動、イベント購読、ネイティブ描画の確認応答 | 適切なレイヤーへのフォールバックDOMの提供 |
| 準備済み画像のキャッシュ、デコード、表示、破棄 | 外観変更と意図した投影先の通知 |
| ネイティブキャプチャと一時的な復帰画像 | ネイティブビューとSDKのキャプチャ適格性の提供 |
| 画像の無効化、トークンの解放、監視の終了処理 | 業務上の操作と操作可能なWebフォールバックの所有 |
DOMコンテナに、操作可能なWebの代替が必ず入っているとは限りません。ボタンプラグインはHTMLボタンをフォールバックとして用意できますが、広告プラグインはネイティブコンテンツが利用できなければコンテナを空にする場合もあります。画像のハンドオフは明示的で、操作はできません。Engineは画像越しにクリックを転送せず、SDKのクリックやインプレッション処理も置き換えません。
ネイティブ登録は、現在のコンポーネント値を反映してフォールバックホストへ渡すこともできます。これは表示意図とは独立しています。選択タブはコンポーネントのデータであり、native、web、noneは表示先を表します。アプリケーションイベントとフレームワークのフォーム連携は、コンポーネントのアダプターに残ります。
制約がUIに適しているか判断する
画像は、コントロールとキャプチャした背景の両方を静止させます。覆われている間もライブ表示や操作が必要なコンテンツには、別の表示方針が必要です。SDKのキャプチャ制限は引き続き適用され、Liquid Glassのハイライトなど、プラットフォームのコンポジター効果の一部はキャプチャ時の外観と異なる場合があります。Engineは、すべてのネイティブビューをピクセル単位で同一にキャプチャすることを保証しません。
対応する実機で、実際の背景、オーバーレイの遷移、復元を検証してください。キャプチャできない場合にユーザーへ何を見せるかを、組み込み前にWebフォールバックで決めます。適格性、タイミング、ストレージ、失敗時の方針は、キャプチャとプラットフォームのリファレンスを参照してください。