AngularとCapacitorによるモバイルアプリ開発

このチュートリアルでは、まず新しい Angular アプリを作成して、Capacitorを使ってネイティブモバイルアプリの世界へ移行します。ネイティブアプリらしい操作感のためにCapgo Native Navigation and Transitionsを追加し、safe areasにはtailwind-capacitorを使用できます。

Capacitorを使用すると、React Nativeのような新しいスキルを学ぶ必要もなく、大規模な改修なしにAngularのWebアプリケーションをネイティブモバイルアプリに簡単に変換できます。

ほんの数ステップで、ほとんどのAngularアプリケーションをモバイルアプリに変換できます。

このチュートリアルでは、新しいAngularアプリから始めて、Capacitorを組み込んでネイティブモバイルアプリの世界へ移行するプロセスを案内します。Capgo Native Navigation, Transitionsをナビゲーションとトランジションに、safe areasにはtailwind-capacitorを使用できます。

Capacitor について

CapacitorJS はまさにゲームチェンジャーです！あらゆるWebプロジェクトに簡単に組み込むことができ、アプリケーションをネイティブWebViewでラップし、XcodeやAndroid Studioのネイティブプロジェクトを自動生成します。さらに、プラグインを使えば、JSブリッジ経由でカメラなどのネイティブデバイス機能にアクセスできます。

Capacitor を使えば、複雑なセットアップも高い学習コストも不要で、素晴らしいネイティブモバイルアプリを手に入れられます。軽量な API と無駄のない機能で、プロジェクトへの統合もとても簡単です。Capacitor なら、フル機能のネイティブアプリをこれほど簡単に作れることにきっと驚きますよ！

Angular アプリの準備

新しい Angular アプリを作成するには、以下のコマンドを実行します:

ng new my-app
cd my-app

Angular バージョンを尋ねられたら「Angular」を選択してください。

ネイティブモバイルアプリを作成するには、 エクスポート が必要です。そこで、シンプルなスクリプトを package.json が必要です。これにより Angular プロジェクトをビルドしてコピーできます:

{
  "scripts": {
    // ...
    "build": "ng build --prod"
  }
}

コマンドを実行した後、 build新しい dist フォルダがプロジェクトのルートに確認できるはずです。

このフォルダは後ほど Capacitor で使用されますが、まずは正しくセットアップする必要があります。

Angular アプリへの Capacitor の追加

Webアプリをネイティブモバイルコンテナにパッケージ化するには、いくつかの初期ステップが必要ですが、その後は単一のコマンドを実行するだけです。 sync コマンドを実行してください。

まず、次をインストールします： Capacitor CLI development dependency としてインストールし、プロジェクト内でセットアップします。セットアップ中は「Enter」キーを押すことで、名前と Bundle ID のデフォルト値を受け入れることができます。

次に、コアパッケージと iOS および Android プラットフォーム用の関連パッケージをインストールする必要があります。

最後に、プラットフォームを追加します。Capacitor を実行すると、プロジェクトのルートに各プラットフォーム用のフォルダが作成されます：

# Install the Capacitor CLI locally
npm install -D @capacitor/cli

# Initialize Capacitor in your Angular project
npx cap init

# Install the required packages
npm install @capacitor/core @capacitor/ios @capacitor/android

# Add the native platforms
npx cap add ios
npx cap add android

この時点で、Angular プロジェクト内に新しい iOS と Android フォルダが作成されているのが確認できるはずです。

これらは本物のネイティブプロジェクトです！

後で Android プロジェクトにアクセスするには、次をインストールする必要があります：デバッグ。iOSの場合はMacが必要で、次をインストールしてください： iOSプロファイリング.

さらに、プロジェクト内に次のファイルがあるはずです： capacitor.config.ts プロジェクト内のファイルで、同期時に使用される基本的なCapacitor設定が含まれています。注意すべき点は webDirは、ビルドコマンドの出力先を指している必要があります。現在は正しくありません。

