ionic-app-development

Ionic アプリ開発

Ionic Framework による一般的な開発について説明します。基本概念、コンポーネントリファレンス、CLI の使用方法、レイアウト、テーマ設定、ユーティリティ、開発ワークフロー、トラブルシューティングを扱います。

前提条件

1. Node.js（最新の LTS 版）がインストールされていること。
2. Ionic CLI がグローバルにインストールされていること（npm install -g @ionic/cli）。
3. 既存の Ionic プロジェクトがあること。新しい Ionic アプリを作成するには、ionic-app-creation スキルを使用してください。

エージェントの動作

• フレームワークを自動検出します。 package.json で @ionic/angular、@ionic/react、@ionic/vue を確認し、使用中のフレームワークを特定します。それに応じてコード例を調整します。
• 詳細はリファレンスファイルを参照します。 このスキルは概要を説明し、詳細なコンポーネント API やトピック別のガイダンスについて、エージェントを個別のリファレンスファイルに案内します。
• フレームワーク固有のスキルを重複させません。 Angular、React、Vue 固有のパターンについては、それぞれのフレームワークスキルを参照してください。

基本概念

Ionic の仕組み

Ionic Framework は、ウェブ技術（HTML、CSS、JavaScript/TypeScript）を使ってクロスプラットフォームアプリを構築するための UI ツールキットです。プラットフォーム（ios または md モード）に応じてスタイルが調整される、事前構築済みの UI コンポーネントライブラリを提供します。

• コンポーネントは、ion- が接頭辞として付いたカスタム HTML 要素（Web Components）です（例：<ion-button>、<ion-content>）。
• プラットフォームモード：Ionic はプラットフォームに応じてコンポーネントを異なる方法でレンダリングします。iOS デバイスでは ios モードが使われ、Android およびその他すべてのプラットフォームでは md（Material Design）モードが使われます。<html> 要素には、プラットフォーム固有のスタイルを有効にするクラス（ios または md）が設定されます。
• Capacitor との統合：Ionic アプリでは Capacitor を使って、ネイティブデバイスの機能にアクセスします。Ionic が UI を担当し、Capacitor がネイティブ API を担当します。Capacitor 固有のガイダンスについては、capacitor-app-development スキルを参照してください。

ページのライフサイクル

Ionic は、フレームワーク独自のライフサイクルフックに加えて、ページが遷移先または遷移元となるときに発生するライフサイクルイベントを提供します。

イベント	説明
ionViewWillEnter	ページが表示され、アクティブになる直前に発生します。
ionViewDidEnter	ページの表示が完了し、アクティブになったときに発生します。
ionViewWillLeave	ページが非表示になり、非アクティブになる直前に発生します。
ionViewDidLeave	ページが非表示になり、非アクティブになったときに発生します。

これらは、フレームワーク固有のライフサイクルフック（例：Angular の ngOnInit、React の useEffect、Vue の onMounted）に加えて使用できます。一部のナビゲーション方式ではページがキャッシュされるため、ページが表示されるたびに実行する処理（データの更新など）には Ionic のライフサイクルイベントを使用してください。

コンポーネントリファレンス

Ionic は 80 種類以上の UI コンポーネントを提供しています。各コンポーネントの詳細な API ドキュメントは、カテゴリ別のリファレンスファイルにまとめられています。各リファレンスファイルでは、プロパティ、イベント、メソッド、スロット、CSS シャドウパーツ、CSS カスタムプロパティを扱います。

特定のコンポーネントについてユーザーからサポートを求められた場合は、該当するリファレンスファイルを参照してください。

カテゴリ	リファレンスファイル	対象コンポーネント
アクションとボタン	references/components-action.md	action-sheet, button, fab, fab-button, fab-list, ripple-effect
データ表示	references/components-data-display.md	accordion, accordion-group, badge, card, card-content, card-header, card-subtitle, card-title, chip, item, item-divider, item-group, item-sliding, item-options, item-option, label, list, list-header, note, text
フォーム	references/components-form.md	checkbox, datetime, datetime-button, input, input-otp, input-password-toggle, picker, radio, radio-group, range, searchbar, select, select-option, segment, segment-button, segment-content, segment-view, textarea, toggle
レイアウト	references/components-layout.md	app, content, grid, col, row, header, footer, toolbar, title, buttons, back-button, split-pane
メディア	references/components-media.md	avatar, icon, img, thumbnail
ナビゲーション	references/components-navigation.md	breadcrumb, breadcrumbs, menu, menu-button, menu-toggle, nav, nav-link, router, router-link, router-outlet, route, route-redirect, tabs, tab, tab-bar, tab-button
オーバーレイ	references/components-overlay.md	alert, loading, modal, popover, toast, backdrop
スクロールと仮想化	references/components-scroll.md	infinite-scroll, infinite-scroll-content, refresher, refresher-content, reorder, reorder-group
進捗	references/components-progress.md	progress-bar, skeleton-text, spinner

