Schermo da bordo a bordo in Capacitor senza plugin

Learn how to properly configure edge-to-edge display in your Capacitor apps using the official adjustMarginsForEdgeToEdge config option - no plugins or hacks needed. Impara a configurare correttamente il display a schermo intero nei tuoi app Capacitor utilizzando l'opzione di configurazione ufficiale adjustMarginsForEdgeToEdge - non sono necessari plugin o hack di alcun tipo. adjustMarginsForEdgeToEdge opzione di configurazione - semplicemente non è molto documentata.

Molti sviluppatori hanno difficoltà con gli schemi edge-to-edge nei loro app Capacitor, 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'è una via migliore, nativa.

Cosa è lo Schermo Edge-to-Edge?

Gli schermi edge-to-edge consentono al contenuto delle 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 spingendo lo schermo edge-to-edge come standard per tutte le app.

La Soluzione Ufficiale: adjustMarginsForEdgeToEdge

Capacitor fornisce l' adjustMarginsForEdgeToEdge opzione di configurazione specifica per questo scopo. Questo è documentato nella documentazione di configurazione ufficiale di Capacitor, ma è facile da perdere.

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;

Ora 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'

Cosa fa: Verifica automaticamente Android 15+ e l'impostazione. Adatta le margine in modo intelligente in base al dispositivo e alla configurazione. windowOptOutEdgeToEdgeEnforcement Migliore per:

La maggior parte degli app di produzione che desiderano l'edge-to-edge su dispositivi supportati, mantenendo la compatibilità con versioni Android più vecchie. Cosa fa:

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

Impone l'aggiustamento delle margine per l'edge-to-edge indipendentemente dalla versione di Android o da altre impostazioni. Cosa fa:

Per chi è più adatto: Le app che desiderano un comportamento edge-to-edge su tutte le versioni di Android supportate.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

Di cosa si tratta: Disabilita completamente gli aggiustamenti automatici dei margini.

Per chi è più adatto: Le app che gestiscono manualmente la disposizione edge-to-edge o non desiderano il comportamento edge-to-edge.

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

Perché è importante per Android 15+

Iniziando con Android 15, Google sta imponendo il display edge-to-edge come comportamento predefinito. Le app che non gestiscono correttamente le disposizioni edge-to-edge potrebbero sperimentare problemi di interfaccia utente come:

Contenuto nascosto dietro le barre di sistema
Spaziatura e padding scomodi
Aspetto non coerente su dispositivi diversi
Pessima esperienza utente

Utilizzando l'opzione ufficiale adjustMarginsForEdgeToEdge configurazione, assicuri che il tuo app gestisca correttamente questi cambiamenti senza dover utilizzare code.

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 un display a schermo intero, potresti dover 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";
}

Test della Configurazione

Dopo aver configurato adjustMarginsForEdgeToEdgetestare il tuo app su:

dispositivi Android 15+ - Verificare che il contenuto rispetti correttamente le barre del sistema
Versioni Android più vecchie - Assicurarsi della compatibilità con i sistemi precedenti
Diversi dimensioni dello schermo - Verificare che i layout funzionino su dispositivi diversi
Temi chiaro e scuro - Testare entrambi i modi 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 sullo sfondo del sistema dopo aver abilitato adjustMarginsForEdgeToEdge, @capgo/capacitor-barra di navigazione e @capgo/indicatore di home completare la configurazione nativa senza sostituirlo.

Non Mescolare con Implementazioni Manuali

Se stai utilizzando adjustMarginsForEdgeToEdge, rimuovi eventuali trattamenti manuali degli insetti della finestra o hack CSS che potresti aver aggiunto.

Non Dimenticare CSS di Area Sicura

La configurazione gestisce gli aggiustamenti di margine, ma hai ancora bisogno di utilizzare gli insetti CSS di area sicura per un padding del contenuto corretto.

Guida di Migrazione

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

Elimina tutti i plugin edge-to-edge dal tuo set di dipendenze
Aggiungi l'opzione di configurazione a tuo 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 android

Preparazione per il futuro

Ricorda che Capacitor 8 farà "auto" il valore predefinito. Per prepararsi:

Testa con "auto" ora per catturare eventuali problemi in anticipo
Aggiorna il tuo CSS per gestire le aree sicure in modo corretto
Verifica le tue impostazioni di layout su dispositivi abilitati per schermi a bordo

Risorse aggiuntive

Conclusioni

L'uso di schermi a bordo in Capacitor non richiede plugin, hack o complicati workaround. Il adjustMarginsForEdgeToEdge opzione di configurazione fornisce una soluzione nativa pulita che è ufficialmente supportata e futura.

Inizia con "auto" per la maggior parte delle app, testa accuratamente su dispositivi diversi e aggiungi CSS di area sicura appropriata. La tua app sarà pronta per Android 15 e oltre con sforzo minimo.

Domande o problemi di esecuzione? Il community di Capacitor e la documentazione ufficiale sono eccellenti risorse per ulteriore aiuto.

Continua da Edge-to-Edge Display in Capacitor Senza Plugin

Se stai utilizzando Edge-to-Edge Display in Capacitor Senza Plugin per pianificare il comportamento dei media e dell'interfaccia nativa, connettilo con Utilizza @capgo/capacitor-live-attività per la capacità nativa in Utilizzo di @capgo/capacitor-live-attivitàs @capgo/capacitor-live-attivitàs per il dettaglio di implementazione in @capgo/capacitor-live-attivitàs Utilizzo di @capgo/capacitor-player-video per la capacità nativa in Utilizzo di @capgo/capacitor-player-video @capgo/capacitor-player-video per il dettaglio di implementazione in @capgo/capacitor-player-video, e Utilizzo di @capgo/capacitor-navigazione-nativa per la capacità nativa in Utilizzo di @capgo/capacitor-navigazione-nativa.

Edge-to-Edge Display in Capacitor Without Plugins