テーマに Native UI を追加する

@rdlabo/ionic-theme-ios27 を利用しているアプリに、テーマのスタイル、Web コンテンツ、ルーティングを維持したまま iOS のネイティブコントロールを追加できます。非対応のコントロール、ブラウザー、Android では Web の外観を維持します。
テーマをまだ設定していない場合はテーマのセットアップから始めてください。別の Web 外観を使用する場合は Native UI のセットアップに進んでください。
ネイティブコントロールと Web DOM・ハンドラーの接続については、投影の仕組みを参照してください。
 1. ネイティブプラグインをインストールするこのガイドは iOS プロジェクトを持つ Capacitor 8 アプリを想定します。Web のみのテーマ利用には Capacitor は不要ですが、iOS のネイティブコントロールを追加するには先にネイティブプロジェクトが必要です。対応する Ionic、iOS、Xcode のバージョンは Native UI の要件を参照してください。
テーマと Native UI は同時に更新してバージョンを揃え、Foldable はアプリの独立した依存関係としてインストールします。
npm install @rdlabo/ionic-theme-ios27 @rdlabo/capacitor-native-ui @erkamyaman/capacitor-foldable
既存のテーマのスタイルシートは維持してください。Capacitor の標準のプラグイン検出には直接依存が必要です。テーマ経由でインストールされるだけではネイティブプラグインは登録されません。
 2. ネイティブコントロールを有効にするアプリの起動時に、ion-app のマウント後、一度だけ Shell を有効にします。
import { enableNativeUI } from '@rdlabo/capacitor-native-ui';

const shell = await enableNativeUI();
アプリの所有コンポーネントを破棄するときに await shell.destroy() を呼び出します。ページごとに Shell を作成しないでください。Angular・React・Vue のアプリルートの例に沿って起動とクリーンアップを接続してください。
テーマパッケージの navAnimation: iosTransitionAnimation は維持します。画面遷移や戻るジェスチャーでのネイティブコントロールの調整を含むため、再度ラップしないでください。独自のアニメーションでは遷移アダプターの手順を参照してください。
プラグインのインストールやテーマのアニメーション設定だけでは、ネイティブコントロールは有効になりません。アプリが上記の起動呼び出しで有効にします。
 3. iOS を同期して実行するWeb アセットをビルドしてから実行します。
npx cap sync ios
対応する iOS デバイスまたはシミュレーターでアプリを実行します。対象の固定コントロールがネイティブ表示になり、既存のハンドラーが呼び出されることを確認してください。前後の画面に遷移し、ブラウザーでも Web フォールバックを確認します。対応する iOS ですべて Web 表示のままなら、直接依存、起動呼び出し、同期、ネイティブの再ビルドを確認してください。対象のマークアップとフォールバック動作は対応コントロールを参照してください。Web コンテンツと投影されないコントロールのためにテーマのスタイルは維持します。
 任意: Vertical Barsサイドレールには Vertical Bars の標準セットアップを使用します。レイアウトのスタイルシートを読み込み、インストール済みの Foldable プラグインの初期配置とイベントを接続します。Shell はレールのランタイムを含むため、追加の起動呼び出しは不要です。標準の起動設定は水平・レール双方のコントロールを選択するため、既存の Native UI にレールを加える場合も維持してください。自動投影をレールだけに限定したい場合のみ enableNativeUI({ controls: 'verticalOnly' }) を使用します。設定オプションを参照してください。
 既存のネイティブ連携を更新するテーマパッケージからネイティブ API をインポートしていた場合は、ネイティブインポートの移行とネイティブプロジェクトの移行に従ってください。通常のテーマのインポートとスタイルシートは維持します。
GitHubでこのページを編集