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 Native et Transitions pour un sentiment d'application mobile native, 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 n'importe quel 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
Créez d'abord une nouvelle application Vue en exécutant la commande suivante :
vue create my-app
cd my-app
npm installPour préparer votre application Vue pour le déploiement mobile natif, 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 build commande, vous devriez voir un nouveau dist folder in your project’s root directory. This folder will be used by Capacitor later.
Capacitor
plus tard.
-
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.
-
Pour convertir votre application web Vue en un conteneur mobile natif, suivez ces étapes :
-
Installez le Capacitor __CAPGO_KEEP_1__ 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 durant 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 dans le 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 androidVous devriez maintenant voir de nouveaux iOS et android dossiers dans votre projet Vue.
Mettez à 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 syncConstruire et déployer des applications natives
To développer des applications iOS, vous avez besoin d'installer Xcode, et pour les applications Android, vous avez besoin d'installer Android Studio. 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 androidDéployez votre application sur un appareil connecté en utilisant Android Studio ou Xcode.
Capacitor Live Reload
Activer 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 fichier avec l'adresse IP et le port corrects : capacitor.config.ts Appliquez ces modifications en les copiant vers votre projet native :
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;Maintenant, votre application se rechargera automatiquement et affichera les modifications lorsque vous mettez à jour votre application Vue.
npx cap copyEn utilisant les __CAPGO_KEEP_0__ Plugins
Installez un plugin Capacitor , comme le plugin de partage, et utilisez-le dans votre application Vue :
Install a Capacitor plugin, such as the Share plugin, and use it in your Vue app:
npm i @capacitor/shareImportez le package et appelez la __CAPGO_KEEP_0__ 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 syncEnsuite, vous pouvez rendre l'application plus native sur iOS et Android avec Capgo navigation et transitions, 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.
UI native avec Capgo Navigation et Transitions Native
J'ai travaillé pendant des années avec Ionic pour construire des applications cross-platform, mais l'intégration avec Vue est hacky et rarement intéressante lorsque vous avez déjà Tailwind CSS.
Pour un sentiment mobile natif dans une application Vue + Capacitor , utilisez les Capgo plugins au lieu des kits UI web uniquement comme Konsta UI :
- @capgo/capacitor-navigation-native — barre de navigation native, Liquid Glass barre de tabs sur iOS, et un style de barre de tabs flou sur Android. Votre routeur Vue conserve l'état de la route ; le plugin gère la barre de chrome native.
- @capgo/capacitor-transitions — Les transitions de page Ionic-style et le balayage arrière sur iOS dans la couche WebView, sans adopter l'interface utilisateur Ionic.
Installez les deux :
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncConfigurez 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',
},
});Affichez une barre de tabs en verre liquide (iOS utilise la mise en page système ; Android utilise un arrière-plan WebView flou) :
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 les 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 lorsque la navigation native possède ces surfaces.
Voir les guides complets : En utilisant @capgo/capacitor-navigation-native et En utilisant @capgo/capacitor-transitions.
Aires sûres avec Tailwind
Pour les zones sûres de l'appareil dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor le npm). Il fournit safe-areas des utilitaires et d'autres plugins de Tailwind compatibles avec Capacitor:
bun add -D tailwind-capacitorEn 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-*) par manque de temps. Le projet est actuellement en développement — 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 scrollable horizontalement sur iOS, ajouter plus overflow-x: hidden ou ajuster seul le tag de vueport ne suffit généralement pas. Travaillez 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 une coquille d'application unique et appliquez-y une mise en page de zone de sécurité — 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 à l'intérieur .app-shell. Les marges de zone 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.
Avec @capgo/tailwind-capacitor, vous pouvez exprimer le même écartement avec des utilitaires comme pt-safe pb-safe px-safe sur cette seule coquille.
Définissez Capacitor iOS contentInset sur never premier
En capacitor.config.ts, préférez la zone de sécurité native désactivée et laissez CSS (ou la navigation native) s'occuper de la zone de sécurité : contentInsetMode: 'css'Mélanger les marges de zone de sécurité automatiques de __CAPGO_KEEP_0__ avec 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-*) padding est une cause courante de double espace.
Trouvez l'élément débordant réel
L'élément habituel est un élément utilisant 100vwTailwind w-screen, une largeur en 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-screenune mise en forme de zone de sécurité dupliquée, ou d'un conteneur à largeur fixe — pas 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.
Apprenez comment Capgo peut vous aider à créer des applications meilleures et plus rapides, s'inscrire à un compte gratuit aujourd'hui.
Continuez à partir de La création d'applications mobiles avec Vue et Capacitor
Si vous utilisez La création d'applications mobiles avec Vue et Capacitor pour planifier le comportement des médias et des interfaces natives, connectez-le avec En utilisant @capgo/capacitor-activités-en-ligne pour la capacité native dans En utilisant @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, En utilisant @capgo/capacitor-lecteur-de-videos For la capacité native dans l'utilisation de @capgo/capacitor-video-player, @capgo/capacitor-video-player Pour le détail d'implémentation dans @capgo/capacitor-video-player, et L'utilisation de @capgo/capacitor-native-navigation Pour la capacité native dans l'utilisation de @capgo/capacitor-native-navigation.
