ionic-expert

Ionic Expert

Ionic Framework 開発の包括的なリファレンスです。コアコンセプト、コンポーネント、テーマ設定、ライフサイクル、ナビゲーション、フレームワーク固有のパターン（Angular、React、Vue）、アップグレード、Capawesome Cloud との統合を扱います。

MCP サーバー

現在のドキュメントを提供するホスト型 MCP サーバーが 2 つあり、どちらもこのスキルに含まれるガイダンスより常に最新です。

• Capawesome MCP サーバー — Capawesome プラグイン、Capawesome CLI、Capawesome Cloud。
• Ionic Framework MCP サーバー（非公式）— Ionic Framework の UI コンポーネント、その API リファレンス、各フレームワークに対応する公式の使用例。

どちらも search_docs と get_doc_page を提供しているため、どちらかを呼び出す前に、トピックに応じてサーバーを選んでください。

• MCP ツールを利用できる場合は、トピックを担当するサーバーで search_docs を呼び出し、該当するページを get_doc_page で読んでから、以下のガイダンスを適用してください。両者の内容が異なる場合は、ドキュメントに従ってください。
• 利用できない場合は、以下のコマンドでサーバーを追加できることを一度だけ伝えたうえで、このスキルに従って続行してください。サーバーの利用を必須条件にしないでください。

claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
claude mcp add --transport http ionic-framework "https://ionic-framework-mcp.capawesome.io/mcp"

ドキュメントの参照にアカウントやトークンは必要ありません。Capawesome Cloud ツールを含む完全なセットアップ方法については、capawesome-mcp と ionic-framework-mcp の各スキルを参照してください。

コアコンセプト

Ionic Framework は、ウェブテクノロジーを使ってクロスプラットフォームアプリを構築するための UI ツールキットです。ion- をプレフィックスとする Web Components として、80 種類以上の組み込み UI コンポーネントを提供します（例：<ion-button>、<ion-content>）。

• プラットフォームモード：コンポーネントのスタイルはプラットフォームに合わせて調整されます。iOS デバイスでは ios モードが使われ、Android とその他すべてのプラットフォームでは md（Material Design）が使われます。<html> 要素にはクラス（ios または md）が設定されます。
• Capacitor との統合：Ionic は UI を、Capacitor はネイティブデバイス API を担当します。Capacitor に関するガイダンスは、capacitor-app-development スキルを参照してください。
• フレームワークのサポート：Ionic は Angular（@ionic/angular）、React（@ionic/react）、Vue（@ionic/vue）と統合できます。

新しいアプリの作成

npm install -g @ionic/cli
ionic start <name> <template> --type=<framework> --capacitor --package-id=<id>

--type の値	フレームワーク
angular	Angular（NgModules）
angular-standalone	Angular（スタンドアロンコンポーネント）
react	React
vue	Vue

テンプレート	説明
blank	空のプロジェクト、単一ページ
tabs	タブベースのレイアウト
sidemenu	サイドメニューレイアウト

詳細については、ionic-app-creation を参照してください。

Ionic CLI

コマンド一覧を確認するには、最新の情報が表示される ionic --help を実行してください。

コマンド	説明
ionic start	新しい Ionic プロジェクトのひな型を作成します。
ionic serve	ライブリロード対応のローカル開発サーバーを起動します（ポート 8100）。
ionic build	ウェブアプリを本番用にビルドします。
ionic generate	ページ、コンポーネント、サービスを生成します（フレームワークによって異なります）。
ionic info	システムと環境の情報を表示します。
ionic repair	依存関係とプラットフォームファイルを削除して再作成します。

ionic serve で便利なフラグ：--external（すべてのネットワークインターフェース）、--port=<port>、--prod、--no-open。

コンポーネントの概要

Ionic はカテゴリ別に整理された 80 種類以上の UI コンポーネントを提供します。完全な API リファレンス（プロパティ、イベント、メソッド、スロット、CSS カスタムプロパティ）については、リンク先のリファレンスファイルを参照してください。

レイアウト

ion-app（ルートコンテナ）、ion-content（スクロール可能な領域）、ion-header、ion-footer、ion-toolbar、ion-title、ion-buttons、ion-back-button、ion-grid/ion-row/ion-col、ion-split-pane。

主な使い方：

