Pantalla completa en Capacitor sin plugins

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

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

¿Qué es la Pantalla de Borde a Borde?

La pantalla de borde a borde permite que el contenido de tu 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 borde a borde como estándar para todas las aplicaciones.

La Solución Oficial: adjustMarginsForEdgeToEdge

Capacitor proporciona la opción de configuración específicamente para este propósito. Esto se documenta en la documentación de configuración oficial de Capacitor adjustMarginsForEdgeToEdge Cómo configurarlo official Capacitor config documentationo

O en formato JSON:

Opciones de configuración capacitor.config.ts La 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;

opción acepta tres valores:

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

(Recomendado)

en su archivo de configuración adjustMarginsForEdgeToEdge en su archivo de configuración

1. `"auto"` en su archivo de configuración

adjustMarginsForEdgeToEdge: 'auto'

translations Verifica automáticamente para Android 15+ y el 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 completa en dispositivos compatibles mientras mantienen la compatibilidad con versiones de Android más antiguas.

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

translations Forza ajustes de márgenes para pantalla completa sin importar la versión de Android o otras configuraciones.

Mejor para: Las aplicaciones que desean el comportamiento de pantalla completa en todas las versiones de Android compatibles.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

translations Deshabilita completamente las ajustes automáticos de márgenes.

Mejor para: Aplicaciones que manejan manualmente la disposición de borde a borde o no desean el comportamiento de borde a borde.

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

¿Por qué esto importa para Android 15+

A partir de Android 15, Google está imponiendo la pantalla de borde a borde como el comportamiento predeterminado. Las aplicaciones que no manejan correctamente las disposiciones de borde a borde pueden experimentar problemas de interfaz de usuario como:

Contenido oculto detrás de las barras del sistema
Espaciado y relleno incómodos
Apariencia inconsistente en diferentes dispositivos
Experiencia de usuario deficiente

Al utilizar el oficial adjustMarginsForEdgeToEdge configuración, asegúrese de que su aplicación maneje estos cambios correctamente sin necesidad de code.

Ejemplo Completo

Aquí hay 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, puede necesitar agregar algunos 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 de tu Configuración

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

dispositivos Android 15+ - Verifique que el contenido respete correctamente las barras del sistema
versiones antiguas de Android - Asegúrese de la compatibilidad hacia atrás
Tamaños de pantalla diferentes - Verificar que los diseños funcionen en dispositivos diferentes
Temas claros y oscuros - Probar ambos modos de tema

Errores comunes a evitar

No utilice plugins para esto

No necesita plugins de terceros como capacitor-edge-to-edge o similares. La configuración nativa maneja esto de manera limpia.

No mezcle con implementaciones manuales

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

No se olvide de CSS de área segura

La configuración gestiona 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 edge-to-edge:

Elimina cualquier plugin de edge-to-edge de tus dependencias Agrega la opción de configuración
a tu Limpia y reconstruye capacitor.config.ts
tu proyecto de Android Prueba exhaustivamente
en dispositivos objetivo Preparación para el Futuro

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

# Rebuild
npx cap copy android
npx cap open android

Preparándote para el Futuro

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

Pruebe con "auto" ahora para detectar cualquier problema temprano
Actualice su CSS para manejar las áreas seguras correctamente
Revisar sus diseños en dispositivos con pantalla completa habilitada

Recursos Adicionales

Conclusión

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

Para la mayoría de las aplicaciones, pruebe exhaustivamente en dispositivos y agregue CSS de seguridad de área adecuada. Su aplicación estará lista para Android 15 y más allá con un mínimo de esfuerzo. "auto" Tiene alguna pregunta o está teniendo problemas?

La comunidad de __CAPGO_KEEP_0__ y la The Capacitor community and son recursos excelentes para obtener ayuda adicional. Escrito por

Pantalla de bordes a bordes en Capacitor sin plugins