ionic-react

Ionic React

React を使用して Ionic Framework アプリを開発します。プロジェクト構成、IonReactRouter、React 固有のコンポーネント、ライフサイクルフック、状態管理、ベストプラクティスについて説明します。

前提条件

1. Ionic Framework 7 または 8 と @ionic/react。
2. React 18 以降。
3. Node.js と npm がインストールされていること。
4. iOS の場合：Xcode がインストールされていること。
5. Android の場合：Android Studio がインストールされていること。

エージェントの動作

• 質問する前に自動検出します。 プロジェクトの package.json にある依存関係（@ionic/react、@ionic/react-router、react、@capacitor/core）、プラットフォーム（android/、ios/）、ビルドツール、TypeScript の使用状況を確認します。検出できない場合にのみユーザーに質問します。
• 手順を一つずつ案内します。 ユーザーを一度に一つの手順ずつ案内します。関連のない複数の質問を一度に提示しないでください。
• プロジェクトに合わせます。 既存のコードスタイル（TypeScript か JavaScript か、状態管理ライブラリ、ルーティング設定）を検出し、それに合ったコードを生成します。

手順

ステップ 1：プロジェクトを分析する

プロジェクトファイルを読み取り、次の項目を自動検出します。

1. Ionic のバージョン：package.json から @ionic/react のバージョンを読み取ります。
2. React のバージョン：package.json から react のバージョンを読み取ります。
3. Capacitor のバージョン：@capacitor/core がある場合は、package.json からそのバージョンを読み取ります。
4. TypeScript：tsconfig.json が存在するか、.tsx ファイルが使用されているかを確認します。
5. ルーター：@ionic/react-router と react-router-dom が package.json に含まれているかを確認します。
6. 状態管理：package.json で redux、@reduxjs/toolkit、zustand、jotai、@tanstack/react-query などを確認します。
7. プラットフォーム：存在するディレクトリ（android/、ios/）を確認します。
8. ビルドツール：vite.config.ts、angular.json、webpack.config.js などがあるかを確認します。

ステップ 2：プロジェクト構成

標準的な Ionic React プロジェクトは、次の構成に従います。

project-root/
├── android/                  # Android native project (Capacitor)
├── ios/                      # iOS native project (Capacitor)
├── public/
├── src/
│   ├── components/           # Reusable UI components
│   ├── hooks/                # Custom React hooks
│   ├── pages/                # Page components (one per route)
│   ├── services/             # Service modules for API and native calls
│   ├── context/              # React context providers
│   ├── theme/
│   │   └── variables.css     # Ionic CSS custom properties
│   ├── App.tsx               # Root component with IonReactRouter
│   └── main.tsx              # Entry point with setupIonicReact()
├── capacitor.config.ts       # Capacitor configuration
├── ionic.config.json         # Ionic CLI configuration
├── package.json
├── tsconfig.json
└── vite.config.ts            # Or other bundler config

プロジェクトがこの構成に従っていない場合は、案内内容を実際のディレクトリ構成に合わせてください。ユーザーから明示的に依頼されない限り、プロジェクトを再構成しないでください。

ステップ 3：アプリの初期化

エントリーポイントでは、アプリをレンダリングする前に setupIonicReact() を呼び出す必要があります。この関数は React 用に Ionic Framework を初期化します。

src/main.tsx（または src/index.tsx）に次の内容があることを確認します。

import { setupIonicReact } from '@ionic/react';

setupIonicReact();

setupIonicReact() は、グローバル設定用のオプションの設定オブジェクトを受け取ります。

setupIonicReact({
  mode: 'ios',          // Force iOS mode on all platforms ('ios' | 'md')
  rippleEffect: false,  // Disable Material Design ripple effect
  animated: true,       // Enable/disable all animations
});

setupIonicReact() がない場合や、レンダリング後に呼び出される場合、Ionic コンポーネントは正しく動作しません。

ステップ 4：ルーティングとナビゲーション