<ion-header>
  <ion-toolbar>
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/home"></ion-back-button>
    </ion-buttons>
    <ion-title>Page Title</ion-title>
  </ion-toolbar>
</ion-header>
<ion-content>
  
</ion-content>

詳細については、components-layout.mdを参照してください。

ナビゲーション

ion-tabs、ion-tab-bar、ion-tab-button、ion-menu、ion-menu-button、ion-menu-toggle、ion-router-outlet、ion-nav、ion-breadcrumbs。

詳細については、components-navigation.mdを参照してください。

フォーム

ion-input、ion-textarea、ion-select/ion-select-option、ion-checkbox、ion-toggle、ion-radio/ion-radio-group、ion-range、ion-datetime/ion-datetime-button、ion-searchbar、ion-segment/ion-segment-button、ion-input-otp。

ほとんどのフォームコンポーネントで共通する主なプロパティ：label、labelPlacement（floating、stacked、fixed、start）、fill（outline、solid）、errorText、helperText、disabled、value、placeholder。

主なイベント：

• ionInput — キーストロークごとに発火します（ion-input/ion-textareaで使用します）。
• ionChange — 値が確定したときに発火します（ion-select、ion-toggle、ion-checkbox、ion-rangeで使用します）。

<ion-input label="Email" labelPlacement="floating" fill="outline"
           type="email" placeholder="[email protected]"
           errorText="Invalid email" helperText="Enter your email">
</ion-input>

<ion-select label="Country" labelPlacement="floating" fill="outline" interface="popover">
  <ion-select-option value="us">United States</ion-select-option>
  <ion-select-option value="de">Germany</ion-select-option>
</ion-select>

詳細については、components-form.mdを参照してください。

オーバーレイ

ion-modal、ion-alert、ion-toast、ion-action-sheet、ion-loading、ion-popover。

すべてのオーバーレイで共通する機能：宣言的な制御に使うisOpenプロパティ、ボタンIDから開くためのtriggerプロパティ、backdropDismiss、animated、ライフサイクルイベント（didPresent、didDismiss、willPresent、willDismiss）。

シートモーダル（ボトムシート）：

<ion-modal [isOpen]="isOpen" [breakpoints]="[0, 0.5, 1]" [initialBreakpoint]="0.5" [handle]="true">
  <ion-content>Sheet content</ion-content>
</ion-modal>

詳細については、components-overlay.mdを参照してください。

データ表示

ion-list、ion-item、ion-item-sliding/ion-item-options/ion-item-option、ion-card/ion-card-header/ion-card-content、ion-accordion/ion-accordion-group、ion-chip、ion-badge、ion-label、ion-note。

詳細については、components-data-display.mdを参照してください。

スクロール

ion-refresher/ion-refresher-content（プルして更新）、ion-infinite-scroll/ion-infinite-scroll-content、ion-reorder-group/ion-reorder。

詳細については、components-scroll.mdを参照してください。

アクションとメディア

ion-button、ion-fab/ion-fab-button、ion-icon、ion-avatar、ion-thumbnail、ion-spinner、ion-skeleton-text、ion-progress-bar。

詳細については、components-action.mdおよびcomponents-media.mdを参照してください。

テーマ設定

色

デフォルトの色は9種類です：primary、secondary、tertiary、success、warning、danger、light、medium、dark。color属性を使って適用します：

<ion-button color="primary">Save</ion-button>
<ion-button color="danger">Delete</ion-button>

:root内の6つのCSS変数をすべて上書きして、色をカスタマイズします：

:root {
  --ion-color-primary: #3880ff;
  --ion-color-primary-rgb: 56, 128, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #3171e0;
  --ion-color-primary-tint: #4c8dff;
}

グローバルCSS変数

主な変数：--ion-background-color、--ion-text-color、--ion-font-family、--ion-safe-area-top/right/bottom/left、--ion-margin、--ion-padding。

ダークモード

3 つの方法があります（@ionic/angular/css/、@ionic/react/css/、または @ionic/vue/css/ からインポートします）。

1. システム設定に合わせる（デフォルト）：@import '@ionic/<framework>/css/palettes/dark.system.css';
2. 常にダークモードにする：@import '@ionic/<framework>/css/palettes/dark.always.css';
3. CSS クラスで切り替える：@import '@ionic/<framework>/css/palettes/dark.class.css'; を指定してから、<html> に .ion-palette-dark を追加します。

