Créer des applications mobiles avec Vue et Capacitor

In this tutorial, we’ll guide you through the process of converting a Vue web application into a native mobile app using Capacitor. You can also add Capgo Native Navigation and Transitions for a native mobile feel, and use tailwind-capacitor for safe areas.

À propos de Capacitor

Capacitor is a game-changing tool that allows you to easily integrate it into any web project and convert your application into a native mobile app. It generates native Xcode and Android Studio projects for you and provides access to native device features like the camera through a JavaScript bridge.

Préparation de votre application Vue

Premièrement, créez une nouvelle application Vue en exécutant la commande suivante :

vue create my-app
cd my-app
npm install

To préparer votre application Vue pour le déploiement natif mobile, vous devrez exporter votre projet. Ajoutez un script dans votre fichier package.json Pour construire et copier le projet Vue :

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

Après avoir exécuté la build commande, vous devriez voir un nouveau dist dossier dans le répertoire racine de votre projet. Ce dossier sera utilisé par Capacitor plus tard.

Ajouter Capacitor à votre application Vue

Suivez ces étapes pour convertir votre application web Vue en conteneur mobile natif :

Install the Capacitor CLI as a development dependency and set it up within your project. Accept the default values for name and bundle ID during the setup.
Installez le package de base et les packages pertinents pour les plateformes iOS et Android.
Ajoutez les plateformes, et Capacitor créera des dossiers pour chaque plateforme à la racine de votre projet :

# 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

Vous devriez maintenant voir de nouvelles iOS et android dossiers dans votre projet Vue.

Mettez à jour le capacitor.config.json fichier pour pointer vers le webDir résultat de votre commande de build :

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

Maintenant, vous pouvez construire votre projet Vue et le synchroniser avec Capacitor :

npm run build
npx cap sync

Construire et Déployer des Applications Natives

Pour développer des applications iOS, vous devez avoir Xcode installé, et pour les applications Android, vous devez avoir Android Studio installé. De plus, vous devez vous inscrire au programme Apple Developer pour les applications iOS et au Google Play Console pour les applications Android pour distribuer votre application sur l'app store.

Utilisez les Capacitor CLI pour ouvrir les deux projets natives :

npx cap open ios
npx cap open android

Déployez votre application sur un appareil connecté à l'aide d'Android Studio ou de Xcode.

Capacitor Live Reload

Activer la rechargement en direct sur votre appareil mobile en faisant charger le contenu par l'application Capacitor à partir d'une URL spécifique de votre réseau.

Trouvez votre adresse IP locale et mettez à jour le capacitor.config.ts fichier avec l'adresse IP et le port corrects :

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;

Appliquez ces modifications en les copiant dans votre projet natif :

npx cap copy

Votre application se rechargera automatiquement et affichera les modifications lorsque vous mettez à jour votre application Vue.

Utiliser des plugins Capacitor

Installez un plugin Capacitor, comme le plugin de partage, et utilisez-le dans votre application Vue :

npm i @capacitor/share

fonction dans votre application : share() fonction dans votre application :

<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>

After avoir installé de nouveaux plugins, exécutez le sync commande et redéployez l'application sur votre appareil :

npx cap sync

Ensuite, vous pouvez rendre l'application ressembler à une application native sur iOS et Android avec la navigation et les transitions Capgo et corriger les problèmes de mise en page courants d'iOS qui provoquent un débordement horizontal ou des zones de sécurité coupées.

J'ai travaillé pendant des années avec Ionic pour construire des applications cross-platform, mais l'intégration de Ionic avec Vue est hacky et rarement valable lorsque vous avez déjà Tailwind CSS.

Pour un sentiment mobile natif dans une application Vue + Capacitor , utilisez les plugins Capgo au lieu des kits UI web uniquement comme Konsta UI :

@capgo/capacitor-navigation native — barre de navigation native, Liquid Glass barre de tab sur iOS, et un style de barre de tab flou sur Android. Votre routeur Vue conserve l'état de la route ; le plugin possède la barre de chrome native.
@capgo/capacitor-transitions — Transition de page Ionic et iOS edge swipe-back dans la couche WebView, sans adopter l'interface utilisateur Ionic.

Installez les deux :

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

Configurez la navigation native avec le mode d'insertion CSS pour que le contenu web respecte les barres natives :

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

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