Ionic CLI

Ionic CLI は Ionic アプリを開発するための主要なツールです。以下に、最もよく使われるコマンドを示します。すべての最新コマンド一覧については、ionic --help を実行してください。

インストール

npm install -g @ionic/cli

従来の ionic パッケージからアップグレードする場合：

npm uninstall -g ionic
npm install -g @ionic/cli

主なコマンド

コマンド	説明
ionic serve	ライブリロード対応のローカル開発サーバーを起動します。
ionic serve --external	すべてのネットワークインターフェイスで配信します（デバイスでのテスト用）。
ionic serve --port=<port>	任意のポートで配信します（デフォルト：8100）。
ionic serve --prod	本番ビルド設定で配信します。
ionic build	Web アプリを本番用にビルドします。
ionic generate	ページ、コンポーネント、サービスを生成します（フレームワークに依存）。
ionic doctor check	プロジェクトに一般的な問題がないか確認します。
ionic info	バグ報告用にシステム／環境情報を出力します。
ionic repair	依存関係とプラットフォームファイルを削除して再作成します。

ionic serve のオプション

オプション	説明
--ssl	HTTPS を有効にします（実験的機能）。
--no-livereload	自動リロードせずに配信します。
--no-open	ブラウザーウィンドウを自動的に開かないようにします。
--consolelogs	アプリのコンソール出力をターミナルに表示します。
--browser=<browser>	指定したブラウザー（safari、firefox、google chrome）で開きます。
--browseroption=<path>	特定の URL パス（例：/#/tab/dash）を開きます。

フレームワーク固有の CLI オプションを渡すには、-- の後に指定します。

ionic serve -- --proxy-config proxy.conf.json

レイアウト

レイアウトコンポーネントの API リファレンス全体については、references/components-layout.md を参照してください。

グリッドシステム

Ionic は 12 列のフレックスボックスグリッドシステム（ion-grid、ion-row、ion-col）を使用します。size 属性が指定されていない場合、列は行全体を均等に埋めるように広がります（1～12）。

レスポンシブブレークポイント：

ブレークポイント	最小幅	CSS クラスのプレフィックス
xs	0	（デフォルト）
sm	576px	sizeSm
md	768px	sizeMd
lg	992px	sizeLg
xl	1200px	sizeXl

CSS ユーティリティクラス

Ionic は、一般的なスタイル設定に対応するレスポンシブ CSS ユーティリティクラスを提供します。

• テキスト：.ion-text-center、.ion-text-start、.ion-text-end、.ion-text-wrap、.ion-text-nowrap、.ion-text-uppercase、.ion-text-lowercase、.ion-text-capitalize
• パディング：.ion-padding、.ion-padding-top、.ion-padding-bottom、.ion-padding-start、.ion-padding-end、.ion-padding-vertical、.ion-padding-horizontal、.ion-no-padding
• マージン：.ion-margin、.ion-margin-top、.ion-margin-bottom、.ion-margin-start、.ion-margin-end、.ion-margin-vertical、.ion-margin-horizontal、.ion-no-margin
• 表示：.ion-display-none、.ion-display-block、.ion-display-flex、.ion-display-inline、.ion-display-grid
• フロート：.ion-float-left、.ion-float-right、.ion-float-start、.ion-float-end
• フレックス：.ion-justify-content-center、.ion-align-items-center、.ion-flex-row、.ion-flex-column、.ion-flex-wrap、.ion-flex-nowrap
• ボーダー：.ion-no-border

すべてのユーティリティクラスは、レスポンシブブレークポイントのサフィックスに対応しています。ion-text-{breakpoint}-center（例：.ion-text-md-center は 768px 以上で適用されます）。

テーマ設定

色

Ionic は、デフォルトで 9 色を提供します：primary、secondary、tertiary、success、warning、danger、light、medium、dark。コンポーネントの color 属性で適用します。

<ion-button color="primary">Primary</ion-button>
<ion-button color="danger">Danger</ion-button>

各色には、6 つの CSS カスタムプロパティがあります。