プラットフォームスタイル

<html> のモードクラスを使って、CSS でプラットフォーム固有のスタイルを指定します。

.ios ion-toolbar { --background: #f8f8f8; }
.md ion-toolbar { --background: #ffffff; }

ブラウザーで特定のモードをプレビューするには、http://localhost:8100/?ionic:mode=ios を開きます。

レイアウト

グリッドシステム

12 列のフレックスボックスグリッドです。ion-grid、ion-row、ion-col を使用します。size（1〜12）を指定しない場合、列は均等に広がります。

ブレークポイント	最小幅	プロパティの接尾辞
xs	0	Xs
sm	576px	Sm
md	768px	Md
lg	992px	Lg
xl	1200px	Xl

CSS ユーティリティクラス

• パディング：.ion-padding、.ion-padding-top/bottom/start/end、.ion-no-padding
• マージン：.ion-margin、.ion-margin-top/bottom/start/end、.ion-no-margin
• テキスト：.ion-text-center、.ion-text-start、.ion-text-end、.ion-text-wrap、.ion-text-nowrap
• 表示：.ion-display-none、.ion-display-block、.ion-display-flex
• フレックス：.ion-justify-content-center、.ion-align-items-center、.ion-flex-row、.ion-flex-column

すべてのユーティリティクラスはレスポンシブな接尾辞に対応しています。例：.ion-text-md-center（768px 以上で適用）。

ページのライフサイクル

Ionic には、ページ遷移中に実行される 4 つのライフサイクルフックがあります。これらが用意されているのは、ion-router-outlet がページを DOM 内にキャッシュするためです。フレームワーク標準のライフサイクルフック（ngOnInit、useEffect、onMounted）は初回作成時にのみ実行され、ページを訪問するたびには実行されません。

フック	実行タイミング	用途
ionViewWillEnter	ページに入る直前（アニメーション前）	訪問のたびにデータを更新する
ionViewDidEnter	ページに入った直後（アニメーション後）	アニメーションを開始し、入力欄にフォーカスする
ionViewWillLeave	ページを離れる直前（アニメーション前）	状態を保存し、サブスクリプションを一時停止する
ionViewDidLeave	ページを離れた直後（アニメーション後）	画面外のリソースをクリーンアップする

重要なルール：

• ion-router-outlet を介してルートに直接マッピングされたコンポーネントでのみ実行されます。
• 子コンポーネントにはこれらのイベントは通知されません。
• コンポーネントでは、フレームワーク固有のページラッパーを使用する必要があります（以下のフレームワークごとのセクションを参照）。

フレームワーク固有のパターン

Angular

詳細については、ionic-angular を参照してください。

アーキテクチャの判別：src/main.ts を確認し、bootstrapApplication（スタンドアロン）か platformBrowserDynamic().bootstrapModule（NgModule）かを判別します。

項目	スタンドアロン	NgModule
Ionic の設定	app.config.ts の provideIonicAngular({})	app.module.ts の IonicModule.forRoot()
コンポーネントのインポート	@ionic/angular/standalone から個別にインポート	IonicModule がすべてをグローバルに提供
遅延読み込み	ルートの loadComponent	ルートの loadChildren
アイコン	ionicons の addIcons() が必要	自動

ナビゲーション：アニメーション付きのナビゲーションには、@ionic/angular の NavController（navigateForward、navigateBack、navigateRoot、back）を使用します。テンプレートでは routerDirection とともに routerLink を使用します。

ライフサイクル：@ionic/angular のインターフェース ViewWillEnter、ViewDidEnter、ViewWillLeave、ViewDidLeave を実装します。

import { ViewWillEnter } from '@ionic/angular';

@Component({ /* ... */ })
export class HomePage implements ViewWillEnter {
  ionViewWillEnter() {
    this.loadData(); // Runs on every page visit
  }
}

ナビゲーションの詳細については、angular/navigation.md を参照してください。ライフサイクルの詳細については、angular/lifecycle.md を参照してください。

React

詳細については、ionic-react を参照してください。

主な設定の違い：

• src/main.tsx で、レンダリングの前に setupIonicReact() を呼び出します。
• BrowserRouter の代わりに IonReactRouter（@ionic/react-router から）を使用します。
• component プロパティ（render や children ではありません）を指定したルートを含めるには、IonRouterOutlet を使用します。
• すべてのページで、ルート要素として IonPage をレンダリングする必要があります — トランジションとライフサイクルフックに必須です。

ナビゲーション：プログラムによるナビゲーションには useIonRouter フックを使用します。

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

const router = useIonRouter();
router.push('/detail/123', 'forward', 'push');
router.goBack();

ライフサイクルフック（@ionic/react から）：

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

useIonViewWillEnter(() => {
  fetchData(); // Runs on every page visit
});

オーバーレイフック：useIonAlert、useIonToast、useIonActionSheet、useIonLoading、useIonModal、useIonPopover、useIonPicker。

フォームイベント：IonInput／IonTextarea には onIonInput を、IonSelect／IonToggle／IonCheckbox／IonRange には onIonChange を使用します。値は e.detail.value から取得します。

ルーティングの詳細については、react/routing.md を参照してください。フックについては、react/hooks.md を参照してください。

Vue

詳しくは、ionic-vueをご覧ください。

主なセットアップの違い：

• src/main.tsでIonicVueプラグインをインストールします：createApp(App).use(IonicVue).use(router)。
• createRouterはvue-routerではなく、@ionic/vue-routerからインポートします。
• すべてのページで、ルートのテンプレート要素としてIonPageを使用する必要があります。使用しないと、トランジションとライフサイクルフックが警告なしに失敗します。
• すべてのIonicコンポーネントを@ionic/vueからインポートします。
• テンプレート内のイベント名にはケバブケースを使用します（@ion-change、@ion-input）。
• アイコンはionicons/iconsからSVG参照としてインポートします。文字列としては使用しないでください。

ナビゲーション：useIonRouterコンポーザブルを使用します。

<script setup lang="ts">
import { useIonRouter } from '@ionic/vue';

const ionRouter = useIonRouter();
ionRouter.push('/detail/123');
ionRouter.back();
</script>

宣言的な方法：<ion-button router-link="/detail" router-direction="forward">Go</ion-button>

ライフサイクルフック（@ionic/vueから）：

<script setup lang="ts">
import { onIonViewWillEnter } from '@ionic/vue';

onIonViewWillEnter(() => {
  fetchData(); // Runs on every page visit
});
</script>

コンポーザブル：useIonRouter()、useBackButton(priority, handler)、useKeyboard()、isPlatform(name)、getPlatforms()。

$elを介してWebコンポーネントのメソッドにアクセス：contentRef.value.$el.scrollToBottom(300)。

ナビゲーションの詳細は、vue/navigation.mdをご覧ください。コンポーザブルについては、vue/composables.mdをご覧ください。

ナビゲーションパターン

タブナビゲーション

各フレームワークでは、ion-tabsとion-tab-barを使用し、タブごとに子ルートを設定します。各タブは独自のナビゲーションスタックを維持します。

ルール：

• ion-tab-buttonのtab属性は、子ルートのパスと一致する必要があります。
• タブ間をプログラムから遷移しないでください。タブを切り替えるのはタブバーのボタンのみです。
• 複数のタブで共有するビューには、タブ間のルーティングではなくion-modalを使用します。

サイドメニュー

ion-router-outletのidと一致するcontentIdを指定してion-menuを使用します。メニュー項目をion-menu-toggleで囲むと、選択後に自動で閉じます。最上位のメニューへのナビゲーションにはrouterDirection="root"を使用します。

線形ルーティングと非線形ルーティング

• 線形：順次進む／戻るナビゲーション（リスト -> 詳細 -> 編集）。戻るボタンで前のページに戻ります。
• 非線形：複数の独立したスタック（タブ）。戻る操作は現在のタブのスタック内にとどまります。

タブや分割ペインのレイアウトには非線形ルーティングを使用します。シンプルなページ遷移には線形ルーティングを使用します。

アップグレード

Ionicでは、バージョン4から8へのアップグレードがサポートされています。メジャーバージョンのアップグレードは順番に適用する必要があります。中間のバージョンを飛ばさないでください。

アップグレードガイドの詳細は、ionic-app-upgradesをご覧ください。

Capacitorとの統合

Ionicアプリでは、ネイティブデバイス機能（カメラ、ファイルシステム、プッシュ通知など）にCapacitorを使用します。標準的なワークフローは次のとおりです。

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

デバイスでライブリロードするには、次のようにします。

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

Capacitorのガイダンスについては、capacitor-app-developmentスキルをご覧ください。

Capawesome Cloud

Capawesome Cloudは、Ionic／Capacitorアプリ向けにCI/CDサービスを提供します。

• ライブアップデート — アプリストアの審査なしで、Ionic／CapacitorアプリにOTAアップデートをすぐにデプロイできます。
• ネイティブビルド — ローカルのXcodeやAndroid Studioを使わずに、クラウドでiOSおよびAndroidのバイナリをビルドできます。
• アプリストアへの公開 — Apple App StoreおよびGoogle Play Storeへの申請を自動化できます。

Capawesomeのエコシステム全体については、capawesome.ioをご覧ください。セットアップについては、capawesome-cloudスキルをご覧ください。

よくあるトラブルシューティング

• ionic: command not found：npm install -g @ionic/cli を実行します。
• コンポーネントがレンダリングされない：グローバルスタイルシートに Ionic の CSS ファイルがインポートされていることを確認します。スタンドアロンの Angular では、各コンポーネントが @ionic/angular/standalone からインポートされていることを確認します。
• ionViewWillEnter が発火しない：コンポーネントは ion-router-outlet 経由で直接ルーティングされている必要があります。子コンポーネントはライフサイクルイベントを受け取りません。React/Vue の場合は、IonPage がルート要素であることを確認します。
• 戻るナビゲーションでページのデータが更新されない：フレームワーク標準のライフサイクルフック（ngOnInit、useEffect、onMounted）ではなく、Ionic のライフサイクルフック（ionViewWillEnter）を使用します。Ionic はページを DOM にキャッシュします。
• ページ遷移がアニメーションされない：フレームワーク向けの Ionic ルーター統合（Angular では NavController、React では IonReactRouter、Vue では @ionic/vue-router の createRouter）を使用します。フレームワーク標準のルーターでは Ionic のアニメーションが実行されません。
• CSS カスタムプロパティが適用されない：Ionic コンポーネントは Shadow DOM を使用します。内部要素を直接指定するのではなく、ドキュメントに記載されている CSS カスタムプロパティ（--background、--color）を使用します。
• アイコンが表示されない（Angular スタンドアロン）：必要なアイコンを指定して ionicons の addIcons() を呼び出し、@ionic/angular/standalone から IonIcon をインポートします。
• Failed to resolve component: ion-*（Vue）：Ionic コンポーネントがインポートされていません。@ionic/vue からインポートを追加します。
• サブページでタブバーが消える（React）：すべてのルート（詳細ルートを含む）を IonTabs 内の IonRouterOutlet に含める必要があります。
• フォームの入力値が更新されない（React）：IonInput／IonTextarea では onChange ではなく onIonInput を使用します。値には e.detail.value でアクセスします。
• slot 属性の非推奨警告（Vue）：Ionic は Web Component のスロットを使用します。ESLint ルール 'vue/no-deprecated-slot-attribute': 'off' を無効にします。

関連するスキル

• ionic-app-creation — Ionic アプリをゼロから新規作成します。
• ionic-app-development — Ionic 開発全般と、コンポーネント API の完全なリファレンスです。
• ionic-angular — Angular 固有のパターン（スタンドアロンと NgModule、ナビゲーション、フォーム、テスト）です。
• ionic-react — React 固有のパターン（IonReactRouter、フック、状態管理）です。
• ionic-vue — Vue 固有のパターン（コンポーザブル、ナビゲーション、IonPage の要件）です。
• ionic-app-upgrades — Ionic を新しいメジャーバージョンにアップグレードします。
• capacitor-app-development — Capacitor 開発全般です。
• capawesome-cloud — ライブアップデート、ネイティブビルド、アプリストアへの公開です。
• capawesome-mcp — MCP クライアントをホスト型の Capawesome MCP サーバーに接続して、常に最新のドキュメントを参照し、Capawesome Cloud を管理します。
• ionic-framework-mcp — MCP クライアントをホスト型の Ionic Framework MCP サーバーに接続して、最新のコンポーネント API リファレンスと使用例を参照します。