Creare App Mobili con Vue e Capacitor

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.

Su Capacitor

Capacitor è uno strumento rivoluzionario che consente di integrare facilmente in qualsiasi progetto web e convertire l'applicazione in un'app mobile nativa. Genera progetti Xcode e Android Studio nativi per te e fornisce accesso alle funzionalità del dispositivo nativo come la fotocamera attraverso un ponte JavaScript.

Preparazione dell'app Vue

Prima, crea una nuova app Vue eseguendo il seguente comando:

vue create my-app
cd my-app
npm install

Per preparare la tua app Vue per la distribuzione nativa mobile, avrai bisogno di esportare il tuo progetto. Aggiungi uno script nel tuo file package.json per costruire e copiare il progetto Vue:

{
  "scripts": {
    // ...
    "build": "vue-cli-service build"
  }
}

Dopo l'esecuzione del build comando, dovresti vedere un nuovo dist cartella nella directory radice del tuo progetto. Questa cartella verrà utilizzata da Capacitor in seguito.

Aggiungere Capacitor alla tua app Vue

Per convertire la tua app web Vue in un contenitore mobile nativo, segui questi passaggi:

1. Installa il Capacitor CLI come dipendenza di sviluppo e configuralo all'interno del tuo progetto. Accetta i valori predefiniti per nome e ID bundle durante la configurazione.

2. Installa il pacchetto di base e i pacchetti pertinenti per le piattaforme iOS e Android.

3. Aggiungi le piattaforme e Capacitor creerà cartelle per ogni piattaforma nella directory radice del tuo progetto:

# 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

Ora dovresti vedere nuovi cartelle per iOS e Android nel tuo progetto Vue. iOS e Android Le cartelle sono state aggiunte al tuo progetto Vue.

Aggiorna il file __CAPGO_KEEP_0__.config.json per puntare la proprietà webDir al risultato del comando di build: Ora puoi costruire il tuo progetto Vue e sincronizzarlo con capacitor: Costruisci e distribuisci applicazioni native webDir __CAPGO_KEEP_0__

{
  "appId": "com.example.app",
  "appName": "my-app",
  "webDir": "dist"
}

Capacitor

npm run build
npx cap sync

__CAPGO_KEEP_0__

Per sviluppare app iOS, avrai bisogno di Xcode installato, e per app Android, avrai bisogno di Android Studio installato. Inoltre, avrai bisogno di iscriverti al Apple Developer Program per iOS e al Google Play Console per Android per distribuire la tua app sul negozio di app.

Usa i Capacitor CLI per aprire entrambi i progetti nativi:

npx cap open ios
npx cap open android

Distribuisci la tua app su un dispositivo connesso utilizzando Android Studio o Xcode.

Capacitor Live Reload

Abilita il live reload sul tuo dispositivo mobile avendo l'app Capacitor caricare il contenuto da una specifica URL del tuo network.

Trova l'indirizzo IP locale e aggiorna il capacitor.config.ts file con l'indirizzo IP e il port corretti:

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;

Applica queste modifiche copiando le modifiche sul tuo progetto nativo:

npx cap copy

Ora, la tua app si ricaricherà automaticamente e mostrerà le modifiche quando aggiorni la tua app Vue.

Utilizzando Capacitor Plugins

Installa un Capacitor plugin, come il plugin di condivisione, e utilizzalo nella tua app Vue:

npm i @capacitor/share

Importa il pacchetto e chiama il share() funzione nella tua app:

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

Dopo aver installato nuovi plugin, esegui il sync comando e ripubblica l'app sul tuo dispositivo:

npx cap sync

Successivamente, puoi rendere l'app più nativa su iOS e Android con Capgo navigazione e transizioni, e risolvere problemi di layout iOS comuni che causano overflow orizzontale o aree sicure tagliate.

Interfaccia utente con un aspetto nativo con Capgo Navigazione e Transizioni native

Ho lavorato per anni con Ionic per costruire applicazioni cross-platform, ma integrarla con Vue è un processo complicato e raramente vale la pena quando già disponi di Tailwind CSS.

Per un aspetto mobile nativo in un'app Vue + Capacitor utilizza invece i plugin Capgo al posto di kit UI web come Konsta UI:

• @capgo/capacitor-navigazione-nativa — barra di navigazione nativa, Liquid Glass bar delle schede su iOS, e uno stile di barra delle schede sfocato su Android. Il tuo router Vue mantiene lo stato delle rotte; il plugin gestisce il chrome nativo.
• @capgo/capacitor-transizioni — Transizioni di pagina stile Ionic e swipe-back di iOS nell' layer WebView, senza adottare l'interfaccia utente di Ionic.

