Display di Confine in Capacitor Senza Plugin

Stai cercando di implementare il display di confine nella tua Capacitor app? Non hai bisogno di hack, plugin o workarounds. Capacitor supporta nativamente il display di confine attraverso l' adjustMarginsForEdgeToEdge opzione di configurazione - è solo poco documentata.

Molti sviluppatori si scontrano con le impostazioni di layout di confine nelle Capacitor app, soprattutto quando si mira a Android 15+. Spesso ricorrono a plugin o hack CSS per ottenere l'aspetto moderno del display di confine. Ma esiste una via migliore, nativa.

What is Display a Schermo Intero?

Display a schermo intero 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 lo schermo intero come standard per tutte le app.

La Soluzione Ufficiale: regolare i margini per lo schermo intero

Capacitor fornisce l'opzione di configurazione specifica per questo scopo. Ciò è documentato nella documentazione di configurazione Capacitor ufficiale adjustMarginsForEdgeToEdge ma è facile perdere. official Capacitor config documentationAggiungi questo al tuo

o

O in formato JSON: capacitor.config.ts Opzioni di Configurazione 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;

options

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

or

L'opzione accetta tre valori: adjustMarginsForEdgeToEdge (Consigliato)

1. "auto" Cosa fa:

adjustMarginsForEdgeToEdge: 'auto'

Verifica automaticamente Android 15+ e la 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 un edge-to-edge su dispositivi supportati, mantenendo la compatibilità con versioni Android più vecchie. Cosa fa:

2. "force"

adjustMarginsForEdgeToEdge: 'force'

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

Gli app che desiderano il comportamento edge-to-edge su tutte le versioni Android supportate. __CAPGO_KEEP_0__

3. "disable"

adjustMarginsForEdgeToEdge: 'disable'

Cosa fa: Disabilita completamente gli aggiustamenti automatici dei margini.

Migliore per: Applicazioni che gestiscono manualmente la disposizione di layout a schermo intero o non desiderano il comportamento a schermo intero.

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

Perché Questo Importa per Android 15+

A partire da Android 15, Google sta imponendo il display a schermo intero come comportamento predefinito. Le app che non gestiscono correttamente le disposizioni di layout a schermo intero possono 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'interfaccia ufficiale adjustMarginsForEdgeToEdge config, assicuri che il tuo app gestisca correttamente questi cambiamenti senza personalizzare 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 di tipo edge-to-edge, 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:

1. Dispositivi Android 15+ - Assicurati che il contenuto rispetti correttamente le barre del sistema
2. Versioni Android più vecchie - Assicurati la compatibilità con versioni precedenti
3. Diversi dimensioni schermo - Verifica che i layout funzionino su dispositivi diversi
4. Temi 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.

Non mescolare con implementazioni manuali

If sei stai utilizzando adjustMarginsForEdgeToEdge, elimina eventuali trattamenti manuali degli insetti della finestra o hack CSS che potresti aver aggiunto.

Non dimenticare CSS Safe Area

Il config 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 edge-to-edge:

1. Elimina eventuali plugin edge-to-edge da le tue dipendenze
2. Aggiungi l'opzione di config a capacitor.config.ts
3. Pulisci e ricostruisci il tuo progetto Android
4. Testare accuratamente su dispositivi di destinazione

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

# Rebuild
npx cap copy android
npx cap open android

Future-Proofing

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

1. Testa con "auto" adesso per catturare eventuali problemi presto
2. Aggiorna il tuo CSS per gestire le aree sicure correttamente
3. Verifica le tue impostazioni su dispositivi abilitati per schermi a bordo-pista

Risorse aggiuntive

• Documentazione ufficiale del file di configurazione Capacitor
• Linee guida per Android Edge-to-Edge
• CSS Spazi sicuri dell'area

Conclusioni

L'uso di un display edge-to-edge con 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 dispositivi diversi e aggiungi CSS di area sicura appropriato. La tua app sarà pronta per Android 15 e oltre con un minimo sforzo. "auto" Domande o problemi di esecuzione?

La comunità di __CAPGO_KEEP_0__ e la The Capacitor community and __CAPGO_KEEP_0__ sono grandi risorse per ulteriore aiuto.

Continua dall'Capacitor Display senza plugin

Se stai utilizzando Display senza plugin dell'Capacitor per pianificare il comportamento di media e interfaccia nativa, connettilo con Usando @capgo/capacitor-attività-in-vivo per la capacità nativa in Usando @capgo/capacitor-attività-in-vivo, @capgo/capacitor-attività-in-vivo per il dettaglio di implementazione in @capgo/capacitor-attività-in-vivo, Usando @capgo/capacitor-lettore-di-video per la capacità nativa in Usando @capgo/capacitor-lettore-di-video, @capgo/capacitor-lettore-di-video per i dettagli di implementazione in @capgo/capacitor-video-player, e Usando @capgo/capacitor-native-navigation per la capacità nativa in Usando @capgo/capacitor-native-navigation.