完全なルーティングパターンについては、references/routing.md を読んでください。次の内容が含まれています。

• IonReactRouter の設定
• IonRouterOutlet によるページ管理
• IonTabs を使用したタブベースのナビゲーション
• IonMenu を使用したサイドメニューのナビゲーション
• useIonRouter を使用したプログラムによるナビゲーション
• ルートガードとルートパラメーター

主な原則：

1. React Router の BrowserRouter ではなく、IonReactRouter を使用します。Ionic のページ遷移に必要です。
2. ルートを格納するには IonRouterOutlet を使用します。ページスタックと遷移アニメーションを管理します。
3. Route に component プロパティを渡します。IonRouterOutlet 内では render や children を使用しないでください。
4. プログラムによるナビゲーションには useIonRouter を使用します。遷移アニメーションに対応した、Ionic 向けのナビゲーションを提供します。

ステップ 5：Ionic のライフサイクルフック

ライフサイクルフックの詳しい使い方は、references/lifecycle.md をご覧ください。

Ionic React のページは、画面遷移後も DOM にマウントされたままです。標準の React useEffect は初回のマウント時にのみ実行され、ページを訪れるたびには実行されません。訪問ごとの処理には、Ionic のライフサイクルフックを使用してください。

フック	用途
useIonViewWillEnter	ページが表示される前にデータを更新します
useIonViewDidEnter	ページの表示後にアニメーションを開始したり、入力欄にフォーカスしたりします
useIonViewWillLeave	メディアを一時停止し、下書きの状態を保存します
useIonViewDidLeave	ページが完全に非表示になった後にクリーンアップします

これらのフックは、次の条件を満たすコンポーネントでのみ動作します。

• IonRouterOutlet 内の Route の component としてレンダリングされる。
• ルート要素として IonPage をレンダリングする。

ステップ 6：React 固有の Ionic フック

利用可能なすべてのフックと使用例については、references/hooks.md をご覧ください。

Ionic React には、状態を手動で管理せずにオーバーレイを表示したり、ナビゲーションを制御したりするためのフックが用意されています。

フック	用途
useIonAlert	アラートダイアログを表示します
useIonToast	トースト通知を表示します
useIonActionSheet	アクションシートを表示します
useIonLoading	ローディングインジケーターを表示／非表示にします
useIonModal	モーダルをプログラムから表示します
useIonPopover	ポップオーバーをプログラムから表示します
useIonPicker	ピッカーダイアログを表示します
useIonRouter	Ionic のアニメーションを使って画面遷移します

ステップ 7：React 固有のコンポーネントパターン

IonPage を使ったページ構造、isOpen バインディングによるインラインオーバーレイ（モーダル、ポップオーバー）、IonRefresher によるプルツーリフレッシュ、IonInfiniteScroll による無限スクロール、Ionic の入力コンポーネントを使ったフォームなど、コンポーネントパターンの詳細については references/components.md をご覧ください。

主な原則：

1. すべてのページはルート要素として IonPage をレンダリングする必要があります。 画面遷移とライフサイクルフックに必要です。
2. テキスト入力には onIonInput を、セレクト、トグル、チェックボックス、レンジの各コンポーネントには onIonChange を使用します。
3. 値には e.detail.value（トグル／チェックボックスの場合は e.detail.checked）からアクセスします。
4. 状態管理を簡素化するには isOpen を使ったインラインオーバーレイを使用するか、命令的に使う場合はオーバーレイフック（useIonModal、useIonAlert など）を使用します。

ステップ 8：状態管理

React Context、Redux Toolkit、Zustand、TanStack Query を使ったパターンについては、references/state-management.md をご覧ください。

主な原則：

1. ページのキャッシュは状態に影響します。 Ionic はページをマウントしたままにするため、画面遷移後も状態が保持されます。古くなったデータを更新するには useIonViewWillEnter を使用してください。
2. プロバイダーは IonReactRouter の外側に配置します。 すべてのページから利用できるように、Context プロバイダー、Redux の Provider、QueryClientProvider でルーターを囲んでください。
3. 必要がない限り、状態管理ライブラリを追加しないでください。 シンプルなアプリでは、React Context と useState／useReducer で十分です。

