Crear aplicaciones móviles con Vue y Capacitor

In este tutorial, le guiarémos a través del proceso de convertir una aplicación web de Vue en una aplicación móvil nativa utilizando Capacitor. También puede agregar Capgo de navegación nativa y transiciones para un sentir móvil nativo, y utilizar tailwind-capacitor para áreas seguras.

Sobre Capacitor

Capacitor es una herramienta revolucionaria que le permite integrar fácilmente en cualquier proyecto web y convertir su aplicación en una aplicación móvil nativa. Genera proyectos Xcode y Android Studio nativos para usted y proporciona acceso a características de dispositivos nativos como la cámara a través de un puente de JavaScript.

Preparando su aplicación de Vue

Primero, cree una nueva aplicación de Vue ejecutando el siguiente comando:

vue create my-app
cd my-app
npm install

Para preparar su aplicación de Vue para la implementación móvil nativa, necesitará exportar su proyecto. Agregue un script en su archivo package.json para construir y copiar el proyecto de Vue:

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

Después de ejecutar el build comando, debería ver un nuevo dist carpeta en el directorio raíz de su proyecto. Esta carpeta se utilizará por Capacitor más tarde.

Agregando Capacitor a su aplicación de Vue

To convertir tu aplicación web de Vue en un contenedor móvil nativo, sigue estos pasos:

1. Instala el Capacitor CLI como dependencia de desarrollo y configúralo dentro de tu proyecto. Acepta los valores predeterminados para el nombre y el ID de paquete durante la configuración.

2. Instala el paquete principal y los paquetes relevantes para las plataformas iOS y Android.

3. Agrega las plataformas, y Capacitor creará carpetas para cada plataforma en la raíz de tu proyecto:

# 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

Tienes que ver ahora nuevos iOS y android carpetas en tu proyecto de Vue.

Actualiza el archivo capacitor.config.json para que apunte a webDir para el resultado de tu comando de compilación:

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

Ahora, puedes compilar tu proyecto de Vue y sincronizarlo con Capacitor:

npm run build
npx cap sync

Desarrollar y Desplegar Aplicaciones Nativas

Para desarrollar aplicaciones iOS, necesitas Xcode instalado, y para Android, necesitas Android Studio instalado. Además, debes inscribirte en el Programa de Desarrolladores de Apple para iOS y en el Console de Google Play para Android para distribuir tu aplicación en la tienda de aplicaciones.

Utiliza los Capacitor CLI para abrir ambos proyectos nativos:

npx cap open ios
npx cap open android

Despliega tu aplicación en un dispositivo conectado utilizando Android Studio o Xcode.

Capacitor Live Reload

Activa la recarga en vivo en tu dispositivo móvil teniendo la aplicación Capacitor cargar el contenido desde una URL específica en tu red.

Encuentra tu dirección IP local y actualiza el capacitor.config.ts archivo con la IP y puerto correctos:

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;

Aplica estos cambios copiándolos a tu proyecto nativo:

npx cap copy

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

Usando plugins Capacitor

Instale un plugin Capacitor, como el plugin de compartir, y utilícelo en su aplicación Vue:

npm i @capacitor/share

Importe el paquete y llame a la share() función en su aplicación:

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

Después de instalar nuevos plugins, ejecute el sync comando y vuelva a desplegar la aplicación en su dispositivo:

npx cap sync

En el siguiente paso, puede hacer que la aplicación se sienta más nativa en iOS y Android con la navegación y las transiciones Capgo, y solucione problemas de diseño comunes de iOS que causan desbordamiento horizontal o áreas de seguridad recortadas.

Interfaz de usuario que se siente nativa con navegación y transiciones Capgo nativas

He trabajado durante años con Ionic para construir aplicaciones de múltiples plataformas, pero integrarla con Vue es engorrosa y raramente vale la pena cuando ya tiene Tailwind CSS.

Para un sentir móvil nativo en una aplicación Vue + Capacitor utilice plugins Capgo en lugar de kits UI web solo como Konsta UI:

• @capgo/capacitor-navegación-nativa — barra de navegación nativa, Liquid Glass barra de pestañas en iOS, y un estilo de barra de pestañas difuminada en Android. Su router Vue mantiene el estado de ruta; el plugin posee el navegador nativo.
• @capgo/capacitor-transiciones — transiciones de página estilo Ionic y retroceso por arrastre en la capa WebView en iOS, sin adoptar UI Ionic.