これを修正するには、次を開いてください： capacitor.config.json ファイルを開き、次を更新してください： webDir:

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "dist"
}

次のコマンドを実行すると試せます：

npm run build
npx cap sync

最初のコマンドは npm run build は Angular プロジェクトをビルドして静的ビルド成果物をコピーするだけで、2番目のコマンドは npx cap sync すべてのWeb code をネイティブプラットフォームの適切な場所に同期し、アプリ内で表示できるようにします。

さらに、syncコマンドはネイティブプラットフォームの更新やプラグインのインストールを行う可能性があるため、新しい Capacitor プラグインを実行する時間です npx cap sync を再度呼び出してください。

気づかぬうちにすでに完了しています。では、デバイス上でアプリを確認しましょう！

ネイティブアプリのビルドとデプロイ

iOSアプリを開発するには、 iOSプロファイリング のインストールが必要です。また、Androidアプリの場合は、 デバッグ インストールしてください。また、アプリストアでアプリを配布する場合は、iOS には Apple Developer Program、Android には Google Play Console に登録する必要があります。

ネイティブモバイル開発が初めてなら、Capacitor CLI を使って両方のネイティブプロジェクトを簡単に開けます：

npx cap open ios
npx cap open android

ネイティブプロジェクトの設定が完了すれば、接続されたデバイスへのアプリのデプロイは簡単です。Android Studioでは、準備が整うのを待つだけで、設定を変更することなく接続デバイスへアプリをデプロイできます。例を以下に示します：

Android Studioで実行

Xcodeでは、シミュレーターではなく実機にアプリをデプロイするために、Signingアカウントの設定が必要です。初めての場合は、Xcodeのガイドに従って設定を進めてください（ただし、Developer Programへの登録が必要です）。設定後は、上部で選択した接続済みデバイスで、再生ボタンを押すだけでアプリを実行できます。例を以下に示します：

Xcodeで実行

おめでとうございます！Angularウェブアプリをモバイルデバイスにデプロイできました。例を以下に示します：

でもちょっと待ってください。開発中にもっと速い方法があります…

Capacitor Live Reload

最近のフレームワークを使っていれば、ホットリロードには慣れているはずです。嬉しいことに、同じ機能を モバイルデバイス上でも 最小限の手間で利用できます！

Live Reloadでローカルでホストしているアプリへのアクセスを有効にする ネットワーク上で Capacitor アプリに特定のURLからコンテンツを読み込ませることで。

まず、ローカルIPアドレスを確認します。Macの場合は、ターミナルで次のコマンドを実行すると確認できます：

ipconfig getifaddr en0

Windowsの場合は、次を実行してください：

ipconfig

次に、IPv4アドレスを探します。

設定に別のエントリを追加することで、Capacitor にサーバーから直接アプリを読み込ませられます。 capacitor.config.ts ファイル内で参照します：

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  bundledWebRuntime: false,
  server: {
    url: 'http://192.168.x.xx:4200',
    cleartext: true
  }
};

export default config;

必ず使用してください： 正しいIPアドレスとポート番号、この例では Angular のデフォルトポートを使用しています。

これで、これらの変更をネイティブプロジェクトにコピーして適用できます：

npx cap copy

この copy コマンドは次と似ています syncただし、 webフォルダと設定への変更内容だけをコピーし、 ネイティブプロジェクトは更新しません。

これで、Android StudioまたはXcodeでアプリをもう一度デプロイできます。その後、Angularアプリに変更を加えると、 アプリが自動的にリロードされ、 変更が反映されます！

注意点として、 カメラなどの新しいプラグインをインストールする場合、ネイティブプロジェクトの再ビルドが必要です。ネイティブファイルが変更されるため、その場で行うことはできません。

設定では正しいIPとポートを使用してください。上記の code ブロックは、デモ用にAngularのデフォルトポートを示しています。

Capacitor プラグインの使用