Afficher une barre d'onglets Liquid Glass (iOS utilise la mise en page système ; Android utilise un arrière-plan flou 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}`);
});

Add native page transitions in your app shell:

<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>

Enveloppez les pages routées dans cap-router-outlet, cap-pageet cap-contentet appelez setDirection('forward') ou setDirection('back') Avant de naviguer. N'ajoutez pas de titres ou de pieds de page web si la navigation native les gère déjà.

Voir les guides complets : Utiliser @capgo/capacitor-navigation native And En utilisant @capgo/capacitor-transitions.

Les zones de sécurité avec Tailwind

For device safe areas in Tailwind CSS, use @capgo/tailwind-capacitor paru sur __CAPGO_KEEP_0__ tailwind-capacitor Cela s'applique à npm). Il fournit safe-areas outils et autres plugins Tailwind compatibles avec Capacitor :

bun add -D tailwind-capacitor

In src/assets/main.css:

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

Utilisez des outils tels que pt-safe, pb-safe, and px-safe au lieu de répandre env(safe-area-inset-*) à la main. Le projet est actuellement développé — si quelque chose manque pour votre configuration Vue, ouvrir une PR sur GitHub.

Résoudre les problèmes de mise en page iOS (Vueport, Zone de sécurité et débordement horizontal)

Si le contenu semble coupé, décalé ou déroulable horizontalement sur iOS, ajouter plus overflow-x: hidden ou ajuster seul le tag de vueport ne suffit généralement pas. Travaillez à travers ces vérifications dans l'ordre.

Assurez-vous que le tag meta de vueport est appliqué correctement

Ajoutez le tag meta de vueport dans index.html à l'intérieur <head>:

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

Gérer la zone de sécurité iOS à partir d'un seul wrapper racine

Créez un noyau d'application unique et appliquez une marge de zone de sécurité là-bas — et non dans plusieurs composants imbriqués :

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);
}

Wrap all page content inside un élément `<ion-app>`. .app-shellLes marges de sécurité dupliquées dans les en-têtes, les modaux et les enveloppes de mise en page rendent souvent l'interface utilisateur coupée ou trop grande.

With @capgo/tailwind-capacitor, vous pouvez exprimer le même écartement avec des utilitaires comme pt-safe pb-safe px-safe on ce seul shell.

Configurez Capacitor iOS `contentInset` à `never` first

premier capacitor.config.tsPréférez l'insertion native désactivée et laissez CSS (ou la navigation native) contentInsetMode: 'css'Propriétaire de la zone de sécurité :

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

Mélanger les Capacitor automatiques d'encart de contenu avec CSS env(safe-area-inset-*) l'espace de padding est une cause courante de double espace.

Trouvez l'élément qui déborde vraiment

Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur fixe en pixels, ou un grand min-width.

Inpecteur Web Safari, exécutez :

[...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,
  }));

Avec Tailwind, remplacez w-screen par w-full lorsque possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screen, une mise en page fixe ou une zone de contenu de largeur fixe — pas de la balise meta viewport elle-même.

Conclusion

Capacitor est une excellente option pour créer des applications natives basées sur un projet web existant. Avec l'ajout de Capgo, il est encore plus facile d'ajouter des mises à jour en temps réel à votre application, vous assurant que vos utilisateurs ont toujours accès aux dernières fonctionnalités et corrections de bogues.

Learn how Capgo can help you build better apps faster, Inscrivez-vous pour un compte gratuit. Aujourd'hui.

Continuez à partir de Construire des applications mobiles avec Vue et Capacitor.

Si vous utilisez Construire des applications mobiles avec Vue et Capacitor. pour planifier le comportement des médias et de l'interface native, connectez-l’avec Utilisez @capgo/capacitor-activités-en-ligne pour la capacité native dans Utilisez @capgo/capacitor-activités-en-ligne. @capgo/capacitor-activités-en-ligne pour le détail d'implémentation dans @capgo/capacitor-activités-en-ligne. Utilisez @capgo/capacitor-joueur-de-videos pour la capacité native dans Utilisez @capgo/capacitor-joueur-de-videos. @capgo/capacitor-vidéo-joueur pour les détails d'implémentation dans @capgo/capacitor-vidéo-joueur, et En utilisant @capgo/capacitor-navigation-native pour la capacité native dans En utilisant @capgo/capacitor-navigation-native.