Vous essayez d'implémenter l'affichage de bordure à bordure dans votre application Capacitor ? Vous n'avez pas besoin d'astuces, de plugins ou de solutions de contournement. Capacitor dispose d'une prise en charge officielle de l'affichage de bordure à bordure via adjustMarginsForEdgeToEdge option de configuration - ce n'est tout simplement pas bien documenté.
Beaucoup de développeurs ont du mal avec les layouts de bord à bord dans les applications Capacitor, surtout lorsqu'ils visent Android 15+. Ils recourent souvent à des plugins personnalisés ou des hacks CSS pour obtenir l'apparence moderne de bord à bord. Mais il existe une meilleure façon native.
Qu'est-ce qu'une affichage de bord à bord ?
La mise en page de bord à bord permet à votre contenu d'application de s'étendre derrière les barres système (barre de statut et barre de navigation), créant une expérience d'interface utilisateur plus immersive et moderne. À partir d'Android 15, Google pousse la mise en page de bord à bord comme standard pour toutes les applications.
La Solution Officielle : ajuster les marges pour la mise en page de bord à bord
Capacitor fournit l'option de configuration spécifique à cet effet. Cela est documenté dans la documentation de configuration Capacitor officielle adjustMarginsForEdgeToEdge mais il est facile de le manquer. official Capacitor config documentationAjoutez cela à votre
ou
configuration capacitor.config.ts __CAPGO_KEEP_0__ 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 en format JSON :
{
"appId": "com.example.app",
"appName": "My App",
"webDir": "dist",
"android": {
"adjustMarginsForEdgeToEdge": "auto"
}
}Options de configuration
Le adjustMarginsForEdgeToEdge l'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 appareil et de la configuration.
Idéal pour : La plupart des applications de production qui veulent une bordure à l'arrêt sur les appareils pris en charge tout en maintenant la compatibilité avec les anciennes versions d'Android.
2. "force"
adjustMarginsForEdgeToEdge: 'force'Ce qu'il fait : Force les ajustements de marges pour une bordure à l'arrêt, quel que soit la version d'Android ou les autres paramètres.
Meilleur pour : Les applications qui veulent une comportement edge-to-edge sur toutes les versions d'Android prises en charge.
3. "disable"
adjustMarginsForEdgeToEdge: 'disable'Ce qu'il fait : Désactive complètement les ajustements de marges automatiques.
Meilleur pour : Les applications qui gèrent manuellement la disposition edge-to-edge ou qui ne veulent pas de comportement edge-to-edge.
Remarque : Actuellement "disable" est la valeur par défaut, mais cela changera à "auto" dans la version Capacitor 8.
Pourquoi Cela Compte pour Android 15+
À partir d'Android 15, Google impose le comportement de la mise en page edge-to-edge comme comportement par défaut. Les applications qui ne gèrent pas correctement les dispositions edge-to-edge peuvent rencontrer des problèmes de UI comme :
- Contenu masqué derrière les barres système
- Écartement et espacement inconfortables
- Apparence incohérente sur les différents appareils
- Expérience utilisateur décevante
En utilisant l'official adjustMarginsForEdgeToEdge config, vous vous assurez que votre application gère ces changements correctement sans un 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
Lors de l'utilisation d'une affichage écran à l'égard de l'arête, vous pouvez avoir besoin d'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 :
- les appareils Android 15+ - Vérifiez que le contenu respecte correctement les barres système
- les versions Android plus anciennes - Assurez la compatibilité vers le bas
- les tailles d'écran différentes - Vérifiez que les dispositions fonctionnent sur plusieurs appareils
- les thèmes clair et sombre - Testez les deux modes de thème
Les erreurs courantes à éviter
N'utilisez pas de plugins pour cela
Vous n'avez pas besoin de plugins tiers comme capacitor-edge-to-edge ou similaire. La configuration native gère cela de manière propre. Si vous avez besoin d'un contrôle fin sur le chrome système après avoir activé adjustMarginsForEdgeToEdge, @capgo/capacitor-barre_de_navigation et @capgo/indicateur_d'accueil complétez la configuration native sans la remplacer.
Ne Mélangez pas avec des Implémentations Manuelles
Si vous utilisez adjustMarginsForEdgeToEdge, supprimez tout le traitement manuel des bordures de fenêtre ou les trucs CSS que vous avez ajoutés.
Ne Rendez pas l'Oubli de la Zone de Sécurité CSS
La configuration gère les ajustements de marge, mais vous avez toujours besoin d'utiliser les insets CSS de la zone de sécurité pour un padding de contenu correct.
Guide de Migration
Si vous utilisez actuellement des plugins ou des trucs pour l'edge-to-edge :
- Supprimez tout plugin edge-to-edge de vos dépendances 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
N'oubliez pas que Capacitor 8 fera la valeur par défaut. Pour se préparer : "auto" Testez avec
- Testez avec
"auto"maintenant pour détecter les problèmes potentiels dès le début - Mettez à jour votre CSS pour gérer les zones de sécurité correctement
- Vérifiez vos maquettes sur les appareils avec écran écran à bords
Ressources supplémentaires
- Documentation de configuration officielle Capacitor
- Lignes directrices Android pour les écrans à bords
- Les espaces de sécurité CSS
Conclusion
L'affichage à bords écrans dans Capacitor n'exige pas de plugins, de trucs ou de solutions complexes. adjustMarginsForEdgeToEdge Cette option de configuration fournit une solution native et propre, officiellement prise en charge et future-proof.
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.
Questions ou en train de rencontrer des problèmes ? La communauté et la documentation officielle de Capacitor sont de grandes ressources pour obtenir de l'aide supplémentaire. Continuez de l'Edge-to-Edge Display dans __CAPGO_KEEP_0__ Sans Plugins Si vous utilisez
Edge-to-Edge Display dans Capacitor Sans Plugins
pour planifier le comportement des médias et de l'interface native, connectez-le avec En utilisant @Capacitor/__CAPGO_KEEP_1__-live-activities 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. Using @capgo/capacitor-live-activities pour la capacité native dans l'utilisation de @capgo/capacitor-live-activités, @capgo/capacitor-live-activités pour le détail d'implémentation dans @capgo/capacitor-live-activités, En utilisant @capgo/capacitor-video-joueur pour la capacité native dans l'utilisation de @capgo/capacitor-video-joueur, @capgo/capacitor-video-joueur pour le détail d'implémentation dans @capgo/capacitor-video-joueur, et En utilisant @capgo/capacitor-navigation-native pour la capacité native dans l'utilisation de @capgo/capacitor-navigation-native.
