Afficher l'écran bord à bord dans Capacitor sans plugins

Vous essayez d'implémenter l'affichage à l'égard des bords dans votre application Capacitor ? Vous n'avez pas besoin d'astuces, de plugins ou de solutions de contournement. Capacitor propose une prise en charge officielle de l'affichage à l'égard des bords à travers l'option de configuration officielle adjustMarginsForEdgeToEdge. adjustMarginsForEdgeToEdge option de configuration - il s'agit simplement de peu de documenté.

Beaucoup de développeurs ont du mal avec les layouts edge-to-edge dans les applications Capacitor, surtout lorsqu'ils visent Android 15+. Ils ont souvent recours à 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 d'interface utilisateur plus immersive et moderne. À partir d'Android 15, Google pousse l'affichage edge-to-edge comme standard pour toutes les applications.

La Solution Officielle : ajuster les marges pour l'affichage edge-to-edge

Capacitor fournit l' adjustMarginsForEdgeToEdge option de configuration spécifique à cet effet. Cela est documenté dans la documentation de configuration officielle de Capacitor, mais il est facile de la 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 sous forme 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 de manière intelligente en fonction du dispositif et de la configuration.

Meilleur pour : La plupart des applications de production qui souhaitent une écran bord à bord sur les appareils pris en charge tout en maintenant la compatibilité avec les versions Android plus anciennes.

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

Ce qu'il fait : Force les ajustements de marges pour une écran bord à bord, quel que soit la version d'Android ou les autres paramètres.

Meilleur pour : Les applications qui souhaitent un comportement edge-to-edge sur toutes les versions d'Android prises en charge.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

Ce qu'il fait : Éteint complètement les ajustements automatiques de marges.

Meilleur pour : Les applications qui gèrent manuellement la disposition edge-to-edge ou qui ne veulent pas de 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 :

Contenu masqué derrière les barres système
Écartement et espacement inconfortables
Apparence incohérente sur les 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 à bords édges, 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 anciennes versions d'Android - Assurez-vous de la compatibilité inverse
les différentes tailles d'écran - 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.

N'associez pas avec des implémentations manuelles

Si vous utilisez adjustMarginsForEdgeToEdge, supprimez tout traitement manuel des marges de fenêtre ou les hacks CSS que vous avez ajoutés.

N'oubliez pas les CSS d'aire de sécurité

La configuration gère les ajustements de marge, mais vous devez toujours utiliser les insets CSS d'aire de sécurité pour un padding de contenu correct.

Guide de migration

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

Supprimez tout les plugins à écran égal 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 android

Prévoyance

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

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é de manière appropriée
Vérifiez vos maquettes sur les appareils avec écran écran écran activé

Ressources supplémentaires

Conclusion

L'affichage écran écran écran dans Capacitor n'a pas besoin de plugins, de trucs ou de solutions complexes. Le adjustMarginsForEdgeToEdge Une 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.

Questions ou rencontrez-vous 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 un comportement de médias et d'interface natifs, connectez-l’avec En utilisant @Capacitor/__CAPGO_KEEP_1__-live-activités Pour la plupart des applications, testez soigneusement sur plusieurs appareils et ajoutez un CSS de zone de sécurité appropriée. Using @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-activités en direct @capgo/capacitor-activités en direct pour le détail d'implémentation dans @capgo/capacitor-activités en direct Utiliser @capgo/capacitor-joueur de vidéo pour la capacité native dans Utiliser @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 Utiliser @capgo/capacitor-navigation native pour la capacité native dans Utiliser @capgo/capacitor-navigation native.

Affichage à l'égard des bords dans Capacitor sans plugins