Créer des applications mobiles avec Vue et Capacitor

In 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 de la navigation et des 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 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 répertoire dans le répertoire root de votre projet. Ce répertoire sera utilisé par Capacitor plus tard.

Intégration de Capacitor à votre application Vue

To convert your Vue web app into a conteneur mobile natif, suivez ces étapes :

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

2. Installez le package de base et les packages pertinents pour les plateformes iOS et Android.

3. 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 nouveaux iOS et context : Page/zone : Site de marketing Capgo. Rôle : Étiquette de navigation ou élément UI court. Vu dans : page trust.astro. Clé de message `et` (Et). android

dossiers dans votre projet Vue. capacitor.config.json __CAPGO_KEEP_0__.config.json répertoire web jusqu'au 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 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 d'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 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 native :

npx cap copy

Now, your app will automatically reload and show changes when you update your Vue app.

Utilisez les plugins Capacitor

Installez un plugin Capacitor comme le 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 commande et redéployez l'application sur votre appareil : sync Ensuite, vous pouvez rendre l'application plus native sur iOS et Android avec les transitions et les navigations __CAPGO_KEEP_0__ 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.

npx cap sync

UI native avec les transitions et les navigations Capgo

Native-feeling UI with Capgo Native Navigation and Transitions

Ionic pour construire des applications cross-plateformes, mais l'intégration avec Vue est hacky et rarement valable lorsque vous avez déjà to build cross-platform applications, but integrating it with Vue is hacky and rarely worth it when you already have 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-native-navigation — 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 — transitions de page Ionic-style et iOS swipe-back sur l'arrière de l'écran 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 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',
  },
});

Rendez une barre de tab Liquid Glass (iOS utilise la rendu système ; Android utilise un arrière-plan flou de 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 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-pageet cap-contentet appelez setDirection('forward') ou setDirection('back') Avant de naviguer. N'insérez pas les en-têtes ou les pieds de page web lorsqu'une navigation native contrôle ces surfaces.

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

Aires de sécurité avec Tailwind

Pour les zones de sécurité de l'appareil dans Tailwind CSS, utilisez @capgo/tailwind-capacitor (publié sous tailwind-capacitor sur 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, 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ésoudre les problèmes de mise en page iOS (Vue d'ensemble, zone de sécurité, et débordement horizontal)

Si le contenu semble être coupé, décalé ou scrollable horizontalement sur iOS, ajouter plus overflow-x: hidden ou ajuster la balise de vue d'ensemble seule ne suffit généralement pas pour résoudre le problème. Travaillez à travers ces vérifications dans l'ordre.

Assurez-vous que la balise meta de vue d'ensemble est appliquée correctement

Ajoutez la balise meta de vue d'ensemble dans index.html à l'intérieur <head>:

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

Gérer l'espace sûr iOS à partir d'un seul enveloppe racine

Créez une coquille d'application unique et appliquez-y la mise en forme de l'espace sûr là — 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);
}

Enveloppez tout le contenu de la page à l'intérieur .app-shell . La mise en forme de l'espace sûr dupliquée dans les en-têtes, les modales et les enveloppes de mise en page rend souvent l'interface utilisateur coupée ou trop grande.

Avec @capgo/tailwind-capacitorvous pouvez exprimer la même mise en forme avec des utilitaires comme pt-safe pb-safe px-safe sur cette coquille unique.

Fixez Capacitor iOS contentInset à never context : Page/zone : Page de produit de mise à jour en temps réel. Rôle : Étiquette de l'interface utilisateur courte ou élément de navigation. Clé de message `live_update_dynamic_label_to` (Étiquette dynamique de mise à jour en temps réel pour).

Dans capacitor.config.ts, préférez les éléments de mise en page natifs désactivés et laissez CSS (ou la navigation native) gérer l'espace sûr : contentInsetMode: 'css'Mélanger les __CAPGO_KEEP_0__ automatiques de mise en page avec des marges CSS est une cause courante de double espace.

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-*) Le coupable habituel est un élément utilisant

, Tailwind

, une largeur fixe en pixels, ou une large 100vwDans l'inspecteur Web de Safari, exécutez : w-screenAvec Tailwind, remplacez min-width.

par

[...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 w-screen par w-full lorsque cela est possible. Beaucoup d'issues de débordement horizontal proviennent de 100vw / w-screenla duplication de la marge de sécurité de l'espace sécurisé, ou d'un conteneur à largeur fixe — et non de la balise meta de la vue portée 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.

Apprenez 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 La création d'applications mobiles avec Vue et Capacitor pour planifier le comportement de la média et de l'interface native, connectez-l’avec En utilisant @capgo/capacitor-live-activities pour la capacité native dans l'utilisation de @capgo/capacitor-activités en direct, @capgo/capacitor-activités en direct pour le détail d'implémentation dans @capgo/capacitor-activités en direct, En utilisant @capgo/capacitor-joueur de vidéo pour la capacité native dans l'utilisation de @capgo/capacitor-joueur de vidéo, @capgo/capacitor-joueur de vidéo pour le détail d'implémentation dans @capgo/capacitor-joueur de vidéo, et En utilisant @capgo/capacitor-navigation native pour la capacité native dans l'utilisation de @capgo/capacitor-navigation native.