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.
Über 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.
Vorbereitung Ihrer Vue-Anwendung
Zuerst erstellen Sie eine neue Vue-Anwendung, indem Sie den folgenden Befehl ausführen:
vue create my-app
cd my-app
npm installUm Ihre Vue-Anwendung für die native mobile Bereitstellung vorzubereiten, müssen Sie Ihr Projekt exportieren. Fügen Sie ein Skript in Ihrem package.json -Datei hinzu, um das Vue-Projekt zu bauen und zu kopieren:
{
"scripts": {
// ...
"build": "vue-cli-service build"
}
}Nachdem Sie den build Kommando, Sie sollten ein neues dist Ordner in Ihrem Projekts Wurzelverzeichnis sehen. Dieser Ordner wird später von Capacitor verwendet.
Capacitor zu Ihrem Vue-App hinzufügen
Um Ihre Vue-Web-App in einen nativen mobilen Container umzuwandeln, folgen Sie diesen Schritten:
-
Installieren Sie das Capacitor CLI als Entwicklungsabhängigkeit und konfigurieren Sie es innerhalb Ihres Projekts. Akzeptieren Sie die Standardwerte für Namen und Bundle-ID während der Konfiguration.
-
Installieren Sie das Kernpaket und die relevanten Pakete für die iOS- und Android-Plattformen.
-
Fügen Sie die Plattformen hinzu, und Capacitor erstellt Ordner für jede Plattform in der Wurzel Ihres Projekts:
# 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 androidSie sollten nun neue iOS und Android Ordner in Ihrem Vue-Projekt sehen.
Update das capacitor.config.json Datei, um den webDir zum Ergebnis Ihrer Build-Kommando:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}Jetzt kannst du dein Vue-Projekt erstellen und es mit Capacitor synchronisieren.
npm run build
npx cap syncErstellen und Bereitstellen von nativen Apps
To develop iOS apps, you need Xcode installed, and for Android apps, you need Android Studio installed. Additionally, you need to enroll in the Apple Developer Program for iOS and the Google Play Console for Android to distribute your app on the app store.
Öffnen Sie die Capacitor CLI für beide nativen Projekte:
npx cap open ios
npx cap open androidDeployen Sie Ihre App auf einem verbundenen Gerät mithilfe von Android Studio oder Xcode.
Capacitor Live Reload
Aktivieren Sie die Live-Neustartfunktion auf Ihrem Mobilgerät, indem die Capacitor-App den Inhalt von einer bestimmten URL auf Ihrem Netzwerk lädt.
Finden Sie Ihre lokale IP-Adresse und aktualisieren Sie das capacitor.config.ts Datei mit der richtigen IP-Adresse und Port:
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;Anwenden Sie diese Änderungen, indem Sie sie in Ihr natives Projekt kopieren:
npx cap copyJetzt wird Ihre App automatisch neu geladen und zeigt Änderungen an, wenn Sie Ihre Vue-App aktualisieren.
Mit Capacitor-Plugins
Installieren Sie ein Capacitor-Plugin, wie z.B. das Share-Plugin, und verwenden Sie es in Ihrer Vue-App:
npm i @capacitor/shareImportieren Sie das Paket und rufen Sie die share() Funktion in Ihrer App auf:
<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>Nach dem Installieren neuer Plugins führen Sie den sync Befehl aus und deployen Sie die App erneut auf Ihr Gerät:
npx cap syncAls Nächstes können Sie die App auf iOS und Android mit Capgo-Navigation und Übergängen noch nativer machen und häufige iOS-Anzeigefehler beheben, die zu horizontaler Überlauf oder gekürzten sicheren Bereichen führen.
Natürliche Benutzeroberfläche mit Capgo-Native Navigation und Übergängen
Ich habe Jahre lang mit Ionic zum Aufbau von Plattformanwendungen gearbeitet, aber die Integration mit Vue ist hackig und selten wertvoll, wenn Sie bereits Tailwind CSS haben Tailwind CSS.
Für einen nativen mobilen Look in einer Vue + Capacitor App verwenden Sie Capgo-Plugins anstatt web-basierter UI-Kits wie Konsta UI.
- @capgo/capacitor-native-Navigation — native navbar, Liquid Glass tab bar on iOS, and a blurred tab bar style on Android. Your Vue router keeps route state; the plugin owns the native chrome.
- @capgo/capacitor-Übergänge — Seitenübergänge im Ionic-Stil und iOS-Rück-Flutschwung in der WebView-Schicht, ohne Ionic-UI zu übernehmen.
Install beide:
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncKonfigurieren Sie die native Navigation mit CSS-Inset-Modus, damit Webinhalte die nativen Balken respektieren:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Ein Liquid Glass-Tasteleisten-Element rendern (iOS verwendet die Systemeigene Rendering; Android verwendet ein verschwommenes WebView-Hintergrundbild):
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}`);
});Fügen Sie native Seitenübergänge in Ihrem App-Shell hinzu:
<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>Verwenden Sie Routen für Seiten: cap-router-outlet, cap-page, und cap-content, und rufen Sie setDirection('forward') oder setDirection('back') Bevor Sie navigieren, verwenden Sie nicht die Web-Überschriften oder -Fußzeilen, wenn native Navigation diese Oberflächen besitzt.
Siehe die vollständigen Anleitungen: Verwenden Sie @capgo/capacitor-native-Navigation und Verwenden Sie @capgo/capacitor-Übergänge.
Sichere Bereiche mit Tailwind
Für Gerätesichere Bereiche in Tailwind CSS verwenden Sie @capgo/tailwind-capacitor (veröffentlicht als) tailwind-capacitor auf npm). Es bietet safe-areas Nützlichkeiten und andere Capacitor-freundliche Tailwind-Plugins:
bun add -D tailwind-capacitorIn src/assets/main.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Verwenden Sie Nützlichkeiten wie pt-safe, pb-safe, und px-safe anstatt von zu streuen env(safe-area-inset-*) manuell zu verteilen. Das Projekt wird aktiv weiterentwickelt — wenn etwas für Ihre Vue-Einrichtung fehlt, erstellen Sie einen PR auf GitHub.
Fixing iOS Layout Issues (Viewport, Safe Area, und Horizontal Overflow)
Wenn Inhalte gekürzt, verschoben oder horizontal scrollbar auf iOS aussehen, fügen Sie mehr overflow-x: hidden oder das Anpassen der Viewport-Tags allein reicht normalerweise nicht aus. Arbeiten Sie durch diese Überprüfungen in der Reihenfolge.
Stellen Sie sicher, dass die Viewport-Metatag korrekt angewendet wird
Fügen Sie den Viewport-Metatag in index.html innerhalb <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Verwenden Sie die iOS-Sicherheitszone nur von einem Root-Wrapper aus.
Erstellen Sie ein einzelnes App-Shell und fügen Sie dort Sicherheitsbereichs-Abstände an — nicht in mehreren verschachtelten Komponenten:
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);
}Verwenden Sie alle Seite-Inhalte innerhalb .app-shell. Doppelte Sicherheitsbereichs-Abstände in Kopfzeilen, Modalen und Layout-Wrapper können die Benutzeroberfläche gekürzt oder zu groß aussehen lassen.
Mit @capgo/tailwind-capacitorkönnen Sie denselben Abstand mit Hilfsfunktionen wie pt-safe pb-safe px-safe auf diesem einzelnen Shell ausdrücken.
Setze Capacitor iOS contentInset auf never erst
In capacitor.config.ts, bevor du native Einstellungen deaktivierst und CSS (oder Native Navigation’s) contentInsetMode: 'css') die sichere Fläche übernimmt:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mische Capacitor’s automatische Inhaltseinstellung mit CSS env(safe-area-inset-*) Padding ist eine häufige Ursache für doppelte Abstände.
Finde das überlaufende Element
Der übliche Täter ist ein Element, das 100vw, Tailwind w-screen, eine feste Pixelbreite oder eine große min-width.
In Safari Web Inspector, führen Sie Folgendes aus:
[...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,
}));Mit Tailwind ersetzen Sie w-screen mit w-full wenn möglich. Viele horizontale Überlaufprobleme kommen von 100vw / w-screen, duplizierter sicheren Bereich-Padding oder einem fester Breiten-Container — nicht von der Viewport-Meta-Tags selbst.
Zusammenfassung
Capacitor ist eine großartige Option für die Erstellung von nativen Anwendungen auf der Basis eines bestehenden Web-Projekts. Mit der Hinzufügung von Capgo ist es sogar einfacher, Live-Updates in Ihrer App hinzuzufügen, sodass Ihre Benutzer immer Zugriff auf die neuesten Funktionen und Fehlerbehebungen haben.
Learn how Capgo can help you build better apps faster, Registrieren Sie sich für ein kostenloses Konto heute.
Fortsetzen Sie mit der Erstellung von mobilen Apps mit Vue und Capacitor
Wenn Sie Capgo verwenden Mit Vue Mobile Apps erstellen und Capacitor um native Medien und Schnittstellenverhalten zu planen, verbinden Sie es mit Mit @capgo/capacitor-live-Aktivitäten zur Verwendung der nativen Fähigkeit in Mit @capgo/capacitor-live-Aktivitäten, Mit @capgo/capacitor-live-Aktivitäten zur Implementierungsdetail in @capgo/capacitor-live-Aktivitäten, Mit @capgo/capacitor-Video-Player zur Verwendung der nativen Fähigkeit in Mit @capgo/capacitor-Video-Player, Mit @capgo/capacitor-Video-Player zur Implementierungsdetail in @capgo/capacitor-Video-Player, und Mit @capgo/capacitor-native-Navigation zur Verwendung der nativen Fähigkeit in Mit @capgo/capacitor-native-Navigation.