これまで何度か触れてきた Capacitor プラグインの実際の使い方を見てみましょう。次のコマンドを実行して、かなりシンプルなプラグインをインストールできます：

npm i @capacitor/share

特別なものはありませんが、プラグインを共有、それでもネイティブ共有ダイアログが表示されます！あとはパッケージをインポートして、対応するメソッドを呼び出すだけです。 share() アプリから関数を呼び出すだけなので、次は src/app/app.component.ts を次のように変更します：

import { Component } from '@angular/core';
import { Share } from '@capacitor/share';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  title = 'my-app';

  async share() {
    await Share.share({
      title: 'Open Youtube',
      text: 'Check new video on youtube',
      url: 'https://www.youtube.com',
      dialogTitle: 'Share with friends'
    });
  }
}

先ほど説明したように、新しいプラグインをインストールするときは、sync 操作を行ってからアプリをデバイスに再デプロイする必要があります。これを行うには、次のコマンドを実行してください：

npx cap sync

ボタンを押すと、美しいネイティブの共有ダイアログが実際に動作する様子を確認できます！

次に、Capgo のナビゲーションとトランジションで、iOS と Android でアプリをよりネイティブに感じさせ、横方向のオーバーフローやセーフエリアの欠けを引き起こす iOS でよくあるレイアウト問題も修正できます。

私は長年、 Ionic to build cross-platform applications, but integrating it with Angular is hacky and rarely worth it when you already have Tailwind CSS がある場合は、あまりメリットがありません。.

Angular + Capacitor アプリでネイティブなモバイル感を出すには、Konsta UIのようなWeb専用UIキットではなく、Capgo プラグインを使ってください:

@capgo/capacitor-native-navigation — ネイティブなナビゲーションバー、iOSのLiquid Glassタブバー、Androidのブラー付きタブバースタイル。Angularルーターがルート状態を保持し、ネイティブUIはプラグインが担当します。
@capgo/capacitor-transitions — Ionic UIを採用せずに、WebViewレイヤーでIonicスタイルのページ遷移とiOSのエッジスワイプによる戻る操作を実現します。

両方をインストールしてください：

bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap sync

CSS insetモードでネイティブナビゲーションを設定し、Webコンテンツがネイティブバーと重ならないようにします：

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Liquid Glassタブバーをレンダリングします（iOSはシステム側のレンダリングを使用し、Androidはぼかし付きWebViewバックドロップを使用します）：

import { inject } from '@angular/core';
import { Router } from '@angular/router';

const router = inject(Router);

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'labeled',
  icons: true,
  colors: { dynamic: true },
  tabs: [
    { id: 'home', title: 'Home', icon: { svg: '...' } },
    { id: 'settings', title: 'Settings', icon: { svg: '...' } },
  ],
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  router.navigate([`/${id}`]);
});


Add native page transitions in your app shell:

```typescript
// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
import { Router } from '@angular/router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions';

initTransitions({ platform: 'auto' });

@Component({
  selector: 'app-root',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <cap-router-outlet #outlet platform="auto" swipe-gesture="auto">
      <router-outlet></router-outlet>
    </cap-router-outlet>
  `,
})
export class AppComponent implements AfterViewInit {
  @ViewChild('outlet') outlet?: ElementRef<HTMLElement>;

  constructor(private router: Router) {}

  ngAfterViewInit() {
    if (this.outlet?.nativeElement) {
      setupRouterOutlet(this.outlet.nativeElement, { platform: 'auto', swipeGesture: 'auto' });
    }
  }

  openSettings() {
    setDirection('forward');
    this.router.navigate(['/settings']);
  }
}

ルーティングされたページを以下でラップします： cap-router-outlet, cap-pageや cap-content、そして呼び出します setDirection('forward') または setDirection('back') 遷移前に実行してください。ネイティブナビゲーションがその領域を管理している場合、Webのヘッダーやフッターを重複させないでください。

