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

このチュートリアルでは、Capacitor を使用して Vue ウェブアプリをネイティブモバイルアプリに変換する手順を解説します。Capgo Native Navigation and Transitions を追加してネイティブアプリのような操作感を実現したり、セーフエリア対策に tailwind-capacitor を活用したりすることも可能です。

Capacitor について

Capacitor は、あらゆるウェブプロジェクトに簡単に統合でき、アプリケーションをネイティブモバイルアプリへと変換できる画期的なツールです。Xcode や Android Studio のネイティブプロジェクトを自動生成し、JavaScript ブリッジを通じてカメラなどのデバイスのネイティブ機能へのアクセスを提供します。

Vue アプリの準備

まず、次のコマンドを実行して新しいVueアプリを作成します：

vue create my-app
cd my-app
npm install

Vueアプリをネイティブモバイル展開用に準備するには、プロジェクトをエクスポートする必要があります。まず、 package.json ファイルに、Vueプロジェクトをビルドしてコピーするためのスクリプトを追加します：

{
  "scripts": {
    // ...
    "build": "vue-cli-service build"
  }
}

次の build コマンドを実行すると、プロジェクトのルートディレクトリに新しい dist フォルダが作成されます。このフォルダは、後ほどCapacitorで使用されます。

VueアプリへのCapacitorの追加方法

Vueウェブアプリをネイティブモバイルコンテナに変換するには、以下の手順に従ってください：

Capacitor CLI を開発用依存関係としてインストールし、プロジェクト内でセットアップします。セットアップ中の name と bundle ID はデフォルト値のまま進めてください。
コアパッケージと、iOSおよびAndroidプラットフォーム用の関連パッケージをインストールします。
プラットフォームを追加すると、Capacitor がプロジェクトのルートに各プラットフォーム用のフォルダを作成します：

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

# Initialize Capacitor in your Vue 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

Vueプロジェクト内に新しい iOSと と android フォルダが表示されているはずです。

を更新する capacitor.config.json ファイルを更新して、 webDir をビルドコマンドの出力先に設定してください：

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

これで、Vueプロジェクトをビルドして Capacitor と同期できるようになります：

npm run build
npx cap sync

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

iOSアプリの開発にはXcodeのインストールが必要で、AndroidアプリにはAndroid Studioが必要です。また、アプリを各ストアで配信するには、iOSの場合はApple Developer Program、Androidの場合はGoogle Play Consoleへの登録が必要です。

以下の Capacitor CLI を使用して、両方のネイティブプロジェクトを開きます：

npx cap open ios
npx cap open android

Android StudioまたはXcodeを使用して、接続されたデバイスにアプリをデプロイします。

Capacitor Live Reload

ネットワーク上の特定のURLから Capacitor アプリがコンテンツを読み込むように設定することで、モバイルデバイス上でライブリロードを有効にします。

ローカルのIPアドレスを確認し、 capacitor.config.ts 正しいIPとポート番号で {} ファイルを更新してください：

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:8080',
    cleartext: true
  }
};

export default config;

変更内容をネイティブプロジェクトにコピーして適用します：

npx cap copy

これで、Vueアプリを更新するとアプリが自動的にリロードされ、変更が反映されます。

Capacitor プラグインの使用

Shareプラグインなどの Capacitor プラグインをインストールし、Vueアプリで使用します：

npm i @capacitor/share

パッケージをインポートして share() アプリ内の関数:

<template>
  <div>
    <h1>Welcome to Vue and Capacitor!</h1>
    <button @click="share">Share now!</button>
  </div>
</template>

<script setup lang="ts">
import { Share } from '@capacitor/share';

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

新しいプラグインをインストールした後は、 sync コマンドを実行し、デバイスにアプリを再デプロイしてください:

npx cap sync

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

私は長年、 Ionic はクロスプラットフォームアプリの開発に使用されますが、すでに Tailwind CSS.

Vue + Capacitor のアプリでネイティブな操作感を実現するには、Konsta UI のような Web 専用 UI キットではなく、Capgo プラグインを使用してください:

@capgo/capacitor-native-navigation — ネイティブのナビゲーションバー、iOS の Liquid Glass タブバー、Android のブラーがかかったタブバースタイルなどが利用可能です。Vue router がルートの状態を保持し、プラグインがネイティブの UI 要素（chrome）を制御します。
@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バックドロップを使用します）：

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.push(`/${id}`);
});

アプリシェルにネイティブのページ遷移を追加します：

<script setup>
import { ref, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import '@capgo/capacitor-transitions';
import { initTransitions, setDirection, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';

initTransitions({ platform: 'auto' });

const router = useRouter();
const outletRef = ref(null);

onMounted(() => {
  if (outletRef.value) {
    setupRouterOutlet(outletRef.value, { platform: 'auto', swipeGesture: 'auto' });
  }
});

const openSettings = () => {
  setDirection('forward');
  router.push('/settings');
};
</script>

<template>
  <cap-router-outlet ref="outletRef">
    <router-view />
  </cap-router-outlet>
</template>

ルーティングされたページを 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/assets/main.css:

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

次のようなユーティリティを使用します： pt-safe, pb-safeや px-safe 散りばめるのではなく、 env(safe-area-inset-*) 手動で行う方法です。このプロジェクトは活発に開発されており、Vueの設定で不足しているものがあれば、 GitHub で PR を作成してください.

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

iOSでコンテンツが切れたり、ずれたり、横スクロールが発生したりする場合、単に overflow-x: hidden viewportタグを追加・調整するだけでは解決しないことがよくあります。以下の手順で順に確認してください。

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

viewport メタタグを以下に追加します index.html 既存の <head>:

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

iOS のセーフエリアは単一のルートラッパーでのみ処理する

単一の App Shell を作成し、そこにセーフエリアのパディングを適用してください。複数のネストされたコンポーネントに適用してはいけません：

html,
body,
#app {
  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: 'dist',
  ios: {
    contentInset: 'never',
  },
};

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

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

主な原因は、以下のような要素です： 100vwTailwindを使用している場合、 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-screenviewportのmetaタグそのものではなく、safe-area paddingの重複や、固定幅のコンテナによって発生します。

まとめ

既存のWebプロジェクトをベースにネイティブアプリを構築する場合、Capacitor は非常に優れた選択肢です。さらに Capgo を組み合わせることで、アプリへの Live Update の追加がより簡単になり、ユーザーは常に最新の機能やバグ修正を利用できるようになります。

Capgo を活用して、より高品質なアプリを高速に開発する方法を学びましょう。無料アカウントに登録するを今すぐ作成してください。