¿Estás tratando de implementar la pantalla de borde a borde en tu aplicación Capacitor? No necesitas trucos, plugins ni soluciones alternativas. 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árgenesParaBordesAABBordes
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.
Ideal para: La mayoría de las aplicaciones de producción que desean tener una pantalla completa en dispositivos compatibles mientras mantienen la compatibilidad con versiones de Android más antiguas.
2. "force"
adjustMarginsForEdgeToEdge: 'force'¿Qué hace: Forza ajustes de márgenes para 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+?
A partir de Android 15, Google está imponiendo el comportamiento de pantalla de borde a borde como el 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 las barras de sistema
- Espaciado y relleno incómodo
- Apariencia inconsistente en dispositivos diferentes
- 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 las á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 adjustMarginsForEdgeToEdge, prueba tu aplicación en:
- dispositivos Android 15+ - Verifica que el contenido respete correctamente las barras del sistema
- Versiones de Android más antiguas - Asegúrate de la compatibilidad hacia atrás
- Tamaños de pantalla diferentes - Verifica que los diseños funcionen en dispositivos diferentes
- Modos de tema claro y oscuro - 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.
No mezcles con implementaciones manuales
Si estás utilizando adjustMarginsForEdgeToEdge, elimina cualquier manejo manual de ajustes de ventanas o trucos CSS que hayas agregado.
No te olvides del CSS de área segura
La configuración maneja ajustes de margen, pero todavía necesitas usar ajustes 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
capacitor.config.ts - Limpia y reconstruye tu proyecto de Android
- 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 androidPreparación para el futuro
Recuerda que Capacitor 8 hará "auto" el valor por defecto. Para prepararse:
- Prueba con
"auto"ahora para detectar cualquier problema temprano - Actualiza tu CSS para manejar las áreas seguras correctamente
- Revisa tus diseños en dispositivos con pantalla de borde a borde habilitada
Recursos adicionales
- Documentación oficial de configuración de Capacitor
- Directrices de Android para pantallas de borde a borde
- Ingresos de área seguros en CSS
Conclusión
La pantalla de borde a borde en Capacitor no requiere plugins, trucos ni complicadas soluciones. La opción de configuración proporciona una solución limpia y nativa que está oficialmente respaldada y futura. adjustMarginsForEdgeToEdge Comienza con
para la mayoría de las aplicaciones, prueba exhaustivamente en dispositivos y agrega CSS de área segura adecuado. Tu aplicación estará lista para Android 15 y más allá con un mínimo de esfuerzo. "auto" Tienes alguna pregunta o estás teniendo problemas?
Preguntas o estás teniendo problemas? The comunidad de Capacitor y la documentación oficial son recursos excelentes para obtener ayuda adicional. Continúa desde la pantalla de borde a borde en __CAPGO_KEEP_0__ sin plugins
Keep going from Edge-to-Edge Display in Capacitor Without Plugins
la pantalla de borde a borde en __CAPGO_KEEP_0__ sin plugins Edge-to-Edge Display in Capacitor Without Plugins Usando @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-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 Si estás utilizando la pantalla de borde a borde en capgo sin plugins para planificar el comportamiento de medios y interfaz nativos, conecta con @capgo/capacitor-reproductor-de-videos para la implementación detallada en @capgo/capacitor-reproductor-de-videos para la capacidad nativa en Using @capgo/capacitor-video-player, @capgo/capacitor-video-player para el detalle de implementación en @capgo/capacitor-video-player, y Using @capgo/capacitor-native-navigation para la capacidad nativa en Using @capgo/capacitor-native-navigation.
