Affichage edge-to-edge dans Capacitor sans plugins

Vous essayez d'implémenter l'affichage edge-to-edge dans votre application Capacitor ? Pas besoin de hacks, de plugins ou de solutions de contournement. Capacitor prend en charge officiellement l'affichage edge-to-edge via le adjustMarginsForEdgeToEdge option de configuration — elle n'est tout simplement pas très documentée.

De nombreux développeurs peinent avec les mises en page edge-to-edge dans les applications Capacitor, surtout pour Android 15+. Ils ont souvent recours à des plugins personnalisés ou des hacks CSS pour obtenir ce look moderne. Mais il existe une meilleure méthode native.

Qu'est-ce que l'affichage edge-to-edge ?

L'affichage edge-to-edge permet au contenu de votre application de s'étendre derrière les barres système (barre d'état et barre de navigation), créant une interface plus immersive et moderne. Avec Android 15, Google impose l'edge-to-edge comme standard pour toutes les applications.

La solution officielle : adjustMarginsForEdgeToEdge

Capacitor propose l' adjustMarginsForEdgeToEdge option de configuration spécifiquement conçue à cet effet. Elle est répertoriée dans la documentation officielle de la config Capacitor, mais elle est facile à manquer.

Comment la configurer

Ajoutez ceci à votre capacitor.config.ts ou 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 au 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 que cela fait : Vérifie automatiquement la présence d'Android 15+ et du windowOptOutEdgeToEdgeEnforcement paramètre est activé. Ajuste intelligemment les marges selon l'appareil et la configuration.

Idéal pour : Pour la plupart des apps en production souhaitant l'affichage edge-to-edge sur les appareils compatibles tout en maintenant la compatibilité avec les anciennes versions d'Android.

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

Ce que cela fait : Force l'ajustement des marges pour l'affichage edge-to-edge, peu importe la version d'Android ou les autres paramètres.

Idéal pour : Les applications souhaitant un affichage edge-to-edge sur toutes les versions Android supportées.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

Ce que cela fait : Désactive complètement les ajustements automatiques de marges.

Idéal pour : Les applications qui gèrent manuellement le layout edge-to-edge ou ne souhaitent pas ce comportement.

Note : Actuellement, "disable" est la valeur par défaut, mais cela passera à "auto" dans Capacitor 8.

Pourquoi c'est important pour Android 15+

À partir d'Android 15, Google impose l'affichage edge-to-edge par défaut. Les applications qui ne gèrent pas correctement les layouts edge-to-edge peuvent rencontrer des problèmes d'UI tels que :

Contenu masqué par les barres système
Espacement et padding maladroits
Apparence incohérente selon les appareils
Expérience utilisateur médiocre

En utilisant la adjustMarginsForEdgeToEdge config officielle, vous garantissez que votre app gère ces changements correctement sans code personnalisé.

Exemple complet

Voici un exemple de configuration complet pour une app Capacitor moderne :

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 de l'affichage edge-to-edge, vous devrez peut-être ajouter du CSS pour gérer les safe areas :

/* 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";
}

Tester votre configuration

Après la configuration adjustMarginsForEdgeToEdge, testez votre app sur :

appareils Android 15+ - Vérifiez que le contenu respecte bien les barres système
Versions plus anciennes d'Android - Assurez la compatibilité ascendante
Différentes tailles d'écran - Verify layouts work across devices
Thèmes clair et sombre - Testez les deux modes de thème

Erreurs communes à é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 proprement. Si vous avez besoin d'un contrôle précis sur le chrome système après l'avoir activé adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar et @capgo/home-indicator pour compléter la config native sans la remplacer.

Ne pas mélanger avec des implémentations manuelles

Si vous utilisez adjustMarginsForEdgeToEdge, supprimez toute gestion manuelle des window insets ou les hacks CSS que vous auriez pu ajouter.

N'oubliez pas le CSS Safe Area

La config gère l'ajustement des marges, mais vous devez toujours utiliser les CSS safe area insets pour le padding du contenu.

Guide de migration

Si vous utilisez actuellement des plugins ou des hacks pour l'affichage edge-to-edge :

Supprimez les plugins edge-to-edge de vos dépendances
Ajoutez l'option de config vers votre capacitor.config.ts
Nettoyez et relancez le build votre projet Android
Testez à fond 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 android

Préparer l'avenir

N'oubliez pas que Capacitor 8 définira "auto" la valeur par défaut. Pour préparer :

Testez avec "auto" maintenant pour détecter les problèmes au plus tôt
Mettre à jour votre CSS pour gérer correctement les safe areas
Vérifier vos layouts sur les appareils avec l'affichage edge-to-edge

Ressources complémentaires

Conclusion

L'affichage edge-to-edge dans Capacitor ne nécessite ni plugins, ni hacks, ni solutions complexes. Le adjustMarginsForEdgeToEdge Cette option de configuration offre une solution native propre, officiellement supportée et pérenne.

Commencez par "auto" Pour la plupart des apps, testez minutieusement sur différents appareils et ajoutez le CSS de safe area approprié. Votre app sera prête pour Android 15 et les versions suivantes avec un effort minimal.

Des questions ou des problèmes ? La communauté Capacitor et documentation officielle are great resources for additional help.

Continuer l'article sur l'affichage Edge-to-Edge dans Capacitor sans plugins

Si vous utilisez Affichage edge-to-edge dans Capacitor sans plugins pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la fonctionnalité native dans la section Utiliser @capgo/capacitor-video-player, @capgo/capacitor-video-player pour les détails d'implémentation dans @capgo/capacitor-video-player, et Utilisation de @capgo/capacitor-native-navigation pour la fonctionnalité native dans Using @capgo/capacitor-native-navigation.