ionic-angular

Ionic Angular

Angular を使用した Ionic 開発 — プロジェクト構成、Angular 固有のコンポーネント、ナビゲーション、遅延読み込み、フォーム、ライフサイクルとの統合。

前提条件

1. @ionic/angular を使用する Ionic Framework 7 または 8。
2. Angular 16 以降（スタンドアロンアーキテクチャには Angular 17 以降を推奨）。
3. Node.js と npm がインストールされていること。
4. Ionic CLI がインストールされていること（npm install -g @ionic/cli）。

エージェントの動作

• アーキテクチャを自動検出します。 src/main.ts を確認し、bootstrapApplication（スタンドアロン）と platformBrowserDynamic().bootstrapModule（NgModule）のどちらが使われているかを判定します。検出したアーキテクチャに合わせて、すべてのコード例を調整します。
• 手順を追って案内します。 一度に1つのトピックをユーザーに案内します。
• インポートを調整します。 スタンドアロンコンポーネントでは、各 Ionic コンポーネントを @ionic/angular/standalone からインポートします。NgModule コンポーネントでは、ページモジュールに IonicModule をインポートします。

手順

Step 1：プロジェクトを分析する

プロジェクトファイルを読み取り、以下の情報を自動検出します。推測できる情報をユーザーに尋ねてはいけません。

1. Ionic のバージョン：package.json から @ionic/angular のバージョンを読み取ります。
2. Angular のバージョン：package.json から @angular/core のバージョンを読み取ります。
3. アーキテクチャ：src/main.ts を確認し、bootstrapApplication（スタンドアロン）と platformBrowserDynamic().bootstrapModule（NgModule）のどちらが使われているかを判定します。src/app/app.module.ts が存在し、IonicModule をインポートしている場合は、NgModule であることを確認します。
4. Capacitor：package.json に @capacitor/core があるか確認します。android/ と ios/ ディレクトリも確認します。
5. ルーティング：src/app/app.routes.ts（スタンドアロン）または src/app/app-routing.module.ts（NgModule）があるか確認します。
6. ナビゲーションパターン：src/app/ に tabs/ ディレクトリがあるか（タブベース）、またはテンプレートで ion-menu が使われているか（サイドメニュー）を確認します。

Step 2：プロジェクト構成を把握する

標準的な Ionic Angular のディレクトリ構成については、references/project-structure.md を読み取ります。

要点：

• スタンドアロンプロジェクトには、app.config.ts、app.routes.ts、スタンドアロンのページコンポーネントがあります。
• NgModule プロジェクトには、app.module.ts、app-routing.module.ts、ページごとの *.module.ts ファイルがあります。
• Ionic の設定は ionic.config.json にあります。
• テーマ変数は src/theme/variables.scss にあります。
• グローバルスタイルと Ionic CSS のインポートは src/global.scss にあります。

Step 3：アーキテクチャの違いを把握する

詳しい違いについては、references/standalone-vs-ngmodules.md を読み取ります。

概要：

項目	スタンドアロン	NgModule
ブートストラップ	main.ts の bootstrapApplication	platformBrowserDynamic().bootstrapModule
Ionic のセットアップ	app.config.ts の provideIonicAngular({})	app.module.ts の IonicModule.forRoot()
コンポーネントのインポート	ファイルごとに Ionic コンポーネントをインポート	IonicModule がすべてをグローバルに提供
インポート元	@ionic/angular/standalone	@ionic/angular
遅延読み込み	ルート内の loadComponent	ルート内の loadChildren
アイコンの登録	ionicons の addIcons() が必要	自動
ツリーシェイキング	はい	いいえ

ステップ 4：ナビゲーションを設定する

ナビゲーションパターンの詳細は、references/navigation.md をお読みください。

対象トピック：

• ルート設定 — どちらのアーキテクチャでも、遅延読み込みを使用してルートを定義します。
• ルートコンポーネントのレイアウト — <ion-app> と <ion-router-outlet>。
• テンプレートでのナビゲーション — routerLink と routerDirection を使用したトランジションアニメーション。
• プログラムによるナビゲーション — NavController（navigateForward、navigateBack、navigateRoot、back）。
• ルートパラメーター — ActivatedRoute を使ったパラメーターの読み取り。
• タブナビゲーション — <ion-tabs> と、各タブの子ルート。
• サイドメニュー — <ion-menu>、<ion-menu-toggle>、子ルート。
• ルートガード — CanActivateFn を使った関数型ガード（Angular 15.2 以降）。
• モーダル — データの受け渡しに対応したオーバーレイナビゲーション向けの ModalController。
• リニアルーティングとノンリニアルーティング — それぞれのパターンを使う場面。

ステップ 5：ライフサイクルフックを実装する

Ionic のページライフサイクルフックの詳細は、references/lifecycle.md をお読みください。

主なルール：

• ngOnInit は最初の作成時に 1 回だけ 呼び出されます。一度だけ行う初期設定に使用します。
• ionViewWillEnter はページを訪れる たびに 呼び出されます。データの更新に使用します。
• ionViewDidEnter はトランジションアニメーションの後に呼び出されます。アニメーションを妨げる可能性のある負荷の高い処理に使用します。
• ionViewWillLeave はページを離れる前に呼び出されます。クリーンアップやサブスクリプションの一時停止に使用します。
• ngOnDestroy はページがナビゲーションスタックから取り除かれると呼び出されます。最終的なクリーンアップに使用します。
• @ionic/angular の ViewWillEnter、ViewDidEnter、ViewWillLeave、ViewDidLeave インターフェースを実装します。

