Essayez d'implémenter l'affichage de bordure à bordure dans votre application Capacitor ? Vous n'avez pas besoin d'hacks, de plugins ou de workarounds. Capacitor propose une prise en charge officielle de l'affichage écran bord à bord par le adjustMarginsForEdgeToEdge option de configuration - il n'est tout simplement pas bien documenté.
Beaucoup de développeurs ont du mal avec les layouts edge-to-edge dans les applications Capacitor, surtout lorsqu'elles visent Android 15+. Ils recourent souvent à des plugins personnalisés ou des hacks CSS pour obtenir l'apparence moderne edge-to-edge. Mais il existe une meilleure façon, native.
Qu'est-ce que l'affichage edge-to-edge ?
L'affichage edge-to-edge permet à votre contenu d'application de s'étendre derrière les barres système (barre d'état et barre de navigation), créant une expérience UI plus immersive et moderne. À partir d'Android 15, Google pousse l'edge-to-edge comme standard pour toutes les applications.
La Solution Officielle : ajusterLesMargesPourAffichageDeBordA Bord
Capacitor fournit les adjustMarginsForEdgeToEdge option de configuration spécifique à cet usage. Cela est documenté dans le documentation officielle de configuration de Capacitormais c'est facile à manquer.
Comment le configurer
Ajoutez ceci à votre capacitor.config.ts or 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;Ou sous format JSON :
{
"appId": "com.example.app",
"appName": "My App",
"webDir": "dist",
"android": {
"adjustMarginsForEdgeToEdge": "auto"
}
}Options de configuration
La adjustMarginsForEdgeToEdge option accepte trois valeurs :
1. "auto" (Recommandé)
adjustMarginsForEdgeToEdge: 'auto'Ce qu'il fait : Vérifie automatiquement Android 15+ et la windowOptOutEdgeToEdgeEnforcement configuration. Ajuste les marges intelligemment en fonction du dispositif et de la configuration.
Meilleur pour : Most production apps that want edge-to-edge on supported devices while maintaining compatibility with older Android versions.
2. "force"
adjustMarginsForEdgeToEdge: 'force'Ce qu'il fait : Ajustements de marges forcés pour écran écran sans tenir compte de la version d'Android ou d'autres paramètres.
Meilleur pour : Applications qui veulent un comportement bord-à-bord sur toutes les versions d'Android prises en charge.
3. "disable"
adjustMarginsForEdgeToEdge: 'disable'What il fait : Active complètement les ajustements de marges automatiques.
Meilleur pour : Les applications qui gèrent manuellement la disposition edge-to-edge ou qui ne souhaitent pas un comportement edge-to-edge.
Note : Actuellement "disable" est la valeur par défaut, mais cela changera à "auto" en Capacitor 8.
Pourquoi Cela Compte pour Android 15+
À partir d'Android 15, Google impose le comportement d'affichage edge-to-edge par défaut. Les applications qui ne gèrent pas correctement les dispositions edge-to-edge peuvent rencontrer des problèmes de UI comme :
- Le contenu caché derrière les barres système
- Écartement et espacement incohérents
- Apparence incohérente sur les appareils
- Expérience utilisateur décevante
En utilisant la configuration officielle adjustMarginsForEdgeToEdge Vous vous assurez ainsi que votre application gère ces changements correctement sans code personnalisé.
Exemple complet
Voici un exemple de configuration complète pour une application moderne 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;Considérations CSS
Lorsque vous utilisez une affichage à l'égard des bords, vous pouvez devoir ajouter du CSS pour gérer les zones de sécurité.
/* 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";
}Testez votre configuration
Après avoir configuré adjustMarginsForEdgeToEdge, testez votre application sur :
- Appareils Android 15+ Vérifiez que le contenu respecte correctement les barres système
- Versions Android plus anciennes Assurez-vous de la compatibilité à rebours
- Tailles d'écran différentes - Verify layouts work across devices
- Thèmes clairs et sombres Testez les deux modes de thème
Erreurs courantes à éviter
N'utilisez pas de plugins pour cela
Vous n'avez pas besoin de plugins tiers comme capacitor-edge-to-edge ou similaires. La configuration native gère cela de manière propre. Si vous avez besoin de contrôler finement le chrome système après avoir activé adjustMarginsForEdgeToEdge, @capgo/capacitor-barre-de-navigation et @capgo/indicateur-d-acceuil complétez la configuration native sans la remplacer.
N'associez pas cela aux implémentations manuelles
Si vous utilisez adjustMarginsForEdgeToEdgeSupprimez tout traitement manuel des marges de fenêtre ou les astuces CSS que vous avez ajoutées.
N'oubliez pas le CSS de zone de sécurité
La configuration gère les ajustements de marge, mais vous devez toujours utiliser les insets de zone sûre CSS pour un padding de contenu correct.
Guide de migration
Si vous utilisez actuellement des plugins ou des astuces pour l'edge-to-edge :
- Supprimez tout plugin edge-to-edge à partir de vos dépendances
- Ajoutez l'option de configuration à votre
capacitor.config.ts - Nettoyez et reconstruisez votre projet Android
- Testez soigneusement sur les appareils cibles
# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..
# Rebuild
npx cap copy android
npx cap open androidPrévoyez l'avenir
Rappelez-vous que Capacitor 8 fera "auto" la valeur par défaut. Pour vous préparer :
- Testez avec
"auto"maintenant pour détecter les problèmes dès le début - Mettez à jour votre CSS pour gérer les zones de sécurité correctement
- Vérifiez vos maquettes Sur appareils avec écran bord à bord
Ressources supplémentaires
- Documentation officielle du Capacitor Config
- Lignes directrices Android Edge-to-Edge
- CSS Inclusions de zones de sécurité
Conclusion
Affichage écran sans interruption en Capacitor n'exige pas de plugins, de trucs ou de solutions compliquées. adjustMarginsForEdgeToEdge option de configuration offre une solution native propre et futuriste, officiellement supportée.
Commencez par "auto" pour la plupart des applications, testez soigneusement sur plusieurs appareils et ajoutez un CSS de zone de sécurité appropriée. Votre application sera prête pour Android 15 et au-delà avec un minimum d'efforts.
Problèmes ou difficultés rencontrées ? La communauté et la documentation officielle de Capacitor sont de grandes ressources pour obtenir de l'aide supplémentaire. documentation officielle are great resources for additional help.
Affichage Edge-to-Edge dans Capacitor Sans Plugins
Si vous utilisez En utilisant @Capacitor/__CAPGO_KEEP_1__-live-activités pour planifier le comportement des médias et de l'interface native, le connecter avec Utilisation de @capgo/capacitor-activités en direct pour la capacité native dans En utilisant @capgo/capacitor-live-activités capgo/capacitor-activités en direct pour le détail d'implémentation dans capgo/capacitor-activités en direct, En utilisant capgo/capacitor-joueur de vidéo pour la capacité native dans En utilisant capgo/capacitor-joueur de vidéo, capgo/capacitor-joueur de vidéo pour le détail d'implémentation dans capgo/capacitor-joueur de vidéo, et En utilisant capgo/capacitor-navigation native pour la capacité native dans En utilisant capgo/capacitor-navigation native.
