Affichage de bord à bord dans Capacitor sans plugins

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 - il n'est tout simplement pas largement documenté.

Beaucoup de développeurs ont du mal avec les layouts de bord à bord dans les applications Capacitor, surtout lorsqu'elles visent Android 15+. Ils ont souvent recours à 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 ?

L'affichage 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 l'affichage de bord à bord comme standard pour toutes les applications.

La Solution Officielle : ajuster les marges pour l'affichage de bord à bord

Capacitor fournit l' adjustMarginsForEdgeToEdge option de configuration spécifique à cet effet. Cela est documenté dans la documentation de configuration officielle Capacitor, mais il est facile de la manquer.

Comment la Configurer

Ajoutez cela à 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 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 réglage. Ajuste les marges de manière intelligente en fonction du dispositif et de la configuration.

Meilleur pour : La plupart des applications de production qui veulent une bordure égale 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 égale, quel que soit la version d'Android ou les autres réglages.

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" en Capacitor 8.

Pourquoi Cela Compte pour Android 15+

À partir d'Android 15, Google impose le comportement de l'affichage 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 à écran, vous devrez peut-être 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.

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 la mise en œuvre de la zone de sécurité CSS

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

Guide de migration

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

Supprimez les plugins edge-to-edge 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 dès le début
Mettez à jour votre CSS pour gérer les zones de sécurité correctement
Révisez vos layouts sur les appareils avec une zone d'écran élargie

Ressources supplémentaires

Conclusion

La mise en page écran élargie dans Capacitor n'exige pas de plugins, de trucs ou de solutions complexes. L'option de configuration fournit une solution native et propre qui est officiellement prise en charge et futuriste. adjustMarginsForEdgeToEdge Commencez par

pour la plupart des applications, testez soigneusement sur plusieurs appareils et ajoutez les CSS appropriés pour la zone d'écran sûre. Votre application sera prête pour Android 15 et au-delà avec un effort minimal. "auto" Questions ou rencontrez des problèmes ?

Questions ou rencontrez des problèmes ? La communauté Capacitor et la documentation officielle sont de grandes ressources pour obtenir de l'aide supplémentaire. Les ressources officielles sont écrites par

Affichage de bordure à bordure dans Capacitor sans plugins