Installa entrambi:

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

Configura la navigazione nativa con il modello CSS inset per far rispettare il contenuto web le barre native:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  glass: {
    effect: 'liquidGlass',
  },
});

Rendi una barra di tab di vetro liquido (iOS utilizza la rendering di proprietà del sistema; Android utilizza un sfondo WebView sfocato):

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

Aggiungi transizioni di pagina native nel contenitore della tua app:

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

Avvolgi le pagine di routing in cap-router-outlet, cap-page, e cap-content, e chiama setDirection('forward') o setDirection('back') prima di navigare.

Non duplicare i titoli o i piedi di pagina web quando la navigazione nativa possiede quelle superfici. Usando @capgo/capacitor-navigazione nativa e Usando @capgo/capacitor-transizioni.

Aree sicure con Tailwind

Per aree sicure del dispositivo in Tailwind CSS, utilizzare @capgo/tailwind-capacitor (pubblicato come tailwind-capacitor su npm). Fornisce safe-areas utilità e altri plugin di Tailwind amichevoli con Capacitor:

bun add -D tailwind-capacitor

In src/assets/main.css:

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

Utilizzare utilità come pt-safe, pb-safe, e px-safe invece di spargere env(safe-area-inset-*) a mano. Il progetto è attivamente sviluppato — se qualcosa manca per la tua configurazione Vue, apri un PR su GitHub.

Risolvere Problemi di Layout iOS (Viewport, Area di Sicurezza e Flusso Orizzontale)

Se il contenuto sembra essere tagliato, spostato o scorrevole orizzontalmente su iOS, aggiungere più overflow-x: hidden o regolare il tag viewport da solo non risolve di solito il problema. Lavora attraverso questi controlli in ordine.

Assicurati che il tag meta viewport sia applicato correttamente

Aggiungi il tag meta viewport in index.html all'interno <head>:

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

Gestisci l'area di sicurezza di iOS da un solo wrapper radice

Crea un unico contenitore dell'applicazione e applica il padding dell'area di sicurezza lì — non in componenti nidificati multipli:

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

Avvolgi tutto il contenuto della pagina all'interno .app-shell. Il sovrapposto padding di sicurezza dell'area protetta nei capisaldi, nelle finestre modal e nei wrapper di layout può spesso rendere l'interfaccia utente appiattita o troppo grande.

Con @capgo/tailwind-capacitor, puoi esprimere lo stesso padding con utilità come pt-safe pb-safe px-safe su quel singolo shell.

Imposta Capacitor iOS contentInset a never primo

In capacitor.config.ts, preferisci l'inserimento nativo disabilitato e lascia che il CSS (o la navigazione nativa ' contentInsetMode: 'css'') gestisca l'area protetta:

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

Il mixaggio di Capacitor’s automatico contenuto insetto con CSS env(safe-area-inset-*) la spaziatura è una causa comune di doppia spaziatura.

Trova l'elemento che sta effettivamente sovrascrivendo

Il solito colpevole è un elemento che utilizza 100vw, Tailwind w-screen, una larghezza in pixel fissata, o un grande min-width.

In Safari Web Inspector, esegui:

[...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,
  }));

Con Tailwind, sostituisci w-screen con w-full quando possibile. Molti problemi di sovrascrittura orizzontale derivano da 100vw / w-screen, padding di area sicura duplicato, o un contenitore di larghezza fissata — non dal tag meta viewport stesso.

Conclusioni

Capacitor è una grande opzione per creare applicazioni native basate su un progetto web esistente. Con l'aggiunta di Capgo, è ancora più facile aggiungere aggiornamenti in tempo reale all'applicazione, assicurando che i tuoi utenti abbiano sempre accesso alle ultime funzionalità e correzioni di bug.

Impara come Capgo può aiutarti a costruire applicazioni migliori in modo più veloce, iscrivi un account gratuito oggi.

Continua a lavorare da Building Mobile Apps con Vue e Capacitor

Se stai utilizzando Building Mobile Apps con Vue e Capacitor per pianificare il comportamento di media e interfaccia nativa, connettilo con Usando @capgo/capacitor-attività-in-vivo per la capacità nativa in Usando @capgo/capacitor-attività-in-vivo, @capgo/capacitor-attività-in-vivo per il dettaglio di implementazione in @capgo/capacitor-attività-in-vivo, Usando @capgo/capacitor-lettore-di-video per la capacità nativa in Utilizzo di @capgo/capacitor-video-player, @capgo/capacitor-video-player per il dettaglio di implementazione in @capgo/capacitor-video-player, e Utilizzo di @capgo/capacitor-native-navigation per la capacità nativa in Utilizzo di @capgo/capacitor-native-navigation.