Pantalla edge-to-edge en Capacitor sin plugins

¿Intentas implementar el modo edge-to-edge en tu app de Capacitor? No necesitas hacks, plugins ni trucos. Capacitor tiene soporte oficial para el modo edge-to-edge a través de adjustMarginsForEdgeToEdge una opción de configuración, solo que no está muy documentada.

Muchos desarrolladores tienen problemas con los layouts edge-to-edge en apps de Capacitor, especialmente con Android 15+. Suelen recurrir a plugins personalizados o hacks de CSS para lograr el aspecto moderno edge-to-edge. Pero hay una forma mejor y nativa.

¿Qué es la pantalla edge-to-edge?

El diseño edge-to-edge permite que el contenido de tu app se extienda detrás de las barras del sistema (barra de estado y barra de navegación), creando una experiencia de UI más inmersiva y moderna. A partir de Android 15, Google está impulsando el edge-to-edge como el estándar para todas las apps.

La solución oficial: adjustMarginsForEdgeToEdge

Capacitor ofrece la adjustMarginsForEdgeToEdge opción de configuración específica para esto. Está recogida en la documentación oficial de configuración de Capacitor, pero es fácil pasarla por alto.

Cómo configurarla

Añade esto a tu capacitor.config.ts o capacitor.config.json:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  android: {
    adjustMarginsForEdgeToEdge: 'auto' // or 'force' or 'disable'
  }
};

export default config;

O en formato JSON:

{
  "appId": "com.example.app",
  "appName": "My App",
  "webDir": "dist",
  "android": {
    "adjustMarginsForEdgeToEdge": "auto"
  }
}

Opciones de configuración

El adjustMarginsForEdgeToEdge la opción acepta tres valores:

1. "auto" (Recomendado)

adjustMarginsForEdgeToEdge: 'auto'

What it does: Comprueba automáticamente si es Android 15+ y el windowOptOutEdgeToEdgeEnforcement configuración. Ajusta los márgenes de forma inteligente según el dispositivo y la configuración.

Ideal para: La mayoría de las apps en producción que buscan el modo edge-to-edge en dispositivos compatibles, manteniendo la compatibilidad con versiones antiguas de Android.

2. "force"

adjustMarginsForEdgeToEdge: 'force'

What it does: Fuerza el ajuste de márgenes para edge-to-edge, sin importar la versión de Android u otros ajustes.

Ideal para: Apps que buscan un comportamiento edge-to-edge en todas las versiones de Android compatibles.

3. "disable"

adjustMarginsForEdgeToEdge: 'disable'

What it does: Desactiva por completo los ajustes automáticos de márgenes.

Ideal para: Apps que gestionan el layout edge-to-edge manualmente o que no desean este comportamiento.

Nota: Actualmente "disable" es el valor por defecto, pero cambiará a "auto" en Capacitor 8.

Por qué es clave para Android 15+

A partir de Android 15, Google exige el modo edge-to-edge como comportamiento predeterminado. Las apps que no gestionen bien los layouts edge-to-edge podrían tener problemas de UI como:

• Contenido oculto tras las barras del sistema
• Espaciado y padding incómodos
• Apariencia inconsistente entre dispositivos
• Mala experiencia de usuario

Al usar el oficial adjustMarginsForEdgeToEdge configuración oficial, te aseguras de que tu app gestione estos cambios correctamente sin code personalizados.

Ejemplo completo

Aquí tienes una configuración de ejemplo completa para una app Capacitor moderna:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'My Awesome App',
  webDir: 'www',
  server: {
    androidScheme: 'https'
  },
  android: {
    // Enable edge-to-edge automatically on supported devices
    adjustMarginsForEdgeToEdge: 'auto',

    // Other Android config options...
    backgroundColor: '#ffffff'
  }
};

export default config;

Consideraciones de CSS

Al usar el modo edge-to-edge, podrías necesitar añadir CSS para gestionar las safe areas:

/* Add padding for system bars */
body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

/* Or use viewport-fit */
meta[name="viewport"] {
  content: "width=device-width, initial-scale=1, viewport-fit=cover";
}

Prueba tu configuración

Tras configurar adjustMarginsForEdgeToEdge, prueba tu app en:

1. dispositivos con Android 15+ - Verifica que el contenido respete correctamente las barras del sistema
2. Versiones anteriores de Android - Asegura la retrocompatibilidad
3. Diferentes tamaños de pantalla - Verify layouts work across devices
4. Temas claro y oscuro - Prueba ambos modos de tema

Errores comunes que debes evitar

No uses plugins para esto

No necesitas plugins de terceros como capacitor-edge-to-edge o similares. La config nativa lo gestiona de forma limpia. Si necesitas control detallado sobre el system chrome tras activar adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar y @capgo/home-indicator complementan la config nativa sin reemplazarla.

No lo mezcles con implementaciones manuales

Si estás usando adjustMarginsForEdgeToEdge, elimina cualquier gestión manual de window insets o hacks de CSS que hayas añadido.

No olvides el CSS de Safe Area

La configuración gestiona los márgenes, pero aún debes usar CSS safe area insets para el padding correcto del contenido.

Guía de migración

Si actualmente usas plugins o hacks para el modo edge-to-edge:

1. Elimina cualquier plugin edge-to-edge de tus dependencias
2. Añade la opción de configuración a tu capacitor.config.ts
3. Limpia y reconstruye tu proyecto de Android
4. Prueba a fondo en los dispositivos de destino

# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..

# Rebuild
npx cap copy android
npx cap open android

Future-Proofing

Recuerda que Capacitor 8 hará "auto" el valor por defecto. Para prepararte:

1. Prueba con "auto" ahora para detectar problemas a tiempo
2. Actualiza tu CSS para gestionar bien las safe areas
3. Revisa tus layouts en dispositivos con edge-to-edge

Recursos adicionales

• Documentación oficial de configuración de Capacitor
• Guías de Android Edge-to-Edge
• CSS Safe Area Insets

Conclusión

La pantalla edge-to-edge en Capacitor no requiere plugins, hacks ni soluciones complejas. La adjustMarginsForEdgeToEdge opción de configuración ofrece una solución nativa, limpia, con soporte oficial y preparada para el futuro.

Empieza con "auto" para la mayoría de las apps, prueba bien en distintos dispositivos y añade el CSS de safe area adecuado. Tu app estará lista para Android 15 y versiones posteriores con mínimo esfuerzo.

¿Tienes dudas o problemas? La comunidad de Capacitor y documentación oficial son excelentes recursos para obtener ayuda adicional.

Sigue con el Edge-to-Edge Display en Capacitor sin plugins

Si estás usando Pantalla edge-to-edge en Capacitor sin plugins para planificar el comportamiento de los medios nativos y la interfaz, conéctalo con Uso de @capgo/capacitor-live-activities para la capacidad nativa en Uso de @capgo/capacitor-live-activities, @capgo/capacitor-live-activities para los detalles de implementación en @capgo/capacitor-live-activities, Uso de @capgo/capacitor-video-player para la capacidad nativa en Uso de @capgo/capacitor-video-player, @capgo/capacitor-video-player por el detalle de implementación en @capgo/capacitor-video-player, y Uso de @capgo/capacitor-native-navigation para la capacidad nativa al usar @capgo/capacitor-native-navigation.