概念と制約
目的は、柔軟なWebレイアウトやナビゲーションと、ネイティブのコントロールや機能をひとつの画面で組み合わせることです。アプリはWeb主体のUIを維持し、プラグインがネイティブコンポーネントを提供します。Engineは両者の表示を調整し、レイアウト変更、操作、ナビゲーションの間も、各コンポーネントが周囲の画面と共存できるようにします。
ブリッジの呼び出しだけでは足りない理由
ネイティブビューを作成しても、DOM内での配置が決まるわけではありません。WebViewの上のビューは、スクロールコンテナへの追従や、そのクリッピングと重なり順には自動で参加しません。Web側のz-indexを高くしても、その上に表示できません。単に非表示と表示を切り替えると、異なる外観が見えたり、古い位置に復元されたりすることがあります。
共通の組み込みモデルは、ネイティブビューとDOMコンテナの組み合わせです。コンテナがWeb画面内でのコンポーネントの位置を定めます。プラグインはネイティブコンテンツを提供して変更を通知し、Engineは計測、準備済みの外観、表示レイヤー間の切り替えを調整します。
共存の具体例
以下の状況は、同じ表示モデルを共有します。各組み込みは、必要なライフサイクル通知と値の通知を接続します。
| 状況 | 期待する体験 | 共通モデルの役割 |
|---|---|---|
| 対応可能なネイティブ広告をWebフィードに配置する | 読者のスクロール中もコンテンツと位置が揃う。 | DOMコンテナがジオメトリを提供し、対応するネイティブ追従または一時的なWeb投影が動きに追従する。 |
| ネイティブのナビゲーションコントロールの上にWebアラートを開く | アラートがその外観を覆い、閉じるとネイティブ操作が戻る。 | ライフサイクル通知またはIonicアダプターが被覆を要求し、Engineが画像への切り替えと復元を調整する。 |
| ページやモーダルのレイアウトが変わる | ネイティブコントロールが、古い矩形ではなく現在の位置に戻る。 | 所有コンテナのライフタイムに合わせてジオメトリと復元を調整する。 |
| Webフォールバックが非表示の間にネイティブのトグルが変わる | HTMLへ戻しても古い値が表示されない。 | 任意の値バインディングが、表示とは独立してコンポーネントのデータを反映する。 |
スクロールが常にライブのネイティブビューの移動を意味するわけではありません。対応するiOSのoverflowレイアウトではネイティブスクロールバインディングを利用できます。Androidでは一時的な画像表示を使い、未対応のレイアウトでは設定済みのフォールバック方針に従います。画像はSDKのライブ操作を提供しません。プラットフォームの制約とスクロールバインディングの制約を参照してください。
Engineはネイティブコンテンツを利用できる間に画像を準備し、表示切り替え中も、ネイティブ復元の確認応答まで保持します。準備と表示は分離されているため、オーバーレイを開く際にキャプチャを待つことはありません。アプリ固有のライフサイクル判断には通知が必要です。ビューを登録するだけで、すべてのフレームワークのオーバーレイを自動検出できるわけではありません。
目的の異なる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フォールバックで何を表示するかは、組み込む前に決めてください。適用条件と失敗時の方針は、キャプチャとプラットフォームのリファレンスおよび投影の契約を参照してください。