Trying to implement edge-to-edge display in your Capacitor app? You don’t need any hacks, plugins, or workarounds. Capacitor has official support for edge-to-edge display through the adjustMarginsForEdgeToEdge opsi konfigurasi - itu hanya tidak terdokumentasikan secara luas.
Banyak pengembang kesulitan dengan tata letak sisi samping di aplikasi Capacitor, terutama ketika menghadapi Android 15+. Mereka sering menggunakan plugin atau CSS yang tidak biasa untuk mencapai tampilan modern sisi samping. Tapi ada cara yang lebih baik, native.
Apa itu Tampilan Sisi Samping?
Tampilan sisi samping memungkinkan konten aplikasi Anda untuk meluas di balik bar sistem (bar status dan bar navigasi), menciptakan pengalaman UI yang lebih imersif dan modern. Mulai dari Android 15, Google mendorong tampilan sisi samping sebagai standar untuk semua aplikasi.
Solusi Resmi: adjustMarginsForEdgeToEdge
Capacitor menyediakan adjustMarginsForEdgeToEdge opsi konfigurasi khusus untuk tujuan ini. Ini terdokumentasi dalam documentasi konfigurasi Capacitor resmitetapi mudah untuk terlewatkan.
Bagaimana Cara Mengkonfigurasinya
Tambahkan ini ke capacitor.config.ts atau 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;atau
{
"appId": "com.example.app",
"appName": "My App",
"webDir": "dist",
"android": {
"adjustMarginsForEdgeToEdge": "auto"
}
}Konfigurasi Pilihan
Opsi adjustMarginsForEdgeToEdge opsi ini menerima tiga nilai:
1. "auto" (Dianjurkan)
adjustMarginsForEdgeToEdge: 'auto'Apa yang dilakukan: Mengatur secara otomatis untuk Android 15+ dan windowOptOutEdgeToEdgeEnforcement pengaturan. Mengatur margin secara cerdas berdasarkan perangkat dan konfigurasi.
Terbaik untuk: Sebagian besar aplikasi produksi yang ingin edge-to-edge pada perangkat yang didukung sambil menjaga konsistensi dengan versi Android yang lebih tua.
2. "force"
adjustMarginsForEdgeToEdge: 'force'Apakah itu: Menggunakan penyesuaian margin untuk edge-to-edge tanpa mempertimbangkan versi Android atau pengaturan lainnya.
Terbaik untuk: Aplikasi yang ingin perilaku edge-to-edge di semua versi Android yang didukung.
3. "disable"
adjustMarginsForEdgeToEdge: 'disable'Apakah itu: Menghapus penyesuaian margin otomatis sepenuhnya.
Terbaik untuk: Aplikasi yang mengelola tata letak edge-to-edge secara manual atau tidak ingin perilaku edge-to-edge.
Penting: Saat ini "disable" is merupakan default, tetapi ini akan berubah menjadi "auto" dalam Capacitor 8.
Mengapa Ini Penting untuk Android 15+
Mulai dengan Android 15, Google menerapkan tampilan tepi ke tepi sebagai perilaku default. Aplikasi yang tidak menghandle layout tepi ke tepi dengan benar mungkin mengalami masalah UI seperti:
- Konten disembunyikan di balik bar sistem
- Spasi dan padding yang tidak nyaman
- Tampilan yang tidak konsisten di berbagai perangkat
- Pengalaman pengguna yang buruk
Dengan menggunakan konfigurasi resmi adjustMarginsForEdgeToEdge anda memastikan aplikasi Anda menghandle perubahan ini dengan benar tanpa custom code.
Contoh Lengkap
Berikut adalah contoh konfigurasi lengkap untuk aplikasi modern 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;Konsiderasi CSS
Menggunakan layar tepi-tepi, Anda mungkin perlu menambahkan beberapa CSS untuk mengatasi area aman:
/* 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";
}Pengujian Konfigurasi Anda
Setelah mengonfigurasi adjustMarginsForEdgeToEdge, uji aplikasi Anda pada:
- Perangkat Android 15+ - Pastikan konten dengan benar menghormati sistem bar
- Versi Android yang lebih tua - Pastikan kembali kompatibilitas
- Ukuran layar yang berbeda - Verifikasi tata letak bekerja di perangkat yang berbeda
- Templat terang dan gelap - Uji keduanya tema mode
Menghindari Kesalahan Umum
Jangan Gunakan Plugin untuk Ini
Kamu tidak memerlukan plugin pihak ketiga seperti capacitor-edge-to-edge atau yang serupa. Konfigurasi native mengelola hal ini dengan baik. Jika kamu memerlukan kontrol yang lebih halus atas sistem chrome setelah mengaktifkan adjustMarginsForEdgeToEdge, @capgo/capacitor-bar navigasi dan @capgo/home-indicator @__CAPGO_KEEP_0__/indikator home
menambahkan konfigurasi native tanpa menggantikannya.
Jangan Campur dengan Implementasi Manual adjustMarginsForEdgeToEdgeJika kamu menggunakan
Jangan Lupa CSS Area Aman
Konfigurasi mengatur penyesuaian margin, tetapi Anda masih perlu menggunakan inset CSS area aman untuk padding konten yang tepat.
Panduan Pemindahan
Jika Anda saat ini menggunakan plugin atau trik untuk edge-to-edge:
- Hapus plugin edge-to-edge apa pun dari dependensi Anda
- Tambahkan opsi konfigurasi ke
capacitor.config.ts - Sederhanakan dan bangun kembali projek Android Anda
- Uji secara menyeluruh pada perangkat target
# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..
# Rebuild
npx cap copy android
npx cap open androidMengantisipasi Masa Depan
Ingat bahwa Capacitor 8 akan membuat nilai default. Untuk mempersiapkan: "auto" Tes dengan
- saat ini
"auto"untuk menangkap masalah-masalah sejak awal Perbarui CSS Anda - untuk menghandle area-area yang aman dengan benar Ulas ulasan layout Anda
- pada perangkat yang diaktifkan edge-to-edge Sumber Daya Tambahan
Dokumentasi Konfigurasi __CAPGO_KEEP_0__ Resmi
Kesimpulan
Tampilan Edge-to-Edge di Capacitor tidak memerlukan plugin, trik, atau cara kerja yang rumit. Opsi pengaturan memberikan solusi yang bersih dan asli yang mendapatkan dukungan resmi dan tahan lama. adjustMarginsForEdgeToEdge Mulai dengan
untuk aplikasi kebanyakan, lakukan tes secara menyeluruh di berbagai perangkat, dan tambahkan CSS area yang aman yang sesuai. Aplikasi Anda akan siap untuk Android 15 dan ke depannya dengan usaha yang minimal. "auto" Pertanyaan atau mengalami masalah?
Masyarakat __CAPGO_KEEP_0__ dan The Capacitor community and merupakan sumber tambahan yang baik untuk bantuan tambahan. Teruskan dari Tampilan Edge-to-Edge di __CAPGO_KEEP_0__ Tanpa Plugin
Keep going from Edge-to-Edge Display in Capacitor Without Plugins
If Anda menggunakan Edge-to-Edge Display in Capacitor Without Plugins untuk merencanakan perilaku media dan antarmuka asli, hubungkannya dengan Menggunakan @capgo/capacitor-aktivitas-hidup untuk kemampuan asli dalam Menggunakan @capgo/capacitor-aktivitas-hidup, @capgo/capacitor-aktivitas-hidup untuk detail implementasi dalam @capgo/capacitor-aktivitas-hidup, Menggunakan @capgo/capacitor-pemain-video untuk kemampuan asli dalam Menggunakan @capgo/capacitor-pemain-video, @capgo/capacitor-pemain-video untuk detail implementasi dalam @capgo/capacitor-pemain-video, dan Menggunakan @capgo/capacitor-navigasi-asli untuk kemampuan asli dalam Menggunakan @capgo/capacitor-native-navigation.
