Dans ce tutoriel, nous vous guidons à travers le processus de conversion d'une application web Vue en application mobile native à l'aide de Capacitor. Vous pouvez également ajouter Capgo Native Navigation and Transitions pour une sensation mobile native, et utiliser tailwind-capacitor pour les zones de sécurité.
À propos de Capacitor
Capacitor est un outil révolutionnaire qui vous permet de l'intégrer facilement à tout projet web et de convertir votre application en application mobile native. Il génère des projets natifs Xcode et Android Studio pour vous et fournit un accès aux fonctionnalités natives de l'appareil, comme l'appareil photo, via un pont JavaScript.
Préparer votre application Vue
D'abord, 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 au déploiement mobile natif, vous devez exporter votre projet. Ajoutez un script dans votre package.json fichier pour compiler et copier le projet Vue :
{
"scripts": {
// ...
"build": "vue-cli-service build"
}
}
Après avoir exécuté la commande build , vous devriez voir un nouveau dist dossier à la racine de votre projet. 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 comme dépendance de développement et configurez-le dans votre projet. Acceptez les valeurs par défaut pour le nom et le bundle ID lors de la configuration.
-
Installez le package core ainsi que les packages nécessaires pour les plateformes iOS et Android.
-
Ajoutez les plateformes, et Capacitor créera un dossier 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 nouveaux iOS et Android dossiers dans votre projet Vue.
Mettez à jour le capacitor.config.json pour pointer le webDir vers le résultat de votre commande de build :
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}
Vous pouvez maintenant compiler votre projet Vue et le synchroniser avec Capacitor :
npm run build
npx cap sync
Compiler et déployer des apps natives
Pour développer des apps iOS, vous devez avoir Xcode installé et, pour les apps Android, Android Studio. Vous devez aussi vous inscrire à l'Apple Developer Program pour iOS et à la Google Play Console pour Android afin de distribuer votre app sur les stores.
Utilisez Capacitor CLI pour ouvrir les deux projets natifs :
npx cap open ios
npx cap open android
Déployez votre app sur un appareil connecté via Android Studio ou Xcode.
Live Reload avec Capacitor
Activez le live reload sur votre appareil mobile en configurant l'app Capacitor pour charger le contenu depuis une URL spécifique de votre réseau.
Trouvez votre adresse IP locale et mettez à jour le capacitor.config.ts fichier avec l'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 changements en les copiant dans votre projet natif :
npx cap copy
Now, your app will automatically reload and show changes when you update your Vue app.
Utiliser les plugins Capacitor
Installez un plugin Capacitor, comme le plugin Share, et utilisez-le dans votre app 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 l’installation 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 la navigation et les transitions Capgo, et corriger les problèmes de mise en page iOS courants qui causent des débordements horizontaux ou des safe areas rognées.
Une interface fluide avec Capgo Native Navigation et Transitions
J'ai travaillé pendant des années avec Ionic pour compiler des applications multiplateformes, mais l’intégrer à Vue est bricolé et rarement intéressant quand vous avez déjà Tailwind CSS.
Pour un rendu mobile natif dans une app Vue + Capacitor, utilisez les plugins Capgo plutôt que des kits UI web-only comme Konsta UI :
- @capgo/capacitor-native-navigation — barre de navigation native, barre d’onglets Liquid Glass sur iOS et style de barre d’onglets floutée sur Android. Votre routeur Vue conserve l’état des routes ; le plugin gère l’habillage natif.
- @capgo/capacitor-transitions — des transitions de page façon Ionic et le swipe-back depuis le bord sur iOS dans la couche WebView, sans adopter l'UI 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 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',
},
});
Affichez une barre d'onglets Liquid Glass (iOS utilise le rendu du système ; Android utilise un fond WebView flouté) :
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 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-page, et cap-content, et appelez setDirection('forward') ou setDirection('back') avant de naviguer. Ne dupliquez pas les headers ou footers web lorsque la navigation native gère ces surfaces.
Consultez les guides complets : Utilisation de @capgo/capacitor-native-navigation et Utiliser @capgo/capacitor-transitions.
Safe areas avec Tailwind
Pour les safe areas de l'appareil avec Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor sur npm). Il fournit safe-areas utilitaires et d'autres plugins Tailwind compatibles 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 tels que pt-safe, pb-safe, et px-safe au lieu de parsemer env(safe-area-inset-*) à la main. Le projet est activement développé — s'il manque quelque chose pour votre configuration Vue, ouvrez une PR sur GitHub.
Corriger les problèmes de mise en page iOS (viewport, zone sécurisée et débordement horizontal)
Si le contenu semble coupé, décalé ou défile horizontalement sur iOS, ajouter plus de overflow-x: hidden ou le simple ajustement de la balise viewport ne règle généralement pas le problème. Effectuez ces vérifications dans l'ordre.
Assurez-vous que la balise meta viewport est correctement appliquée
Ajoutez la balise meta viewport dans index.html à l'intérieur <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
Gérez la safe area iOS depuis un seul wrapper racine
Créez un shell d'application unique et appliquez-y le padding de la safe area — pas 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);
}
Enveloppez tout le contenu de la page dans .app-shell. Un padding de safe area dupliqué dans les headers, les modales et les wrappers de layout donne souvent l'impression que l'UI est rognée ou trop grande.
Avec @capgo/tailwind-capacitor, vous pouvez obtenir le même padding avec des utilitaires comme pt-safe pb-safe px-safe sur ce shell unique.
Configurez Capacitor iOS contentInset vers never d'abord
Dans capacitor.config.ts, préférez désactiver les insets natifs et laissez le CSS (ou la contentInsetMode: 'css') gèrent la safe area :
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};
Combiner le content inset automatique de Capacitor avec le CSS env(safe-area-inset-*) le padding est une cause fréquente de double espacement.
Trouvez l'élément qui déborde réellement
Le coupable habituel est un élément utilisant 100vw, Tailwind w-screen, une largeur fixe en pixels, ou un grand min-width.
Dans le Web Inspector de Safari, lancez :
[...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 dès que possible. De nombreux problèmes de débordement horizontal proviennent de 100vw / w-screen, d'un padding safe-area dupliqué, ou d'un conteneur à largeur fixe — et non de la balise meta viewport elle-même.
Conclusion
Capacitor est une excellente option pour compiler des applications natives à partir d'un projet web existant. Avec Capgo, il est encore plus simple d'ajouter des live updates à votre app, en garantissant ainsi que vos utilisateurs ont toujours accès aux dernières fonctionnalités et corrections de bugs.
Learn how Capgo can help you build better apps faster, créez un compte gratuit aujourd'hui.
Continuez à partir de « Créer des applications mobiles avec Vue et Capacitor »
Si vous utilisez Développer des applications mobiles avec Vue et Capacitor pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la fonctionnalité native dans la section Utiliser @capgo/capacitor-video-player, @capgo/capacitor-video-player pour les détails d'implémentation dans @capgo/capacitor-video-player, et Utilisation de @capgo/capacitor-native-navigation pour la fonctionnalité native dans Using @capgo/capacitor-native-navigation.