ステップ 9：ビルドと実行

変更を実装した後：

npm run build
npx cap sync
npx cap run android
npx cap run ios

ライブリロードを使った開発の場合：

ionic serve

ライブリロードを使ったネイティブ開発の場合：

ionic cap run android --livereload --external
ionic cap run ios --livereload --external

エラー処理

• Ionic のライフサイクルフックが呼び出されない：コンポーネントのルート要素として IonPage をレンダリングし、IonRouterOutlet 内の Route の component として指定していることを確認してください。ライフサイクルフックは、子コンポーネントや render／children プロパティ経由でレンダリングされたコンポーネントでは呼び出されません。
• ページ遷移がアニメーションしない：BrowserRouter ではなく IonReactRouter を使用していることを確認してください。ルートでは render や children ではなく、component プロパティを使用してください。IonRouterOutlet が IonReactRouter または IonTabs の直接の子であることを確認してください。
• 戻る操作後にデータが古いままになる：Ionic ではページが DOM にマウントされたままになります。[] を指定した useEffect ではなく、useIonViewWillEnter を使用して、ページを訪れるたびにデータを更新してください。
• サブページでタブバーが表示されなくなる：詳細ルートを含むすべてのルートを、IonTabs 内の IonRouterOutlet に配置する必要があります。タブページ内に別の IonRouterOutlet をネストしないでください。
• setupIonicReact のエラーが発生する、またはコンポーネントがレンダリングされない：エントリーファイルで ReactDOM.createRoot() または ReactDOM.render() を呼び出す前に、setupIonicReact() が呼び出されていることを確認してください。すべての Ionic CSS ファイルがインポートされていることを確認してください（src/App.tsx または src/main.tsx の Ionic CSS のインポートを参照）。
• IonBackButton が表示されない：IonBackButton はナビゲーション履歴がある場合にのみレンダリングされます。ページに直接アクセスした場合のフォールバックルートとして、defaultHref プロパティを設定してください。
• フォーム入力の値が更新されない：IonInput／IonTextarea では onChange ではなく onIonInput を使用してください。IonSelect、IonToggle、IonCheckbox、IonRange では onIonChange を使用してください。値は e.detail.value で取得します。
• モーダルやポップオーバーのコンテンツにスタイルが適用されない：オーバーレイのコンテンツが IonContent で囲まれていることを確認してください。モーダルでツールバーが必要な場合は、IonToolbar を含む IonHeader を追加してください。
• React のストリクトモードで二重マウントされる：開発時、React 18 のストリクトモードではコンポーネントが 2 回マウントされます。その結果、Ionic のイベントリスナーが重複することがあります。クリーンアップ関数でリスナーが適切に削除されることを確認してください。
• useIonRouter が undefined を返す：このフックは、IonReactRouter の子孫であるコンポーネント内で使用する必要があります。コンポーネントツリーに IonReactRouter が祖先として含まれていることを確認してください。
• CSS カスタムプロパティが適用されない：src/App.tsx または src/main.tsx で、Ionic CSS ファイルが正しい順序でインポートされていることを確認してください。テーマの variables.css ファイルは、Ionic のコア CSS の後にインポートする必要があります。

関連スキル

• ionic-app-development — コンポーネント、テーマ設定、CLI の使い方を含む Ionic 開発全般。
• ionic-app-creation — Ionic アプリをゼロから作成します。
• capacitor-react — Ionic Framework を使わずにネイティブデバイスの機能へアクセスする、Capacitor 固有の React パターン。
• ionic-app-upgrades — Ionic Framework を新しいバージョンにアップグレードします。
• capacitor-plugins — 公式およびコミュニティのソースから Capacitor プラグインをインストール、設定、使用します。