Schermo da bordo a bordo in Capacitor senza plugin

Stai cercando di implementare il display da bordo a bordo nella tua Capacitor app? Non hai bisogno di hack, plugin o workarounds. Capacitor supporta ufficialmente il display da bordo a bordo attraverso adjustMarginsForEdgeToEdge opzione di configurazione - semplicemente non è molto documentata.

Molti sviluppatori hanno difficoltà con gli schemi di layout 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'è un modo migliore, nativo.

Cosa è la Display Edge-to-Edge?

La display edge-to-edge consente al contenuto dell'app di estendersi dietro le barre del 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 l'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 Capacitor, ma è 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;

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"` (Raccomandato)

adjustMarginsForEdgeToEdge: 'auto'

Cosa fa: Controlla automaticamente Android 15+ e la windowOptOutEdgeToEdgeEnforcement impostazione. Adatta le margine in modo intelligente in base al dispositivo e alla configurazione.

Migliore per: La maggior parte degli app di produzione che desiderano un edge-to-edge su dispositivi supportati mentre mantengono la compatibilità con versioni Android più vecchie.

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

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

Migliore per: Applicazioni che desiderano un comportamento edge-to-edge su tutte le versioni di Android supportate.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

Cosa fa: Disabilita completamente gli aggiustamenti di margine automatici.

Migliore per: Applicazioni 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" in Capgo Capacitor 8.

Perché Questo Importa per Android 15+

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

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

Utilizzando l'interfaccia ufficiale adjustMarginsForEdgeToEdge config, assicuri che il tuo app gestisca correttamente questi cambiamenti senza un code personalizzato.

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 senza bordi, 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, test your app on:

dispositivi Android 15+ - Assicurati che il contenuto rispetti correttamente le barre del sistema
Versioni Android più vecchie - Assicurati della compatibilità a ritroso
Dimensioni schermo diverse - Verifica che i layout funzionino su dispositivi diversi
Tempi chiaro e scuro - Testa entrambi i modi di tema

Mistake 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 dei titoli del sistema dopo aver abilitato adjustMarginsForEdgeToEdge, @capgo/@capacitor-barra_di_navigazione e @capgo/indicatore_di_casa completano la configurazione nativa senza sostituirlo.

Non Mescolare con Implementazioni Manuali

Se stai utilizzando adjustMarginsForEdgeToEdge, elimina qualsiasi gestione manuale degli insetti della finestra o gli hack CSS che hai aggiunto.

Non Dimenticare CSS di Area di Sicurezza

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

Guida di Migrazione

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

Elimina i plugin senza bordi a bordo da le tue dipendenze
Aggiungi l'opzione di configurazione al 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 rilevare eventuali problemi fin da subito
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 L'opzione di configurazione fornisce una soluzione pulita e nativa che è supportata ufficialmente e futura-proof.

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

Hai domande o stai incontrando problemi? La comunità e la documentazione ufficiale di Capacitor sono ottimi risorse per ulteriore aiuto. Continua dall'Edge-to-Edge Display in __CAPGO_KEEP_0__ 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 Usando @Capacitor/__CAPGO_KEEP_1__-live-activities Pianifica il tuo progetto con __CAPGO_KEEP_0__ e ottieni il massimo dalle funzionalità native Using @capgo/capacitor-live-activities For la capacità nativa in Utilizzo di @capgo/capacitor-live-activities, @capgo/capacitor-live-activities Per il dettaglio di implementazione in @capgo/capacitor-live-activities, Utilizzo di @capgo/capacitor-video-player Per la capacità nativa in Utilizzo di @capgo/capacitor-video-player, @capgo/capacitor-video-player Per il dettaglio di implementazione in @capgo/capacitor-video-player, e Utilizzo di @capgo/capacitor-native-navigation Per la capacità nativa in Utilizzo di @capgo/capacitor-native-navigation.

Display da bordo a bordo in Capacitor Senza Plugin