Pantalla de borde a borde en Capacitor sin plugins

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

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

¿Qué es la pantalla de bordes a bordes?

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árgenesParaPantallaDeBordes

Capacitor proporciona la adjustMarginsForEdgeToEdge opción de configuración específica para este propósito. Esto se documenta en la documentación oficial de configuración de Capacitorpero 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 La 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.

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

2. "force"

adjustMarginsForEdgeToEdge: 'force'

¿Qué hace: Aplica ajustes de márgenes para una pantalla completa sin importar la versión de Android o otras configuraciones.

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

3. "disable"

adjustMarginsForEdgeToEdge: 'disable'

¿Qué hace: Deshabilita ajustes de márgenes automáticos completamente.

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

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

¿Por qué esto importa para Android 15+?

Con Android 15, Google está imponiendo el comportamiento de pantalla de borde a borde como comportamiento predeterminado. Las aplicaciones que no manejan correctamente los diseños de borde a borde pueden experimentar problemas de interfaz de usuario como:

• Contenido oculto detrás de barras de sistema
• Espaciado y relleno incómodo
• Apariencia inconsistente en dispositivos
• Experiencia de usuario deficiente

Al utilizar la configuración oficial adjustMarginsForEdgeToEdge config, asegura que tu aplicación maneje estos cambios correctamente sin necesidad de un code personalizado.

Ejemplo Completo

¡Aquí tienes un ejemplo de configuración completo 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

Al utilizar una pantalla de borde a borde, es posible que debas 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";
}

Prueba tu Configuración

Después de configurar adjustMarginsForEdgeToEdgePrueba tu aplicación en:

1. dispositivos Android 15+ - Verifica que el contenido respete correctamente las barras del sistema
2. Versiones de Android más antiguas - Asegúrate de la compatibilidad hacia atrás
3. Tamaños de pantalla diferentes - Verifica que los diseños funcionen en dispositivos diferentes
4. Temas claros y oscuros - Prueba ambos modos de tema

Errores comunes a evitar

No Utilices plugins para esto

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

No mezclar con implementaciones manuales

Si está utilizando adjustMarginsForEdgeToEdge, elimine cualquier manejo manual de ajustes de ventana o trucos CSS que haya agregado.

No olvide el CSS de área segura

La configuración maneja ajustes de margen, pero todavía necesita usar CSS de insets de área segura para un relleno de contenido adecuado.

Guía de Migración

Si actualmente está utilizando plugins o trucos para edge-to-edge:

1. Elimine cualquier plugin de borde a borde de sus dependencias
2. Agregar la opción de configuración a su capacitor.config.ts
3. Limpie y reconstruya su proyecto de Android
4. Pruebe 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

Preparación para el futuro

Recuerde que Capacitor 8 hará "auto" el valor predeterminado. Para prepararse:

1. Pruebe con "auto" ahora para detectar cualquier problema temprano
2. Actualizar su CSS para manejar las áreas seguras correctamente
3. Revisar sus diseños en dispositivos con pantalla de borde a borde habilitada

Recursos Adicionales

• Documentación de Configuración Oficial Capacitor
• Directrices de Android para Pantalla de Borde a Borde
• Ingresos de Área Segura de CSS

Conclusión

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

Inicie 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.

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

Siga adelante desde la pantalla de Edge-to-Edge en Capacitor Sin Plugins

Si está utilizando Edge-to-Edge Display en Capacitor Sin Plugins para planificar el comportamiento de medios y interfaz nativa, conecte con Usando @capgo/capacitor-actividades-en-vivo para la capacidad nativa en Using @capgo/capacitor-actividades-en-vivo, @capgo/capacitor-actividades-en-vivo para el detalle de implementación en @capgo/capacitor-actividades-en-vivo, Using @capgo/capacitor-reproductor-de-videos para la capacidad nativa en Using @capgo/capacitor-reproductor-de-videos, @capgo/capacitor-reproductor-de-videos para el detalle de implementación en @capgo/capacitor-reproductor-de-videos, y Using @capgo/capacitor-navegación-nativa para la capacidad nativa en Using @capgo/capacitor-navegación-nativa.