ガイドの全文はこちら： @capgo/capacitor-native-navigation の活用と @capgo/capacitor-transitions の活用.

Tailwind によるセーフエリア対応

Tailwind CSS でデバイスのセーフエリアを扱うには、以下を使用します： @capgo/tailwind-capacitor （ tailwind-capacitor として npm で公開）。これは、 safe-areas ユーティリティや Capacitor と相性の良いその他の Tailwind プラグインを提供します：

bun add -D tailwind-capacitor

では src/styles.css:

@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";

次のようなユーティリティを使用します： pt-safe, pb-safeや px-safe 手作業でばらまくのではなく env(safe-area-inset-*) このプロジェクトは活発に開発されています — Angularのセットアップに足りないものがあれば、 GitHub でPRを作成してください.

iOSのレイアウト問題を修正（ビューポート、セーフエリア、横方向のオーバーフロー）

iOSでコンテンツが切れて見えたり、ずれて見えたり、横スクロールが発生したりする場合は、さらに追加するだけでも、 overflow-x: hidden viewportタグを調整するだけでも通常は解決しません。以下のチェックを順番に確認してください。

viewport メタタグが正しく適用されているか確認する

では src/index.html、にviewportメタタグを設定します <head>:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

iOSのセーフエリアは1つのルートラッパーだけで処理する

単一のアプリシェルを作成し、そこにセーフエリアのパディングを適用してください — 複数のネストしたコンポーネントではなく：

html,
body,
app-root {
  width: 100%;
  min-height: 100%;
  margin: 0;
  padding: 0;
  overflow-x: hidden;
}

* {
  box-sizing: border-box;
}

.app-shell {
  min-height: 100dvh;
  width: 100%;
  padding-top: env(safe-area-inset-top);
  padding-right: env(safe-area-inset-right);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
}

すべてのページコンテンツを以下でラップします： .app-shellヘッダー、モーダル、レイアウトラッパーで safe-area のパディングが重複すると、UI が欠けたり、逆に大きすぎたりすることがよくあります。

を使用すると、 @capgo/tailwind-capacitor同じパディングを次のようなユーティリティで表現できます： pt-safe pb-safe px-safe その単一のシェル上で。

Capacitor iOS を設定 `contentInset` まで `never` 最初に

では capacitor.config.ts、native inset を無効にすることを推奨し、CSS（または Native Navigation のもの contentInsetMode: 'css'）に safe area を任せる：

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'my-app',
  webDir: 'www',
  ios: {
    contentInset: 'never',
  },
};

Capacitor の自動コンテンツ inset と CSS を混在させると env(safe-area-inset-*) padding は二重スペースのよくある原因です。

実際にオーバーフローしている要素を特定する

原因はたいてい、使用している要素です 100vw、Tailwind w-screen、固定ピクセル幅、または大きな min-width.

Safari Web Inspectorで以下を実行してください：

[...document.querySelectorAll('*')]
  .filter(el => el.scrollWidth > document.documentElement.clientWidth)
  .map(el => ({
    el,
    tag: el.tagName,
    class: el.className,
    scrollWidth: el.scrollWidth,
    clientWidth: document.documentElement.clientWidth,
  }));

Tailwindを使用する場合は、可能な限り w-screen を使用して w-full 置き換えてください。水平方向のオーバーフロー問題の多くは 100vw / w-screen、重複したセーフエリアのパディング、または固定幅のコンテナに起因し、viewportのmetaタグ自体が原因ではありません。

まとめ

Capacitor は、既存のWebプロジェクトをベースにネイティブアプリを構築するための優れた選択肢です。code を簡単に共有し、一貫したUIを維持できます。

さらに、追加されたことで Capgo、アプリへのLive Updatesの追加がより簡単になり、ユーザーは常に最新の機能とバグ修正を利用できます。

AngularアプリにCapgoを追加する方法については、次の記事をご覧ください：