Stai cercando di implementare il display edge-to-edge nella tua Capacitor app? Non hai bisogno di nessun hack, plugin o workaround. Capacitor supporta nativamente il display edge-to-edge tramite l'opzione di configurazione - è solo poco documentata. adjustMarginsForEdgeToEdge Molti sviluppatori si scontrano con gli schemi edge-to-edge nelle app __CAPGO_KEEP_0__, soprattutto quando si mira a Android 15+. Spesso ricorrono a plugin personalizzati o hack CSS per ottenere l'aspetto moderno edge-to-edge. Ma c'è un modo migliore, nativo.
Many developers struggle with edge-to-edge layouts in Capacitor apps, especially when targeting Android 15+. They often resort to custom plugins or CSS hacks to achieve the modern edge-to-edge look. But there’s a better, native way.
Il display edge-to-edge consente al contenuto dell'app di estendersi dietro le barre di sistema (barra di stato e barra di navigazione), creando un'esperienza di interfaccia utente più immersiva e moderna. A partire da Android 15, Google sta promuovendo l'edge-to-edge come standard per tutte le app.
La Soluzione Ufficiale: adjustMarginsForEdgeToEdge
__CAPGO_KEEP_0__ fornisce l'opzione di configurazione specifica per questo scopo. Questo è documentato nella documentazione di configurazione ufficiale di __CAPGO_KEEP_0__
Capacitor provides the adjustMarginsForEdgeToEdge Edge-to-edge display allows your app content to extend behind system bars (status bar and navigation bar), creating a more immersive, modern UI experience. Starting with Android 15, Google is pushing edge-to-edge as the standard for all apps. official Capacitor config documentationma è facile perdere di vista.
Come configurarlo
Aggiungi questo al tuo capacitor.config.ts o 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;Oppure
{
"appId": "com.example.app",
"appName": "My App",
"webDir": "dist",
"android": {
"adjustMarginsForEdgeToEdge": "auto"
}
}Ora in formato JSON:
Opzioni di configurazione adjustMarginsForEdgeToEdge La
1. "auto" opzione accetta tre valori:
adjustMarginsForEdgeToEdge: 'auto'(Raccomandato) Cos'è che fa: windowOptOutEdgeToEdgeEnforcement Verifica automaticamente Android 15+ e l' impostazione. Adatta le margine in modo intelligente in base al dispositivo e alla configurazione.
Miglior per: La maggior parte degli app di produzione che desiderano un display edge-to-edge su dispositivi supportati, mantenendo la compatibilità con le versioni Android più vecchie.
2. "force"
adjustMarginsForEdgeToEdge: 'force'Cosa fa: Forza gli aggiustamenti di margine per il display edge-to-edge indipendentemente dalla versione Android o da altri impostazioni.
Miglior per: Gli app che desiderano il comportamento edge-to-edge su tutte le versioni Android supportate.
3. "disable"
adjustMarginsForEdgeToEdge: 'disable'Cosa fa: Disabilita completamente gli aggiustamenti di margine automatici.
Miglior per: Gli app che gestiscono manualmente la disposizione edge-to-edge o non desiderano il comportamento edge-to-edge.
Nota: Attualmente "disable" is il default, ma questo cambierà in "auto" in Capacitor 8.
Perché Questo Interessa per Android 15+
Con l'uscita di Android 15, Google sta imponendo l'uso di schermi a bordo bordo come comportamento di default. Le app che non gestiscono correttamente i layout a bordo bordo potrebbero avere problemi di UI come:
- Contenuto nascosto dietro le barre del sistema
- Spaziatura e padding scomodi
- Aspetto non coerente su dispositivi diversi
- Esperienza utente povera
Utilizzando la configurazione ufficiale adjustMarginsForEdgeToEdge config, puoi assicurarti che la tua app gestisca questi cambiamenti correttamente senza dover creare code personalizzati.
Esempio Completo
Ecco un esempio di configurazione completa per un'app moderna 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;Considerazioni CSS
Quando si utilizza una schermata da bordo a bordo, potrebbe essere necessario aggiungere alcuni CSS per gestire le aree sicure:
/* 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";
}Testare la tua configurazione
Dopo aver configurato adjustMarginsForEdgeToEdge, testa il tuo app su:
- Dispositivi Android 15+ - Verifica che il contenuto rispetti correttamente le barre del sistema
- Versioni Android più vecchie - Assicurati della compatibilità con le versioni precedenti
- Diversi dimensioni dello schermo - Verifica che i layout funzionino su dispositivi diversi
- Tempi e temi scuri - Testare entrambe le modalità di tema
Errori comuni da evitare
Non utilizzare plugin per questo
Non hai bisogno di plugin di terze parti come capacitor-edge-to-edge o simili. La configurazione nativa gestisce questo in modo pulito. Se hai bisogno di un controllo fine-granulare sulla barra di navigazione del sistema dopo aver abilitato adjustMarginsForEdgeToEdge, @capgo/@capacitor-barra-di-navigazione e @
capgo/indicatore-di-casa completare la configurazione nativa senza sostituirlo.
Non mescolare con implementazioni manuali
Se stai utilizzando adjustMarginsForEdgeToEdge, elimina qualsiasi gestione manuale degli insetti della finestra o hack CSS che hai aggiunto.
Don’t Dimenticare CSS di Area Sicura
La configurazione gestisce gli aggiustamenti di margine, ma è necessario utilizzare gli insetti di area sicura CSS per un padding del contenuto corretto.
Guida di Migrazione
Se stai utilizzando attualmente plugin o hack per edge-to-edge:
- Elimina qualsiasi plugin per edge-to-edge da le tue dipendenze
- Aggiungi l'opzione di configurazione a
capacitor.config.ts - Pulisci e ricostruisci il tuo progetto Android
- Testa accuratamente su dispositivi target
# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..
# Rebuild
npx cap copy android
npx cap open androidFuture-Proofing
Ricordate che Capacitor 8 sarà il valore predefinito. Per prepararsi: "auto" Testate con
- ora
"auto"per individuare eventuali problemi fin da subito Aggiornate il vostro CSS - per gestire le aree sicure in modo corretto Verificate le vostre impostazioni di layout
- su dispositivi abilitati per schermi da bordo a bordo Risorse aggiuntive
Documentazione ufficiale del __CAPGO_KEEP_0__ Config
- Official Capacitor Config Documentation
- Linee guida Android Edge-to-Edge
- CSS Margini di sicurezza dell'area
Conclusioni
L'uso di un display edge-to-edge in Capacitor non richiede plugin, hack o complicati workaround. L'opzione di configurazione fornisce una soluzione pulita e nativa che è ufficialmente supportata e futura-proof. adjustMarginsForEdgeToEdge Inizia con
per la maggior parte delle app, testa accuratamente su diversi dispositivi e aggiungi CSS di sicurezza appropriato. La tua app sarà pronta per Android 15 e oltre con minimo sforzo. "auto" Hai domande o stai incontrando problemi?
La comunità di __CAPGO_KEEP_0__ e la The Capacitor community and sono risorse eccellenti per ulteriore aiuto. Continua dall'uso del display edge-to-edge in __CAPGO_KEEP_0__ senza plugin
edge-to-edge display in Capacitor doesn’t require plugins, hacks, or complicated workarounds. The configuration option provides a clean, native solution that’s officially supported and future-proof.
If sei stai utilizzando Edge-to-Edge Display senza plugin in Capacitor per pianificare il comportamento nativo dei media e dell'interfaccia, connettilo con Utilizzando @capgo/capacitor-live-attività per la capacità nativa in Utilizzando @capgo/capacitor-live-attività @capgo/capacitor-live-attività per il dettaglio di implementazione in @capgo/capacitor-live-attività Utilizzando @capgo/capacitor-player-video per la capacità nativa in Utilizzando @capgo/capacitor-player-video @capgo/capacitor-player-video per il dettaglio di implementazione in @capgo/capacitor-player-video, e Utilizzando @capgo/capacitor-navigazione-nativa per la capacità nativa in Utilizzo di @capgo/capacitor-navigazione nativa.
