Créer des applications mobiles avec Vue et Capacitor

Dans ce tutoriel, nous vous guiderons à travers le processus de conversion d'une application web Vue en application mobile native en utilisant Capacitor. Vous pouvez également ajouter Capgo Navigation et transitions natives pour un sentiment mobile natif, et utiliser tailwind-capacitor pour les zones de sécurité.

À propos de Capacitor

Capacitor est un outil révolutionnaire qui vous permet d'intégrer facilement Capacitor dans tout projet web et de convertir votre application en application mobile native. Il génère des projets Xcode et Android Studio natifs pour vous et vous donne accès aux fonctionnalités de dispositif natif comme la caméra à travers un pont JavaScript.

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

Pour préparer votre application Vue à la mise en production mobile native, vous aurez besoin d'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 commande, vous devriez voir un nouveau dossier dans le répertoire root de votre projet. Ce dossier sera utilisé par __CAPGO_KEEP_0__ plus tard. build Vous devriez voir un nouveau dossier dans le répertoire root de votre projet. dist Ce dossier sera utilisé par Capacitor plus tard.

Ajouter Capacitor à votre application Vue

Pour convertir votre application web Vue en conteneur mobile natif, suivez ces étapes :

Installez le Capacitor CLI en tant que dépendance de développement et configurez-le dans votre projet. Acceptez les valeurs par défaut pour le nom et l'ID de l'application lors de la configuration.
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 au niveau du répertoire root 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 nouveaux iOS et android dossiers de votre projet Vue.

Mettre à jour le capacitor.config.json fichier pour pointer le webDir vers le 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 avez besoin d'Xcode installé, et pour les applications Android, vous avez besoin d'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 le 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 d'Xcode.

Capacitor Live Reload

Activez le rechargement en direct sur votre appareil mobile en faisant en sorte que l'application Capacitor charge le contenu à partir d'une URL spécifique sur 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 vers votre projet natif :

npx cap copy

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

En utilisant les plugins Capacitor

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

npm i @capacitor/share

Importez le package et appelez la 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>

Après avoir installé de nouveaux plugins, exécutez la sync commande et redéployez l'application sur votre appareil :

npx cap sync

Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec les navigations et transitions Capgo et corriger les problèmes de mise en page iOS courants qui entraînent un débordement horizontal ou des zones de sécurité coupées.

J'ai travaillé pendant des années avec Ionic pour créer des applications cross-platform, mais intégrer Ionic avec Vue est fastidieux et rarement justifié 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. Le routeur Vue conserve l'état de la route ; le plugin possède la barre de chrome native.
@capgo/capacitor-transitions — transitions de page à la manière d'Ionic et iOS edge swipe-back dans la couche WebView, sans adopter les UI d'Ionic.

Installez les deux :

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

Configurez la navigation native avec le mode CSS inset afin 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 un onglet de verre liquide (iOS utilise la mise en page système ; Android utilise un arrière-plan flou d'une fenêtre 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}`);
});

Ajoutez des transitions de page natives dans votre coquille d'application :

<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-page, et cap-content, et appelez setDirection('forward') ou setDirection('back') avant de naviguer. N'ajoutez pas de titres ou de pieds de page web lorsqu'une navigation native possède ces surfaces.

Voir les guides complets : Utiliser @capgo/capacitor-navigation-native et Utiliser @capgo/capacitor-transitions.

Aires de sécurité avec Tailwind

Pour les zones de sécurité des appareils dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor sur npm). Il fournit safe-areas des utilitaires et d'autres plugins de Tailwind compatibles avec Capacitor:

bun add -D tailwind-capacitor

Dans src/assets/main.css:

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

Utilisez des utilitaires comme pt-safe, pb-safe, et px-safe au lieu de les répandre env(safe-area-inset-*) manuellement. Le projet est actuellement développé — si quelque chose manque pour votre configuration Vue, ouvre une PR sur GitHub.

Résolution des problèmes de mise en page iOS (Vueport, zone de sécurité et débordement horizontal)

Si le contenu semble coupé, décalé ou scrollable horizontalement sur iOS, ajouter plus ou ajuster la balise de viewport seul ne résout généralement pas le problème. Travaillez ces vérifications dans l'ordre. overflow-x: hidden Assurez-vous que la balise de viewport meta est appliquée correctement

Ajoutez la balise de viewport meta dans

à l'intérieur index.html Gérez l'espace sûr d'iOS à partir d'un seul wrapper racine <head>:

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

Créez une coquille d'application unique et appliquez-y le padding de l'espace sûr — pas dans plusieurs composants imbriqués :

Enveloppez tout le contenu de la page à l'intérieur

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

Le padding de l'espace sûr dupliqué dans les en-têtes, les modaux et les enveloppes de disposition rend souvent l'interface utilisateur coupée ou trop grande. .app-shellAvec

@__CAPGO_KEEP_0__/tailwind-__CAPGO_KEEP_1__ @capgo/tailwind-capacitorDuplicated safe-area padding in headers, modals, and layout wrappers often makes the UI look cropped or too large. pt-safe pb-safe px-safe sur cette seule coquille.

Définissez Capacitor iOS `contentInset` sur `never` premier

In capacitor.config.ts, préférez l'insertion native désactivée et laissez CSS (ou la navigation native) gérer la zone de sécurité : contentInsetMode: 'css'Mélanger les marges automatiques de contenu de __CAPGO_KEEP_0__ avec les marges CSS

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

Mixing Capacitor’s automatic content inset with CSS env(safe-area-inset-*) Trouvez l'élément qui déborde vraiment

Le coupable habituel est un élément utilisant

, Tailwind 100vwMélangez pas les marges automatiques de contenu de __CAPGO_KEEP_0__ avec les marges CSS w-screen, une largeur de pixels fixe, ou une large min-width.

Dans l'inspecteur Web de 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, de la mise en forme de zone de sécurité dupliquée, ou d'un conteneur à largeur fixe — et non de la balise meta de la zone de vue 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 aient toujours accès aux dernières fonctionnalités et corrections de bogues.

Découvrez comment Capgo peut vous aider à créer des applications meilleures et plus rapides, Inscrivez-vous à un compte gratuit aujourd'hui.

Continuez à partir de la création d'applications mobiles avec Vue et Capacitor

Si vous utilisez Créer des applications mobiles avec Vue et Capacitor pour planifier le comportement de médias et d'interface natives, connectez-le avec Utiliser @capgo/capacitor-activités-en-ligne pour la capacité native dans Utiliser @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, Utiliser @capgo/capacitor-joueur-de-videos pour la capacité native dans Utiliser @capgo/capacitor-joueur-de-videos, @capgo/capacitor-joueur-de-videos pour le détail d'implémentation dans @capgo/capacitor-joueur-de-videos, et Utiliser @capgo/capacitor-navigation-native pour la capacité native en utilisant @capgo/capacitor-navigation-native.