Visualizzazione edge-to-edge in Capacitor senza plugin

Vuoi implementare il display edge-to-edge nella tua app Capacitor? Non avrai bisogno di hack, plugin o workaround. Capacitor supporta ufficialmente l'edge-to-edge display tramite il adjustMarginsForEdgeToEdge opzione di configurazione: semplicemente non è molto documentata.

Molti sviluppatori hanno difficoltà con i layout edge-to-edge nelle app Capacitor, soprattutto quando puntano ad Android 15+. Spesso ricorrono a plugin custom o hack CSS per ottenere il moderno look edge-to-edge. Ma esiste un modo nativo migliore.

Che cos'è l'Edge-to-Edge Display?

L'edge-to-edge display permette al contenuto dell'app di estendersi dietro le barre di sistema (status bar e navigation bar), creando un'esperienza UI più immersiva e moderna. A partire da Android 15, Google sta rendendo l'edge-to-edge lo standard per tutte le app.

La soluzione ufficiale: adjustMarginsForEdgeToEdge

Capacitor fornisce l' adjustMarginsForEdgeToEdge opzione di configurazione specifica per questo scopo. È documentata nella documentazione ufficiale della config di Capacitor, ma è facile non notarla.

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;

O in formato JSON:

{
  "appId": "com.example.app",
  "appName": "My App",
  "webDir": "dist",
  "android": {
    "adjustMarginsForEdgeToEdge": "auto"
  }
}

Opzioni di configurazione

Il adjustMarginsForEdgeToEdge l'opzione accetta tre valori:

1. "auto" (Consigliato)

adjustMarginsForEdgeToEdge: 'auto'

What it does: Controlla automaticamente Android 15+ e l'impostazione windowOptOutEdgeToEdgeEnforcement Adatta i margini in modo intelligente in base al dispositivo e alla configurazione.

Ideale per: La maggior parte delle app in produzione che vogliono l'edge-to-edge sui dispositivi supportati, mantenendo la compatibilità con le versioni precedenti di Android.

2. "force"

adjustMarginsForEdgeToEdge: 'force'

What it does: Imposta forzatamente i margini per l'edge-to-edge, indipendentemente dalla versione di Android o da altre impostazioni.

Ideale per: App che richiedono il comportamento edge-to-edge su tutte le versioni Android supportate.

3. "disable"

adjustMarginsForEdgeToEdge: 'disable'

What it does: Disabilita completamente la regolazione automatica dei margini.

Ideale per: App che gestiscono il layout edge-to-edge manualmente o che non lo richiedono.

Nota: Attualmente "disable" è il default, ma cambierà in "auto" con Capacitor 8.

Perché è importante per Android 15+

A partire da Android 15, Google imporrà l'edge-to-edge display come comportamento predefinito. Le app che non gestiscono correttamente i layout edge-to-edge potrebbero presentare problemi di UI come:

• Contenuti nascosti dietro le barre di sistema
• Spaziatura e padding errati
• Aspetto inconsistente tra i dispositivi
• Esperienza utente scadente

Utilizzando l'ufficiale adjustMarginsForEdgeToEdge config, assicuri che la tua app gestisca correttamente questi cambiamenti senza code personalizzati.

Esempio completo

Ecco un esempio completo di configurazione per un'app Capacitor moderna:

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 usi il display edge-to-edge, potresti dover aggiungere del CSS per gestire le 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";
}

Test della configurazione

Dopo la configurazione adjustMarginsForEdgeToEdge, testa la tua app su:

1. dispositivi Android 15+ - Verifica che i contenuti rispettino le system bars
2. Versioni Android precedenti - Garantisci la retrocompatibilità
3. Diverse dimensioni dello schermo - Verifica il layout su vari dispositivi
4. Temi light e dark - Testa entrambi i temi

Errori comuni da evitare

Non usare plugin per questo

Non servono plugin di terze parti come capacitor-edge-to-edge o simili. La configurazione nativa gestisce tutto in modo pulito. Se hai bisogno di un controllo granulare sul system chrome dopo l'abilitazione adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar e @capgo/home-indicator possono integrare la configurazione nativa senza sostituirla.

Non mixare con implementazioni manuali

Se stai usando adjustMarginsForEdgeToEdge, rimuovi qualsiasi gestione manuale dei window insets o hack CSS che potresti aver aggiunto.

Non dimenticare il CSS Safe Area

La configurazione gestisce gli aggiustamenti dei margini, ma dovrai comunque usare i CSS safe area insets per il padding corretto dei contenuti.

Guida alla migrazione

Se stai usando plugin o hack per l'edge-to-edge:

1. Rimuovi i plugin edge-to-edge dalle tue dipendenze
2. Aggiungi l'opzione di config al tuo capacitor.config.ts
3. Pulisci e ricostruisci il tuo progetto Android
4. Testa a fondo sui dispositivi target

# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..

# Rebuild
npx cap copy android
npx cap open android

Pensare al futuro

Ricorda che Capacitor 8 imposterà "auto" il valore predefinito. Per prepararti:

1. Testa con "auto" ora per individuare eventuali problemi subito
2. Aggiorna il tuo CSS per gestire correttamente le safe areas
3. Controlla i tuoi layout sui dispositivi con edge-to-edge abilitato

Risorse aggiuntive

• Documentazione ufficiale per la configurazione Capacitor
• Linee guida Android Edge-to-Edge
• CSS Safe Area Insets

Conclusione

L'edge-to-edge display in Capacitor non richiede plugin, hack o workaround complicati. Il adjustMarginsForEdgeToEdge l'opzione di configurazione offre una soluzione nativa pulita, ufficialmente supportata e a prova di futuro.

Inizia con "auto" per la maggior parte delle app, testa a fondo su più dispositivi e aggiungi il CSS per le safe area. La tua app sarà pronta per Android 15 e oltre con il minimo sforzo.

Hai domande o riscontri problemi? La community di Capacitor e documentazione ufficiale sono ottime risorse per un aiuto in più.

Continua da Edge-to-Edge Display in Capacitor senza plugin

Se stai usando Visualizzazione edge-to-edge in Capacitor senza plugin per pianificare il comportamento dei media nativi e dell'interfaccia, collegalo a Uso di @capgo/capacitor-live-activities per la funzionalità nativa nella pagina Uso di @capgo/capacitor-live-activities, @capgo/capacitor-live-activities per il dettaglio implementativo in @capgo/capacitor-live-activities, Uso di @capgo/capacitor-video-player per la funzionalità nativa in Utilizzo di @capgo/capacitor-video-player, @capgo/capacitor-video-player per i dettagli di implementazione in @capgo/capacitor-video-player, e Usando @capgo/capacitor-native-navigation per la funzionalità nativa in Usando @capgo/capacitor-native-navigation.