En este tutorial, comenzaremos creando una nueva aplicación web utilizando Quasar. Posteriormente, aprenderemos a convertirla en una aplicación móvil utilizando Capacitor. Si deseas que tu aplicación se vea mejor en móvil.
Con Capacitor, puedes cambiar tu aplicación web de Quasar en una aplicación móvil sin necesitar hacer muchas cosas difíciles o aprender un nuevo método de creación de aplicaciones como lo harías con algo llamado React Native.
Este tutorial te guiará a través del proceso, comenzando con una nueva aplicación de Quasar y luego incorporando Capacitor para moverte al reino de aplicaciones móviles nativas. Además, utilizarás Capgo para enviar live update a tu aplicación en segundos
Sobre Capacitor
CapacitorJS es verdaderamente un cambio de juego. Puedes incorporarlo fácilmente en cualquier proyecto web, y lo envolverá en una vista web nativa, generando el proyecto Xcode y Android Studio nativo para ti. Además, sus plugins proporcionan acceso a características de dispositivos nativos como la cámara a través de un puente JS.
Con Capacitor, obtienes una aplicación móvil nativa fantástica sin ninguna configuración complicada o curva de aprendizaje empinada. Su delgado API y funcionalidad simplificada lo hacen un placer integrarlo en tu proyecto. Confía en mí, te sorprenderá la facilidad con la que puedes lograr una aplicación nativa funcional completa con Capacitor.
Preparando tu aplicación Quasar
Para crear una nueva aplicación Quasar, ejecuta el siguiente comando:
npm init quasar
Elige la opción "Aplicación con Quasar CLI" luego "Quasar v2".
Para crear una aplicación móvil nativa, necesitamos un export de nuestro proyecto. Por lo tanto, incluyamos un script directo en nuestro package.json que se puede utilizar para construir y copiar el proyecto Quasar:
{
"scripts": {
// ...
"build": "quasar build"
}
}Después de ejecutar el comando generate, deberías poder ver un nuevo dist carpeta en la raíz de tu proyecto.
Esta carpeta se utilizará por Capacitor más adelante, pero por ahora debemos configurarla correctamente.
Agregar Capacitor a tu aplicación Quasar
Para empaquetar cualquier aplicación web en un contenedor móvil nativo, debemos seguir unos pocos pasos inicialmente, pero después es tan simple como ejecutar un solo sync comando.
Primero, podemos instalar el Capacitor CLI como dependencia de desarrollo, y luego configurarlo dentro de nuestro proyecto. Durante la configuración, puedes pulsar “enter” para aceptar los valores predeterminados para el nombre y el ID de la aplicación.
A continuación, debemos instalar el paquete principal y los paquetes relevantes para las plataformas iOS y Android.
Finalmente, podemos agregar las plataformas, y Capacitor creará carpetas para cada plataforma en la raíz de nuestro proyecto:
# Install the Capacitor CLI locally
npm install -D @capacitor/cli
# Initialize Capacitor in your Quasar 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
Hasta este punto, deberías poder observar nuevos ios y android Estos son proyectos nativos reales!
¡Son proyectos nativos reales!
Para acceder al proyecto de Android más adelante, debes instalar Android StudioPara iOS, necesitas un Mac y debes instalar Xcode.
Además, deberías encontrar un capacitor.config.ts archivo en tu proyecto, que contiene algunas configuraciones fundamentales Capacitor utilizadas durante la sincronización. La única cosa que debes tener en cuenta es el webDir, que debe apuntar al resultado de tu comando de compilación. Actualmente, es inexacto.
Para corregir esto, abre el capacitor.config.json archivo y actualiza el webDir:
{
"appId": "com.example.app",
"appName": "my-app",
"webDir": "dist"
}Puedes probarlo ejecutando los siguientes comandos:
npm run generate
npx cap syncEl primer comando npm run generate construirá simplemente su proyecto de Quasar y copiará la compilación estática, mientras que la segunda orden npx cap sync sincronizará todos los web code en los lugares adecuados de las plataformas nativas para que puedan ser mostrados en una aplicación.
Además, la orden de sincronización podría actualizar las plataformas nativas e instalar plugins, por lo que cuando instale un nuevo Capacitor plugins Es hora de ejecutar npx cap sync again.
Ahora, sin darte cuenta, ya estás listo, así que veamos la aplicación en un dispositivo.
Desarrolla y Despliega aplicaciones nativas
Construir y Desplegar aplicaciones nativas Xcode instalado, y para aplicaciones de Android, necesitas tener Android Studio instalado. Además, si planeas distribuir tu aplicación en la tienda de aplicaciones, debes inscribirte en el Programa de Desarrolladores de Apple para iOS y en el Console de Google Play para Android.
Si eres nuevo en el desarrollo de aplicaciones móviles nativas, puedes utilizar el Capacitor CLI para abrir fácilmente ambos proyectos nativos:
npx cap open ios
npx cap open androidUna vez que hayas configurado tus proyectos nativos, desplegar tu aplicación en un dispositivo conectado es fácil. En Android Studio, solo necesitas esperar a que todo esté listo, y puedes desplegar tu aplicación en un dispositivo conectado sin cambiar ninguna configuración. Aquí tienes un ejemplo:
En Xcode, debes configurar tu cuenta de firma para desplegar tu aplicación en un dispositivo real en lugar del simulador. Si no lo has hecho antes, Xcode te guía a través del proceso (pero, nuevamente, debes estar inscrito en el Programa de Desarrolladores). Después de eso, solo debes pulsar play para ejecutar la aplicación en tu dispositivo conectado, que puedes seleccionar en la parte superior. Aquí tienes un ejemplo:
Felicidades! Has desplegado con éxito tu aplicación web de Quasar en un dispositivo móvil. Aquí tienes un ejemplo:
Pero espera, hay una forma más rápida de hacer esto durante el desarrollo…
Capgo Live Update
Capgo Live Update es un servicio que permite a los desarrolladores desplegar actualizaciones de sus aplicaciones móviles sin pasar por el proceso tradicional de subida a la Tienda de Aplicaciones. Esto puede ser una forma conveniente de corregir rápidamente errores o hacer actualizaciones pequeñas en una aplicación sin tener que esperar al proceso de revisión de la Tienda de Aplicaciones.
Integrating Capgo into your Quasar app is a straightforward process that empowers you to harness the power of real-time live updates. This step-by-step guide will walk you through the integration and implementation of Capgo Live Update, enabling you to deliver seamless updates.
Regístrate y accede a la consola de Capgo:
Es hora de registrarse y obtener tu clave de API para subir tu primera versión. registrarse en una cuenta de Capgo.
Instala el Capgo SDK:
Desde una línea de comandos, en la raíz de tu aplicación Capacitor, ejecuta:
npm i @capgo/capacitor-updater && npx cap sync Para instalar el plugin en tu aplicación Capacitor.
Y luego agrega a tu aplicación este code en lugar de CodePush:
import { CapacitorUpdater } from '@capgo/capacitor-updater'
CapacitorUpdater.notifyAppReady()Esto le dirá al plugin nativo que la instalación ha tenido éxito.
Inicia sesión en Capgo CLOUD:
Primero, utiliza el all apikey presente en tu cuenta para iniciar sesión con el CLI:
`npx @capgo/cli@latest login YOU_KEY`Agrega tu primera aplicación:
Comencemos creando una aplicación en Capgo con el CLI.
npx @capgo/cli@latest app addEsta orden utilizará todas las variables definidas en el archivo de configuración de Capacitor para crear la aplicación.
Carga tu primera versión:
Ejecuta la orden para construir tu code y enviarla a Capgo con:
npx @capgo/cli@latest bundle upload`Por defecto, el nombre de la versión será el que se encuentra en tu archivo package.json.
Revisa en Capgo si el build está presente.
Puedes incluso probarlo con mi aplicación de sandbox móvil.
Establecer canal predeterminado:
Después de enviar tu aplicación a Capgo, debes establecer tu canal como predeterminado para que las aplicaciones puedan recibir actualizaciones de Capgo.
npx @capgo/cli@latest channel set production -s default
Configura la app para validar actualizaciones:
Agregar esta configuración a tu archivo JavaScript principal.
import { CapacitorUpdater } from '@capgo/capacitor-updater'
CapacitorUpdater.notifyAppReady()Hacer un npm run build && npx cap copy para actualizar tu aplicación.
Recibir un Live Update:
Para que tu aplicación reciba un live update de Deploy, necesitarás ejecutar la aplicación en un dispositivo o un emulador. La forma más fácil de hacer esto es simplemente usar el siguiente comando para lanzar tu aplicación local en un emulador o un dispositivo conectado a tu computadora.
npx cap run [ios | android]Abre la aplicación, ponla en segundo plano y abríla de nuevo, deberías ver en los registros que la aplicación realizó la actualización.
Felicidades! 🎉 Has desplegado con éxito tu primera Live Update. Esto es solo el comienzo de lo que puedes hacer con Actualizaciones en Vivo. Para aprender más, consulta la documentación completa de Documentación de Actualizaciones en Vivo.
Usando plugins de Capacitor
Vamos a ver cómo utilizar un plugin de Capacitor en acción, que mencionamos anteriormente varias veces. Para hacer esto, podemos instalar un plugin bastante simple ejecutando:
npm i @capacitor/shareSin embargo, no hay nada especial en el plugin de CompartirPero de todos modos, abre el diálogo de compartir nativo. Para esto, ahora solo es necesario importar el paquete y llamar al método correspondiente. share() función de nuestra aplicación, así que cambiémosla pages/index.vue a esto:
<template>
<div>
<h1>Welcome to Quasar 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>As mentioned earlier, when installing new plugins, we need to perform a sync operation and then redeploy the app to our device. To do this, run the following command:
npx cap syncDespués de pulsar el botón, podrás ver en acción el hermoso diálogo de compartir nativo.
Next, you can make the app feel more native on iOS and Android with Capgo navigation and transitions, and fix common iOS layout issues that cause horizontal overflow or cropped safe areas.
Interfaz de usuario con un sentimiento nativo con Capgo Navegación y Transiciones nativas
He trabajado durante años con Angular a construir aplicaciones de múltiples plataformas, pero integrarlo con Quasar es engorroso y raramente vale la pena cuando ya tienes Tailwind CSS.
Para un sentir móvil nativo en una aplicación Quasar + Capacitor, utilice plugins Capgo en lugar de kits de interfaz de usuario 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 difuminado en Android. Su router de Quasar mantiene el estado de ruta; el plugin es dueño del navegador nativo.
- @capgo/capacitor-transiciones Transiciones de página estilo Ionic y retroceso por swipe en iOS en la capa WebView, sin adoptar la interfaz de usuario de Ionic.
Instale ambos:
npm add @capgo/capacitor-native-navigation @capgo/capacitor-transitions
npmx cap syncConfigure 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',
},
});Render un tablero de Liquid Glass (iOS utiliza la renderización propia del sistema; Android utiliza un fondo degradado de 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 capa 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>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 controla esas superficies.
Consulte las guías completas: Usando @capgo/capacitor-navigación-nativa y Usando @capgo/capacitor-transiciones.
Áreas seguras con Tailwind
Para áreas seguras de dispositivos en Tailwind CSS, utiliza @capgo/tailwind-capacitor (publicado como) tailwind-capacitor en npm). Ofrece safe-areas utilidades y otros plugins de Tailwind Capacitor-amigables:
npm add -D tailwind-capacitorIn src/css/app.scss:
@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 esparcirlos env(safe-area-inset-*) manualmente. El proyecto está activamente desarrollado — si algo falta para tu configuración de Quasar, abre una solicitud de extracción 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 no suele solucionar el problema. Trabaja a través de estas comprobaciones en orden.
Asegúrese de que la etiqueta meta de viewport se aplique correctamente
In index.html (o su plantilla de HTML de Quasar), establezca la etiqueta meta de viewport en <head>:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />Administre el área segura de iOS desde un solo contenedor raíz
Crear un solo contenedor de aplicación y aplique allí el relleno de área segura — no en múltiples componentes anidados:
html,
body,
#q-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);
}Wrap all page content inside __CAPGO_KEEP_0__. .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-capacitorpuede expresar el mismo relleno con utilidades como pt-safe pb-safe px-safe en ese solo contenedor.
Ajuste Capacitor iOS contentInset para 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/spa',
ios: {
contentInset: 'never',
},
};Mezclar el diseño de contenido automático de Capacitor con CSS env(safe-area-inset-*) de padding es una causa común de espaciado doble.
Encuentre el elemento que sobresale realmente
El culpable usual es un elemento que utiliza 100vw, Tailwind w-screen, un ancho de píxeles fijo, o un tamaño min-width.
In 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 desbordamiento horizontal provienen de 100vw / w-screen, relleno de área segura duplicado, o un contenedor de ancho fijo — no del meta de viewport en sí.
Conclusión
Capacitor es una excelente opción para crear aplicaciones nativas basadas en un proyecto web existente, ofreciendo una forma sencilla de compartir code y mantener una interfaz de usuario consistente.
Y con la adición de CapgoEs 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.
Si deseas aprender a agregar Capgo a tu aplicación Next.js, consulta el siguiente artículo.
Sigue adelante desde la creación de aplicaciones móviles con actualizaciones en vivo, Quasar y Capacitor.
Si estás utilizando Crear Aplicaciones Móviles con actualizaciones en vivo, Quasar y Capacitor. para planificar el trabajo de plugin nativo, conectarlo con Capgo Directorio de Plugins para el flujo de trabajo del producto en Capgo Directorio de Plugins, Capacitor Plugins por Capgo para el detalle de implementación en Capacitor Plugins por Capgo, Agregar o Actualizar Plugins para el detalle de implementación en Agregar o Actualizar Plugins, Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Ionic Enterprise Plugin Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas.