• --ion-color-{name} — ベースカラーの値
• --ion-color-{name}-rgb — RGB 形式のベースカラー
• --ion-color-{name}-contrast — 読みやすさを確保するテキストカラー
• --ion-color-{name}-contrast-rgb — RGB 形式のコントラストカラー
• --ion-color-{name}-shade — 暗いバリエーション（アクティブ／押下状態）
• --ion-color-{name}-tint — 明るいバリエーション（ホバー状態）

色をカスタマイズするには、:root ですべての 6 つの変数を上書きします。

: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 変数を定義してクラスを作成します。

:root {
  --ion-color-favorite: #69bb7b;
  --ion-color-favorite-rgb: 105, 187, 123;
  --ion-color-favorite-contrast: #ffffff;
  --ion-color-favorite-contrast-rgb: 255, 255, 255;
  --ion-color-favorite-shade: #5ca56c;
  --ion-color-favorite-tint: #78c288;
}

.ion-color-favorite {
  --ion-color-base: var(--ion-color-favorite);
  --ion-color-base-rgb: var(--ion-color-favorite-rgb);
  --ion-color-contrast: var(--ion-color-favorite-contrast);
  --ion-color-contrast-rgb: var(--ion-color-favorite-contrast-rgb);
  --ion-color-shade: var(--ion-color-favorite-shade);
  --ion-color-tint: var(--ion-color-favorite-tint);
}

グローバル CSS 変数

変数	説明
--ion-background-color	アプリの背景色
--ion-text-color	アプリのテキスト色
--ion-font-family	アプリのフォントファミリー
--ion-statusbar-padding	アプリ上部のステータスバーのパディング
--ion-safe-area-top	セーフエリアの上部インセットを調整
--ion-safe-area-right	セーフエリアの右側インセットを調整
--ion-safe-area-bottom	セーフエリアの下部インセットを調整
--ion-safe-area-left	セーフエリアの左側インセットを調整
--ion-margin	マージンユーティリティクラスのデフォルトマージン
--ion-padding	パディングユーティリティクラスのデフォルトパディング
--ion-placeholder-opacity	入力欄のプレースホルダーテキストの不透明度

ダークモード

Ionic は、ダークモードに対応する 3 つの方法をサポートしています。

1. システム設定（デフォルト）

ユーザーの OS 設定に基づいて、ダークパレットを自動的に適用します。

@import '@ionic/angular/css/palettes/dark.system.css';
/* or @ionic/react, @ionic/vue */

2. 常にダーク

システム設定に関係なく、ダークモードを強制します。

@import '@ionic/angular/css/palettes/dark.always.css';

3. CSS クラスの切り替え

CSS クラスを使って、ダークモードを手動で制御できます。

@import '@ionic/angular/css/palettes/dark.class.css';

<html> 要素に .ion-palette-dark を追加すると有効になります。

<html class="ion-palette-dark">

システム UI 要素（スクロールバーなど）を調整するには、このメタタグを追加します。

<meta name="color-scheme" content="light dark" />

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

Ionic は、プラットフォーム固有のスタイリングに 2 つのモードを使用します。

プラットフォーム	デフォルトモード	スタイル
iOS	ios	Apple iOS デザイン
Android	md	Material Design
その他 / Web	md	Material Design

ブラウザーで特定のモードをプレビューするには、URL に ?ionic:mode=ios または ?ionic:mode=md を追加します。

http://localhost:8100/?ionic:mode=ios

CSS でモード固有のスタイルを指定します。

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

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

開発

ブラウザーでのプレビュー

主な開発ワークフローはブラウザーを使用します。

ionic serve

これにより、ライブリロードに対応した開発サーバーが http://localhost:8100 で起動します。

ブラウザーの DevTools を使ってモバイルデバイスをシミュレートします。

• Chrome：Cmd+Opt+I（Mac） / Ctrl+Shift+I（Windows/Linux）を押し、デバイスツールバーを切り替えます
• Safari：Cmd+Opt+R でレスポンシブデザインモードを開きます
• Firefox：Cmd+Opt+M（Mac） / Ctrl+Shift+M（Windows/Linux）

デバイスでのテスト

実機が必要なネイティブ機能をテストする場合：

npx cap run android
npx cap run ios

デバイスでライブリロードを使用する場合：

npx cap run android --livereload --external
npx cap run ios --livereload --external

デバッグのヒント

