Dispositivo de borde a borde en Capacitor sin plugins

¿Estás intentando implementar la pantalla de borde a borde en tu aplicación Capacitor? No necesita ningún truco, plugin o solución alternativa. Capacitor cuenta con soporte oficial para pantallas de borde a borde a través de adjustMarginsForEdgeToEdge opción de configuración - simplemente no está bien documentada.

Muchos desarrolladores se enfrentan a problemas con diseños de bordes a bordes en aplicaciones Capacitor, especialmente cuando se dirigen a Android 15+. A menudo recurren a plugins o trucos de CSS personalizados para lograr la apariencia moderna de bordes a bordes. Pero hay una mejor forma, nativa.

¿Qué es la pantalla de borde a borde?

La pantalla de bordes a bordes permite que el contenido de la aplicación se extienda detrás de las barras del sistema (barra de estado y barra de navegación), creando una experiencia de interfaz de usuario más inmersiva y moderna. A partir de Android 15, Google está impulsando la pantalla de bordes a bordes como estándar para todas las aplicaciones.

La Solución Oficial: ajustarMárgenesParaBordesA

Capacitor proporciona la adjustMarginsForEdgeToEdge opción de configuración específica para este propósito. Esto se documenta en la documentación de configuración oficial de Capacitor, pero es fácil pasar por alto.

Cómo Configurarlo

Agregar 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

La adjustMarginsForEdgeToEdge Opción acepta tres valores:

1. "auto" (Recomendado)

adjustMarginsForEdgeToEdge: 'auto'

¿Qué hace: Verifica automáticamente Android 15+ y la windowOptOutEdgeToEdgeEnforcement ajusta las márgenes de manera inteligente según el dispositivo y la configuración.

Mejor para: La mayoría de las aplicaciones de producción que desean una pantalla de borde a borde en dispositivos compatibles mientras mantienen la compatibilidad con versiones antiguas de Android.

2. "force"

adjustMarginsForEdgeToEdge: 'force'

¿Qué hace: Ajusta las margenes para pantallas de borde a borde sin importar la versión de Android o otros ajustes.

Mejor para: Aplicaciones que desean comportamiento de borde a borde en todas las versiones de Android admitidas.

3. "disable"

adjustMarginsForEdgeToEdge: 'disable'

¿Qué hace: Desactiva ajustes de márgenes automáticos por completo.

Mejor para: Aplicaciones que manejan manualmente el diseño de borde a borde o no desean comportamiento de borde a borde.

Notas: Actualmente "disable" es el valor predeterminado, pero esto cambiará a "auto" en Capacitor 8.

¿Por qué esto importa para Android 15+?

Starting with Android 15, Google is enforcing edge-to-edge display as the default behavior. Apps that don’t properly handle edge-to-edge layouts may experience UI issues like:

• Contenido oculto detrás de las barras del sistema
• Espaciado y relleno desafortunados
• Aspecto inconsistente en dispositivos
• Experiencia de usuario deficiente

Al utilizar la configuración oficial adjustMarginsForEdgeToEdge configura tu aplicación para manejar estos cambios correctamente sin necesidad de un code.

Ejemplo Completo

Aquí está un ejemplo de configuración completa para una aplicación moderna Capacitor.

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

Cuando se utiliza una pantalla de borde a borde, es posible que deba agregar algún CSS para manejar áreas seguras:

/* 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";
}

Después de configurar

, prueba tu aplicación en: adjustMarginsForEdgeToEdgePrueba tu configuración en dispositivos

1. Dispositivos Android 15+ Verifique que el contenido respete correctamente las barras del sistema
2. Versiones de Android más antiguas Asegúrese de la compatibilidad hacia atrás
3. Tamaños de pantalla diferentes - Verify layouts work across devices
4. Temas claro y oscuro Pruebe ambos modos de tema

Errores comunes a evitar

No utilice plugins para esto

No necesita plugins de terceros como capacitor-edge-to-edge o similar. La configuración nativa maneja esto de manera limpia. Si necesita control fino sobre el navegador del sistema después de habilitar adjustMarginsForEdgeToEdge, @capgo/capacitor-barra-de-navegación y @capgo/__CAPGO_KEEP_1__-navegación-barra complementar la configuración nativa sin reemplazarla.

complementa la configuración nativa sin reemplazarla.

No mezclar con implementaciones manuales adjustMarginsForEdgeToEdge, elimine cualquier manejo manual de ajustes de ventanas o trucos de CSS que haya agregado.

No te olvides de CSS de área segura

El configura ajustes de margen, pero todavía necesitas usar insets de área segura de CSS para un relleno de contenido adecuado.

Guía de Migración

Si actualmente estás utilizando plugins o trucos para pantallas de borde a borde:

1. Quitar cualquier plugin de pantalla completa desde tus dependencias
2. Agregar la opción de configuración a tu capacitor.config.ts
3. Limpia y reconstruye tu proyecto de Android
4. Prueba exhaustivamente en dispositivos objetivo

# 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 cualquier problema temprano
2. actualice su CSS para manejar las áreas seguras correctamente
3. revisar sus diseños en dispositivos habilitados para bordes de pantalla

Recursos adicionales

• Documentación oficial de la configuración de Capacitor
• Directrices de Android para bordes de pantalla
• Ingresos de área segura de CSS

Conclusiones

Pantalla de borde a borde en Capacitor no requiere plugins, trucos ni complicadas soluciones. adjustMarginsForEdgeToEdge La configuración de __CAPGO_KEEP_0__ proporciona una solución nativa limpia que está oficialmente respaldada y futura.

Comience con "auto" para la mayoría de las aplicaciones, pruebe exhaustivamente en dispositivos y agregue CSS de área segura adecuada. Su aplicación estará lista para Android 15 y más con un mínimo de esfuerzo.

Preguntas o estás teniendo problemas? La comunidad de Capacitor y la documentación oficial son recursos excelentes para obtener ayuda adicional.

Sigue adelante desde la pantalla de Edge-to-Edge Display en Capacitor Sin plugins

Si está utilizando Pantalla de Borde a Borde en Capacitor Sin Plugins para planificar el comportamiento de medios y interfaz nativos, conecte 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.