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 - yang tidak terlalu banyak dokumentasi.
Many developers struggle with edge-to-edge layouts in Capacitor apps, especially when targeting Android 15+. They often resort to custom plugins or CSS hacks to achieve the modern edge-to-edge look. But there’s a better, native way.
Apa itu Tampilan Sisi-Sisi Penuh?
Tampilan sisi-sisi penuh memungkinkan konten aplikasi Anda untuk memanjang di balik bar sistem (status bar dan navigation bar), menciptakan pengalaman UI yang lebih imersif dan modern. Mulai dari Android 15, Google mempromosikan tampilan sisi-sisi penuh sebagai standar untuk semua aplikasi.
Solusi Resmi: adjustMarginsForEdgeToEdge
Capacitor provides the adjustMarginsForEdgeToEdge Pilihan konfigurasi khusus untuk tujuan ini. Ini terdokumentasi di Panduan Dokumentasi Konfigurasi Capacitor ResmiTapi mudah dilupakan.
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;Bagaimana Cara Mengkonfigurasinya
{
"appId": "com.example.app",
"appName": "My App",
"webDir": "dist",
"android": {
"adjustMarginsForEdgeToEdge": "auto"
}
}Pilihan Konfigurasi
Opsi ini menerima tiga nilai: adjustMarginsForEdgeToEdge Dianjurkan
1. "auto" Apa yang dilakukan:
adjustMarginsForEdgeToEdge: 'auto'Apa yang dilakukan: Memeriksa secara otomatis untuk Android 15+ dan windowOptOutEdgeToEdgeEnforcement Mengatur margin dengan cerdas berdasarkan perangkat dan konfigurasi.
Terbaik untuk: Aplikasi produksi yang paling banyak yang ingin edge-to-edge pada perangkat yang didukung sambil menjaga konsistensi dengan versi Android yang lebih lama.
2. "force"
adjustMarginsForEdgeToEdge: 'force'Apa yang dilakukan: Menggunakan penyesuaian margin secara paksa 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'Apa yang dilakukan: Menghapus penyesuaian margin otomatis sepenuhnya.
Terbaik untuk: Aplikasi yang menghandle tata letak edge-to-edge secara manual atau tidak ingin perilaku edge-to-edge.
Catatan: Saat ini "disable" adalah 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
Sini ada 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;Pertimbangan CSS
Ketika 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";
}Tes Konfigurasi Anda
Setelah mengonfigurasi adjustMarginsForEdgeToEdge, tes aplikasi Anda di:
- Perangkat Android 15+ - Periksa apakah konten dengan benar menghormati bar sistem
- Versi Android yang lebih tua - Pastikan kembali kompatibilitas
- Ukuran layar yang berbeda - Pastikan tata letak bekerja di perangkat-perangkat yang berbeda
- Templat Cahaya dan Tema Gelap - Uji mode tema baiklah
Kesalahan Umum untuk Dihindari
Tidak Menggunakan Plugin untuk Ini
Kamu tidak memerlukan plugin pihak ketiga seperti capacitor-edge-to-edge atau yang mirip. Konfigurasi native mengatasi hal ini dengan bersih. Jika kamu memerlukan kontrol yang 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.
Jika Anda menggunakan adjustMarginsForEdgeToEdgeHapus semua pengaturan jendela manual atau trik CSS yang telah Anda tambahkan.
Tidak Lupa CSS Area Aman
Pengaturan ini mengatur penyesuaian margin, tetapi Anda masih perlu menggunakan CSS area aman untuk memperoleh padding konten yang tepat.
Petunjuk Pindah
Jika Anda saat ini menggunakan plugin atau trik untuk edge-to-edge:
- Hapus semua plugin edge-to-edge dari dependensi Anda
- Tambahkan opsi pengaturan ke dalam
capacitor.config.ts - Membersihkan dan membangun ulang projek Android Anda
- Tes 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
Ingatlah bahwa Capacitor 8 akan membuat "auto" nilai default. Untuk mempersiapkan:
- Tes dengan
"auto"saat ini untuk menangkap masalah-masalah sejak awal - Perbarui CSS Anda untuk menghandle area-area yang aman dengan benar
- Ulas kembali tata letak Anda pada perangkat yang diaktifkan edge-to-edge
Sumber Tambahan
- Dokumentasi Konfigurasi Resmi Capacitor
- Pedoman Android untuk Layar Sisi Samping
- CSS Margin Aman Area
Kesimpulan
Layar sisi samping di Capacitor tidak memerlukan plugin, trik, atau cara kerja yang rumit. Opsi konfigurasi menyediakan solusi yang bersih dan asli yang mendapat dukungan resmi dan tahan lama. adjustMarginsForEdgeToEdge Mulai dengan
untuk aplikasi kebanyakan, lakukan tes secara menyeluruh di berbagai perangkat, dan tambahkan CSS area aman yang sesuai. Aplikasi Anda akan siap untuk Android 15 dan seterusnya dengan usaha yang minimal. "auto" Pertanyaan atau mengalami masalah?
Masyarakat __CAPGO_KEEP_0__ dan The Capacitor community and __CAPGO_KEEP_0__ Sumber daya ini sangat berguna untuk bantuan tambahan.
Teruskan dari Display Edge-to-Edge di Capacitor Tanpa Plugin
Jika Anda menggunakan Display Edge-to-Edge di Capacitor Tanpa Plugin Untuk merencanakan perilaku media dan antarmuka asli, hubungkannya dengan Menggunakan @capgo/capacitor-aktivitas-hidup untuk kemampuan asli di Menggunakan @capgo/capacitor-aktivitas-hidup @capgo/capacitor-aktivitas-hidup untuk detail implementasi di @capgo/capacitor-aktivitas-hidup Menggunakan @capgo/capacitor-pemain-video untuk kemampuan asli di Menggunakan @capgo/capacitor-pemain-video @capgo/capacitor-pemain-video untuk detail implementasi di @capgo/capacitor-video-player, dan Menggunakan @capgo/capacitor-native-navigation untuk kemampuan asli di Menggunakan @capgo/capacitor-native-navigation.
