En este tutorial, te guiaré 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 navegación y transiciones nativas con Capgo 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 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 installPara preparar tu aplicación de Vue para el despliegue móvil nativo, necesitarás exportar tu proyecto. Agrega un script en tu 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í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 Vue
Para convertir tu aplicación web Vue en un contenedor móvil nativo, sigue estos pasos:
-
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.
-
Instala el paquete principal y los paquetes relevantes para las plataformas iOS y Android.
-
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 androidDeberías ver nuevas iOS y carpetas en tu proyecto Vue. Actualiza el
y Android capacitor.config.json archivo para apuntar a 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 syncDesarrollar y Desplegar Aplicaciones Nativas
Para desarrollar aplicaciones iOS, necesitas Xcode instalado, y para Android, necesitas Android Studio instalado. Además, debes inscribirte en el Apple Developer Program para iOS y en el Google Play Console 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 androidDespliega 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 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 copyAhora, 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/shareImporta el paquete y llama a la 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 syncEnseguida, 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 desbordamiento 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 Para construir aplicaciones de múltiples plataformas, pero integrarla con Vue es engorrosa y raramente vale la pena cuando ya tienes Para un sentir móvil nativo en una aplicación Vue + __CAPGO_KEEP_0__, utilice en su lugar plugins __CAPGO_KEEP_1__ en lugar de kits de interfaz de usuario web como Konsta UI: @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-navegación-nativa.
For a native mobile feel in a Vue + Capacitor app, use Capgo plugins instead of web-only UI kits like Konsta UI:
- @capgo/capacitor-transiciones — transiciones de página estilo Ionic y retroceso de arrastre en iOS en la capa de WebView, sin adoptar la interfaz de usuario de Ionic.
- @capgo/capacitor-transitions Configure la navegación nativa con el modo de inserción de CSS para que el contenido web respete las barras nativas:
Renderice una barra de pestañas de vidrio líquido (iOS utiliza la renderización propiedad del sistema; Android utiliza un fondo difuminado de WebView):
bun add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
bunx cap syncAgregue transiciones de página nativas en su capa de aplicación:
import { NativeNavigation } from '@capgo/capacitor-native-navigation';
await NativeNavigation.configure({
contentInsetMode: 'css',
animationDuration: 360,
glass: {
effect: 'liquidGlass',
},
});Para construir aplicaciones de múltiples plataformas, pero integrarla con Vue es engorrosa y raramente vale la pena cuando ya tienes Tailwind CSS.
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}`);
});Para un sentir móvil nativo en una aplicación Vue + __CAPGO_KEEP_0__, utilice en su lugar plugins __CAPGO_KEEP_1__ en lugar de kits de interfaz de usuario web como Konsta UI: Ionic, para construir aplicaciones de múltiples plataformas, pero integrarla con Vue es engorrosa y raramente vale la pena cuando ya tienes Tailwind CSS.
<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>Envuelve páginas de rutas en cap-router-outlet, cap-page, y cap-content, y llama setDirection('forward') o setDirection('back') antes de navegar. No duplique encabezados o pie de página web cuando la navegación nativa se encarga de 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). Ofrece safe-areas utilidades y otros plugins de Tailwind compatibles con Capacitor:
bun add -D tailwind-capacitorIn src/assets/main.css:
@import 'tailwindcss';
@plugin "@capgo/tailwind-capacitor/platform";
@plugin "@capgo/tailwind-capacitor/safe-areas";Utiliza 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 tu configuración de Vue, abre una solicitud de extracción en GitHub.
Corrección de problemas de diseño en 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. Pasa por estas comprobaciones en orden.
Asegúrese de que la etiqueta meta de viewport se aplique correctamente
Agregar la etiqueta meta de viewport en index.html dentro de <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Administrar el área seguro de iOS desde un solo wrapper 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 de .app-shellEl relleno de área segura 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-capacitorpuede expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en esa caja única.
Configurar Capacitor iOS contentInset Hasta never primero
En capacitor.config.ts, prefiere el diseño nativo deshabilitado y deja que CSS (o la navegación nativa) contentInsetMode: 'css') se encargue del área segura:
const config: CapacitorConfig = {
appId: 'com.example.myapp',
appName: 'my-app',
webDir: 'dist',
ios: {
contentInset: 'never',
},
};Mezclar el contenido automático de Capacitor con CSS env(safe-area-inset-*) es una causa común de espaciado doble.
Encuentra el elemento que está desbordando realmente
El culpable habitual es un elemento que utiliza 100vw, Tailwind w-screen, una anchura de píxeles fija o una gran 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,
}));With 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 etiqueta meta de viewport en sí.
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, conectarlo 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.