Instale ambos:

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

Configure la navegación nativa con el modo de inserción de CSS para que el contenido web respete las barras nativas:

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

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

Renderice una barra de pestañas de vidrio líquido (iOS utiliza la renderización propia del sistema; Android utiliza un fondo difuminado de la capa 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}`);
});

Agregue transiciones de página nativas en su concha de aplicación:

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

Envuelva páginas de ruta en cap-router-outlet, cap-page, y cap-contenty llamar setDirection('forward') o setDirection('back') antes de navegar. No duplique encabezados o pie de página web cuando la navegación nativa controla esas superficies.

Consulte las guías completas: Usando @capgo/capacitor-navegación-nativa y Usando @capgo/capacitor-transiciones.

Áreas seguras con Tailwind

Para áreas seguras de dispositivos en Tailwind CSS, utilice @capgo/tailwind-capacitor (publicado como tailwind-capacitor en npm). Proporciona safe-areas utilidades y otros plugins de Tailwind compatibles 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";

Utilice utilidades como pt-safe, pb-safe, y px-safe en lugar de agregarlas env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para su configuración de Vue, abre una solicitud de extracción en GitHub.

Solucionar problemas de diseño de iOS (Viewport, Área Segura y Desbordamiento Horizontal)

Si el contenido parece recortado, desplazado o desplazable horizontalmente en iOS, agregar más overflow-x: hidden o ajustar la etiqueta de viewport sola no suele solucionar el problema. Pase por estos controles en orden.

Asegúrese de que la etiqueta meta de viewport se aplique correctamente

Agregue la etiqueta meta de viewport en index.html inside <head>:

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

Administre el área segura de iOS desde un solo envoltorio raíz

Cree un concha de aplicación única y aplique allí el relleno de área segura, no en múltiples componentes anidados:

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

Envuelva todo el contenido de la página .app-shell. El relleno de área segura duplicado en encabezados, modales y envoltorios de diseño a menudo hace que la IU se vea recortada o demasiado grande.

Con @capgo/tailwind-capacitor, puede expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa concha única.

Establezca Capacitor iOS contentInset a never primero

Inicia capacitor.config.ts, prefiera el área de inserción nativa deshabilitada y deja que CSS (o la navegación nativa) se encargue del área segura: contentInsetMode: 'css'Mezclar el área de contenido automática de __CAPGO_KEEP_0__ con CSS de relleno es una causa común de espaciado doble.

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-*) El culpable habitual es un elemento que utiliza

, Tailwind

, una anchura de píxeles fija o muy grande 100vwEn Safari Web Inspector, ejecuta: w-screenCon Tailwind, reemplaza min-width.

con

[...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, reemplaza w-screen con w-full cuando sea posible. Muchos problemas de rebosamiento horizontal provienen de 100vw / w-screen, relleno de área segura duplicado, o un contenedor de ancho fijo — no del meta de viewport en sí mismo.

Conclusión

Capacitor es una gran opción para crear aplicaciones nativas basadas en un proyecto web existente. Con la adición de Capgo, es aún más fácil agregar actualizaciones en vivo a tu aplicación, asegurando que tus usuarios siempre tengan acceso a las últimas características y correcciones de errores.

Aprende cómo Capgo puede ayudarte a crear aplicaciones mejoradas más rápido, regístrate para una cuenta gratuita hoy.

Sigue adelante desde Construyendo Aplicaciones Móviles con Vue y Capacitor

Si estás utilizando Construyendo Aplicaciones Móviles con Vue y Capacitor para planificar el comportamiento de medios y interfaz nativa, conecta con Usando @capgo/capacitor-live-activities para la capacidad nativa en Usando @capgo/capacitor-actividades-en-vivo, @capgo/capacitor-actividades-en-vivo para el detalle de implementación en @capgo/capacitor-actividades-en-vivo, Usando @capgo/capacitor-reproductor-de-videos para la capacidad nativa en Usando @capgo/capacitor-reproductor-de-videos, @capgo/capacitor-reproductor-de-videos para el detalle de implementación en @capgo/capacitor-reproductor-de-videos, y Usando @capgo/capacitor-navegación-nativa para la capacidad nativa en Usando @capgo/capacitor-navegación-nativa.