Desarrollar Aplicaciones Móviles con Vue y Capacitor

En este tutorial, te guiaremos 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 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 te permite integrar fácilmente en cualquier proyecto web y convertir tu aplicación en una aplicación móvil nativa. Genera proyectos Xcode y Android Studio nativos 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 su aplicación Vue

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

vue create my-app
cd my-app
npm install

Para preparar tu aplicación Vue para la implementación móvil nativa, necesitarás exportar tu proyecto. Agrega un script en tu archivo package.json El archivo

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

package.json build Después de ejecutar el dist folder in your project’s root directory. This folder will be used by Capacitor later.

Adding Capacitor to Your Vue App

Capgo

1. Install the Capacitor CLI as a development dependency and set it up within your project. Accept the default values for name and bundle ID during the setup.

2. Capacitor

3. Add the platforms, and Capacitor will create folders for each platform at the root of your project:

# 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

Ahora deberías ver nuevos iOS y Android carpetas en tu proyecto Vue.

Actualiza el archivo capacitor.config.json para apuntar a la salida de tu comando de compilación: Ahora, puedes compilar tu proyecto Vue y sincronizarlo con __CAPGO_KEEP_0__: Construye y Despliega Aplicaciones Nativas

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

Now, you can build your Vue project and sync it with Capacitor:

npm run build
npx cap sync

Build and Deploy Native Apps

To desarrollar aplicaciones iOS, necesitas tener instalado Xcode, y para aplicaciones Android, necesitas tener instalado Android Studio. 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

Habilita el 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 dirección IP y el 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

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

Usando Capacitor Plugins

Instala un plugin Capacitor, como el plugin de Compartir, y úsalo en tu aplicación Vue:

npm i @capacitor/share

Importa el paquete y llama al share() función en tu 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, ejecuta el sync comando y vuelve a desplegar la aplicación en tu dispositivo:

npx cap sync

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

Interfaz de usuario que se siente nativa con Capgo Navegación y Transiciones Nativas

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

Para un sentir móvil nativo en una aplicación Vue + Capacitor, utilice plugins de Capgo en lugar de kits de interfaz de usuario web solo 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 con estilo de Ionic y retroceso por swipe 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 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 propiedad del sistema; Android utiliza un fondo de fondo de WebView difuminado):

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 capa de concha:

<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 pie 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 del dispositivo en Tailwind CSS, utilice @capgo/tailwind-capacitor (publicado como) tailwind-capacitor en npm. safe-areas Proporciona utilidades y otros plugins de Tailwind amigables 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 esparcir env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para tu configuración de Vue, abre una PR en GitHub.

Corrección de 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 usualmente no lo resuelve. Trabaja a través de estas comprobaciones en orden.

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

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

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

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

Crear un núcleo de aplicación único 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);
}

Envuelve todo el contenido de la página dentro de .app-shell. El relleno de área de seguridad duplicado en encabezados, modales y wrappers 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 capa.

Establece Capacitor iOS contentInset a never primero

En capacitor.config.ts, prefiere el relleno de área de seguridad deshabilitado nativo y deja que CSS (o la navegación nativa) contentInsetMode: 'css') tenga el área de seguridad:

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

Mezclar Capacitor's contenido de área de seguridad automático con CSS env(safe-area-inset-*) El relleno es una causa común de doble espaciado.

Encuentra el elemento que está causando el desbordamiento real.

El culpable habitual es un elemento que utiliza 100vw, Tailwind w-screen, un ancho de píxel fijo, o un contenedor muy ancho — min-width.

En Safari Web Inspector, ejecuta:

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

Conclusión

Capacitor es una excelente 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.

Continúa 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-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-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.