• debugger キーワードを使って、コードにブレークポイントを設定します。
• URL に ?ionic:mode=ios を追加すると、ブラウザーで iOS スタイルをプレビューできます。
• ionic info を使って、トラブルシューティング用の環境情報を収集します。

ユーティリティ

アニメーション

Ionic には、Web Animations API を基盤とする、フレームワークに依存しないアニメーションユーティリティが用意されています。次のようにインポートします。

• JavaScript/TypeScript：import { createAnimation } from '@ionic/core';
• Angular：@ionic/angular から AnimationController をインジェクトします
• React：@ionic/react の CreateAnimation コンポーネントを使用します
• Vue：import { createAnimation } from '@ionic/vue';

主なメソッド：addElement()、duration()、easing()、fromTo()、keyframes()、play()、pause()、stop()、onFinish()。

アニメーションは、グループ化（親子）、連鎖（play() の Promise を介して）、ジェスチャーとの統合をサポートしています。

パフォーマンスを高めるには、height や width よりも transform と opacity のアニメーションを優先してください。

ジェスチャー

Ionic は、フレームワークに依存しないジェスチャーユーティリティを提供します。インポート方法：

• JavaScript/TypeScript：import { createGesture } from '@ionic/core';
• Angular：@ionic/angular から GestureController をインジェクションします
• React：import { createGesture } from '@ionic/react';
• Vue：import { createGesture } from '@ionic/vue';

設定オプション：el、gestureName、threshold、direction（x／y）、maxAngle、gesturePriority、disableScroll、passive。

コールバック：canStart、onWillStart、onStart、onMove、onEnd、notCaptured。

GestureDetail オブジェクトには、startX／startY、currentX／currentY、deltaX／deltaY、velocityX／velocityY が含まれます。

ハードウェアの戻るボタン（Android）

Android のハードウェアの戻るボタンが押されると、Ionic は ionBackButton イベントを発行します。ハンドラーは優先度に基づいて処理されます。

優先度	ハンドラー
100	オーバーレイ
99	メニュー
0	ナビゲーション

Capacitor アプリでハードウェアの戻るボタンをサポートするには、@capacitor/app をインストールしてください。実装パターンについては、フレームワーク別のスキルを参照してください。

エラー処理

• ionic: command not found：Ionic CLI がインストールされていません。npm install -g @ionic/cli を実行してください。
• ポート 8100 が使用中：別のプロセスがデフォルトのポートを使用しています。ionic serve --port=<other-port> を実行してください。
• コンポーネントがレンダリングされない：グローバルスタイルシートで Ionic の CSS ファイルがインポートされていることを確認してください。Angular の場合：@import '@ionic/angular/css/core.css';。React／Vue の場合：フレームワーク固有のインポートを確認してください。
• プラットフォームのスタイルが適用されない：@ionic/angular、@ionic/react、または @ionic/vue がインストールされ、設定されていることを確認してください。<html> 要素には ios または md クラスが必要です。
• ダークモードが機能しない：正しいダークパレットの CSS インポートが含まれていることを確認してください。クラス方式の場合は、<html> 要素に .ion-palette-dark が適用されていることを確認してください。
• CSS カスタムプロパティが適用されない：Ionic コンポーネントは Shadow DOM を使用します。内部要素を直接指定するのではなく、コンポーネントのドキュメントに記載されている CSS カスタムプロパティ（例：--background、--color）を使用してください。利用可能なプロパティについては、コンポーネントのリファレンスファイルを確認してください。
• デバイスでライブリロードが機能しない：デバイスと開発マシンが同じネットワーク上にあることを確認してください。npx cap run で --external フラグを使用してください。
• ionViewWillEnter が呼び出されない：このライフサイクルイベントは Ionic のルーティングコンポーネント（ion-router-outlet）でのみ呼び出されます。Ionic のルーティング統合を使用しない限り、標準のフレームワークルーターでは呼び出されません。

関連スキル

• ionic-app-creation — 新しい Ionic アプリを作成します。
• ionic-angular — Angular での Ionic（フレームワーク固有のパターン）。
• ionic-react — React での Ionic（フレームワーク固有のパターン）。
• ionic-vue — Vue での Ionic（フレームワーク固有のパターン）。
• ionic-app-upgrades — Ionic を新しいメジャーバージョンにアップグレードします。
• capacitor-app-development — Capacitor の一般的な開発。
• capacitor-plugins — Capacitor プラグインのインストールと設定。
• ionic-framework-mcp — MCP クライアントを現在の Ionic Framework ドキュメントに接続します。