Desarrollar Aplicaciones Móviles con Vue y Capacitor

En este tutorial, te guiamos a través del proceso de convertir una aplicación web de Vue en una aplicación móvil nativa utilizando Capacitor. También puedes agregar Capgo 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 te permite integrar fácilmente en cualquier proyecto web y convertir tu aplicación en una aplicación móvil nativa. Genera proyectos nativos de Xcode y Android Studio para ti y te proporciona acceso a características de dispositivos nativos como la cámara a través de un puente de JavaScript.

Preparando Tu Aplicación de Vue

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

vue create my-app
cd my-app
npm install

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

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

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

Agregar Capacitor a Tu Aplicación de Vue

Para 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 básico 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

Deberías ver ahora nuevos iOS y android carpetas en tu proyecto Vue.

Actualiza el capacitor.config.json archivo para apuntar el webDir a la resultante de tu comando de compilación:

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

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

npm run build
npx cap sync

Construye y Despliega Aplicaciones Nativas

Para desarrollar aplicaciones iOS, necesitas Xcode instalado, y para aplicaciones 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 el Capacitor CLI para abrir ambos proyectos nativos:

npx cap open ios
npx cap open android

Despliegue su aplicación en un dispositivo conectado utilizando Android Studio o Xcode.

Capacitor Live Reload

Habilite el recarga en vivo en su dispositivo móvil teniendo la aplicación Capacitor cargando el contenido desde una URL específica en su red.

Encuentre su dirección IP local y actualice el archivo con la dirección IP y puerto correctos: capacitor.config.ts Aplicar estos cambios copiándolos a su proyecto nativo:

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;

Ahora, su aplicación se recargará automáticamente y mostrará cambios cuando actualice su aplicación Vue.

npx cap copy

Usando __CAPGO_KEEP_0__ Plugins

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

Install a Capacitor plugin, such as the Share plugin, and use it in your Vue app:

npm i @capacitor/share

función en su aplicación: share() Después de instalar nuevos plugins, ejecute el

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

Ahora, su aplicación se recargará automáticamente y mostrará cambios cuando actualice su aplicación Vue. sync comando y reemplaza la aplicación en tu dispositivo:

npx cap sync

Enseguida, puedes hacer que la aplicación se sienta más nativa en iOS y Android con Capgo navegación y transiciones, y solucionar problemas de diseño comunes de iOS que causan rebosamiento horizontal o áreas de seguridad recortadas.

Interfaz de usuario con un sentimiento nativo con Capgo Navegación y Transiciones Nativas

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

Para un sentimiento móvil nativo en una aplicación Vue + Capacitor, utilice en su lugar Capgo plugins en lugar de kits de interfaz de usuario solo para web como Konsta UI:

• @capgo/capacitor-navegación-nativa — barra de navegación nativa, barra de pestañas de vidrio líquido en iOS, y un estilo de barra de pestañas difuminado en Android. Su router de Vue mantiene el estado de la ruta; el plugin posee el navegador nativo.
• @capgo/capacitor-transiciones — transiciones de página estilo Ionic y retroceso de arrastre de iOS en la capa de WebView, sin adoptar la interfaz de usuario de 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 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',
  },
});

Vincule una barra de pestañas de vidrio líquido (iOS utiliza la renderización propiedad del sistema; Android utiliza un fondo de vista de web desenfocado):

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 la caja de su 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 las páginas de ruteo en cap-router-outlet, cap-page, y cap-content, y llame a setDirection('forward') o setDirection('back') antes de navegar. No duplique los encabezados o pies de página web cuando la navegación nativa posee 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 amigables con Capacitor:

bun add -D tailwind-capacitor

En 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 esparcir env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para su configuración de Vue, abrir una PR en GitHub.

Resolviendo 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. Trabaja a través de estas comprobaciones en orden.

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

Agregar la etiqueta meta de viewport en index.html dentro <head>:

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

Gestionar el área segura de iOS desde un solo contenedor raíz

Crear una caja de aplicación única y aplicar 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);
}

Envolver todo el contenido de la página dentro .app-shellEl relleno de área segura duplicado en encabezados, modales y contenedores de diseño a menudo hace que la interfaz de usuario parezca recortada o demasiado grande.

Con @capgo/tailwind-capacitor, puedes expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa sola consola.

Establece Capacitor en iOS contentInset a never primero

En capacitor.config.ts, prefiere el relleno nativo deshabilitado y deja que CSS (o la navegación nativa) se encargue del área segura: contentInsetMode: 'css'Mezclar __CAPGO_KEEP_0__’s contenido automático con 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-*) Encuentra el elemento que realmente está desbordando

Encuentra el elemento que realmente está desbordando.

The usual culprit is an element using 100vw, Tailwind w-screen, un ancho de píxeles fijo, o un gran min-width.

In Safari Web Inspector, run:

[...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, duplicado relleno de área segura, o un contenedor de ancho fijo — no del meta etiqueta de viewport en sí.

Conclusion

Capacitor es una gran opción para construir aplicaciones nativas basadas en un proyecto web existente. Con la adición de Capgo, es incluso 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 construir 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 interfaces nativas, conecta con Usando @capgo/capacitor-actividades-en-vivo 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-video para la capacidad nativa en Usando @capgo/capacitor-reproductor-de-video, @capgo/capacitor-reproductor-de-video para los detalles 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.