ステップ 6：フォームを作成する

Ionic コンポーネントを使ったフォームパターンの詳細は、references/forms.md をお読みください。

対象トピック：

• リアクティブフォーム — Ionic の入力コンポーネントと FormBuilder、FormGroup、Validators。
• テンプレート駆動フォーム — FormsModule と [(ngModel)]。
• Ionic のフォームコンポーネント — ion-input、ion-textarea、ion-select、ion-checkbox、ion-toggle、ion-radio-group、ion-range、ion-datetime。
• バリデーションの表示 — errorText（Ionic 7 以降）、または旧バージョン向けの手動による <ion-note>。
• ラベルの配置 — labelPlacement 属性（floating、stacked、fixed）。

ステップ 7：サービスと状態を管理する

サービスと状態管理のパターンの詳細は、references/services-and-state.md をお読みください。

対象トピック：

• インジェクタブルサービス — @Injectable({ providedIn: 'root' })。
• HTTP によるデータ取得 — スタンドアロンと NgModule 向けの HttpClient 設定、CRUD サービスのパターン。
• リアクティブな状態 — 共有する Observable の状態に BehaviorSubject を使用します。
• Angular シグナル — リアクティブな状態に signal() と computed() を使用します（Angular 16 以降）。
• ローディングインジケーター — 非同期処理に LoadingController を使用します。
• エラーのフィードバック — ユーザーに表示するエラー／成功メッセージに ToastController を使用します。
• 環境設定 — API URL に environment.ts／environment.prod.ts を使用します。

ステップ 8：パフォーマンスを最適化する

パフォーマンス最適化の手法については、references/performance.md をお読みください。

対象トピック：

• 遅延読み込み — loadComponent（スタンドアロン）と loadChildren（NgModule）。
• trackBy／track — *ngFor と @for による効率的なリスト描画。
• 仮想スクロール — 大きなリスト向けの Angular CDK cdk-virtual-scroll-viewport。
• OnPush による変更検出 — 不要な再描画を減らします。
• プリロード戦略 — 2 回目以降のナビゲーションを即座に行うための PreloadAllModules。
• スケルトンテキスト — 読み込み中の体感パフォーマンスを高める ion-skeleton-text。

ステップ 9：テストを書く

テストパターンについては、references/testing.md をお読みください。

対象トピック：

• ページの単体テスト — スタンドアロンページと NgModule ページ向けの TestBed 設定。
• サービスのテスト — HttpTestingController を使った基本的なサービスと HTTP サービスのテスト。
• 依存関係のモック — サービスやコントローラーのモックに jasmine.createSpyObj を使用します。
• ナビゲーションのテスト — NavController をモックします。
• ガードのテスト — 関数型ガード向けの TestBed.runInInjectionContext。
• E2E テスト — Cypress と Playwright の設定。

エラー処理

• NullInjectorError: No provider for IonRouterOutlet：スタンドアロンアプリでは、app.config.ts で provideIonicAngular({}) が呼び出されていることを確認してください。NgModule アプリでは、app.module.ts で IonicModule.forRoot() がインポートされていることを確認してください。
• Ionic コンポーネントがレンダリングされない：スタンドアロンコンポーネントでは、各 Ionic コンポーネントが @ionic/angular/standalone からインポートされ、imports 配列に指定されていることを確認してください。NgModule コンポーネントでは、ページモジュールで IonicModule がインポートされていることを確認してください。
• アイコンが表示されない（スタンドアロン）：ionicons/icons の必要なアイコンを指定して addIcons() が呼び出され、IonIcon が @ionic/angular/standalone からインポートされていることを確認してください。
• ionViewWillEnter が呼び出されない：コンポーネントが <ion-router-outlet> 経由で直接ルーティングされていることを確認してください。子コンポーネントは Ionic のライフサイクルイベントを受け取りません。
• 戻る操作でページのデータが更新されない：データ読み込みには ngOnInit ではなく ionViewWillEnter を使用してください。Ionic はページを DOM にキャッシュするため、ngOnInit は一度しか呼び出されません。
• フォームの検証エラーが表示されない：Ionic 7 以降では、<ion-input> の errorText を使用してください。以前のバージョンでは、control.invalid && control.touched を手動で確認し、<ion-note> を表示してください。
• Ionic コンポーネントで routerLink が機能しない：スタンドアロンコンポーネントでは、コンポーネントの imports 配列に @angular/router から RouterLink をインポートしてください。
• ページ遷移がアニメーションしない：アニメーション付きのナビゲーションには、Angular の Router ではなく @ionic/angular の NavController を使用してください。または、routerLink 要素に routerDirection を追加してください。
• タブナビゲーションが機能しない：<ion-tab-button> の tab 属性が子ルートの path と一致していることを確認してください。タブ間をプログラムで移動しないでください。

関連スキル

• capacitor-angular — Capacitor 固有の Angular パターン（プラグインサービス、NgZone、ディープリンク、プラットフォーム検出）。
• ionic-app-development — Ionic 開発全般（コンポーネント、テーマ設定、CLI）。
• ionic-app-creation — Ionic アプリを新規作成します。
• ionic-app-upgrades — Ionic を新しいバージョンにアップグレードします。