Tampilan Layar Tanpa Batas di Capacitor Tanpa Menggunakan Plugin

Tampilan Tanpa Batas pada Capacitor Tanpa Plugin

Pelajari cara mengonfigurasi layar edge-to-edge dengan benar di aplikasi Capacitor Anda menggunakan opsi konfigurasi resmi adjustMarginsForEdgeToEdge - tidak perlu plugin atau trik.

Kredit artikel

Martin Donadieu

Penulis

Valeria

Pengulas

Jordan

Editor

Mencoba untuk menerapkan layar edge-to-edge di aplikasi Capacitor Anda? Anda tidak perlu menggunakan trik, plugin, atau kerja sama. Capacitor memiliki dukungan resmi untuk layar tanpa batas melalui adjustMarginsForEdgeToEdge opsi konfigurasi - itu hanya tidak terdokumentasikan secara luas.

Beberapa pengembang kesulitan dengan tata letak edge-to-edge di aplikasi Capacitor, terutama ketika mengarahkan Android 15+. Mereka sering kali bergantung pada plugin khusus atau trik CSS untuk mencapai tampilan modern edge-to-edge. Tapi ada cara yang lebih baik, native.

Apa itu Display Edge-to-Edge?

Tampilan edge-to-edge memungkinkan konten aplikasi Anda untuk meluas di balik bar sistem (status bar dan bar navigasi), menciptakan pengalaman UI yang lebih imersif dan modern. Mulai dari Android 15, Google mendorong edge-to-edge sebagai standar untuk semua aplikasi.

Solusi Resmi: adjustMarginsForEdgeToEdge

Capacitor menyediakan adjustMarginsForEdgeToEdge opsi konfigurasi khusus untuk tujuan ini. Ini terdokumentasi dalam documentasi konfigurasi Capacitor resmi, tapi mudah untuk melewatinya.

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 dalam format JSON:

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

Opsi Konfigurasi

Konfigurasi adjustMarginsForEdgeToEdge Opsi ini menerima tiga nilai:

1. `"auto"` (Dianjurkan)

adjustMarginsForEdgeToEdge: 'auto'

Apakah yang dilakukan: Mengatur otomatis untuk memeriksa Android 15+ dan pengaturan. windowOptOutEdgeToEdgeEnforcement Mengatur margin cerdas berdasarkan perangkat dan konfigurasi.

Terbaik untuk: Aplikasi produksi yang paling banyak ingin edge-to-edge pada perangkat yang didukung sambil menjaga konsistensi dengan versi Android yang lebih tua.

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

Apakah yang dilakukan: Mengatur penyesuaian margin untuk layar edge-to-edge tanpa mempertimbangkan versi Android atau pengaturan lainnya.

Terbaik untuk: Aplikasi yang ingin perilaku tepi ke tepi di semua versi Android yang didukung.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

Apa yang dilakukan: Menghapus penyesuaian margin otomatis sepenuhnya.

Terbaik untuk: Aplikasi yang mengatur layout tepi ke tepi secara manual atau tidak ingin perilaku tepi ke tepi.

Note: Saat ini "disable" adalah default, tetapi ini akan berubah menjadi "auto" di 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 tata letak 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 Kamu pastikan aplikasi kamu menangani perubahan-perubahan ini dengan benar tanpa kode code.

Contoh Lengkap

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

Saat menggunakan layar edge-to-edge, kamu mungkin perlu menambahkan beberapa CSS untuk mengatasi area yang 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";
}

Menguji Konfigurasi Kamu

Sesudah mengonfigurasi adjustMarginsForEdgeToEdge, uji coba aplikasi kamu di:

Perangkat Android 15+ - Pastikan konten dengan benar menghormati bar sistem
Versi Android yang lebih tua - Pastikan kembali kompatibilitas
Ukuran layar yang berbeda Verifikasi tampilan bekerja di berbagai perangkat
Mode tema terang dan gelap - Uji coba mode tema baik

Kesalahan Umum untuk Dihindari

Tidak Menggunakan Plugin untuk Ini

Anda tidak memerlukan plugin pihak ketiga seperti capacitor-edge-to-edge atau serupa. Konfigurasi native mengatasi hal ini dengan baik. Jika Anda memerlukan kontrol halus atas chrome sistem setelah mengaktifkan adjustMarginsForEdgeToEdge, @capgo/capacitor-bar navigasi dan @capgo/home-indicator menambahkan konfigurasi native tanpa menggantinya.

Tidak Campurkan dengan Implementasi Manual

Jika Anda menggunakan adjustMarginsForEdgeToEdge, hapus semua pengaturan manual untuk inset jendela atau hack CSS yang telah Anda tambahkan.

Tidak Lupakan CSS Area Aman

Konfigurasi mengatur penyesuaian margin, tetapi Anda masih perlu menggunakan inset CSS area aman untuk penataan konten yang tepat.

Petunjuk Pindah

Jika Anda saat ini menggunakan plugin atau hack untuk edge-to-edge:

Hapus semua plugin edge-to-edge mulai dari dependensi Anda
Tambahkan opsi konfigurasi ke dalam capacitor.config.ts
Membersihkan dan membangun ulang 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 android

Future-Proofing

Ingatlah bahwa Capacitor 8 akan membuat "auto" nilai default. Untuk mempersiapkan:

Uji dengan "auto" saat ini untuk menangkap masalah-masalah yang mungkin terjadi
Perbarui CSS Anda untuk menghandle area-area yang aman dengan benar
Ulas kembali tata letak Anda pada perangkat yang diaktifkan edge-to-edge

Sumber Daya Tambahan

Kesimpulan

Tampilan layar tanpa batas di Capacitor tidak memerlukan plugin, trik, atau cara kerja yang rumit. adjustMarginsForEdgeToEdge Opsi konfigurasi ini menyediakan solusi asli yang bersih dan mendukung masa depan.

Mulai dengan "auto" untuk aplikasi sebagian besar, tes secara menyeluruh di berbagai perangkat, dan tambahkan CSS area aman yang sesuai. Aplikasi Anda akan siap untuk Android 15 dan seterusnya dengan sedikit usaha.

Questions or running into issues? Masyarakat dan dokumentasi resmi Capacitor Dokumentasi resmi are great resources for additional help.

Teruskan dari Display Edge-to-Edge di Capacitor Tanpa Plugin

Display Edge-to-Edge di __CAPGO_KEEP_0__ Tanpa Plugin Tampilan Layar Tanpa Batas di Capacitor Tanpa Menggunakan Plugin Untuk merencanakan perilaku media dan antarmuka native, hubungkannya dengan Menggunakan @capgo/capacitor-aktivitas langsung untuk kemampuan asli dalam Menggunakan @capgo/capacitor-aktivitas langsung. @capgo/capacitor-aktivitas-hidup-nyata untuk detail implementasi di @capgo/capacitor-aktivitas-hidup-nyata, Menggunakan @capgo/capacitor-pemain-video untuk kemampuan asli di Menggunakan @capgo/capacitor-pemain-video, @capgo/capacitor-pemain-video untuk detail implementasi di @capgo/capacitor-pemain-video, dan Menggunakan @capgo/capacitor-navigasi-asli untuk kemampuan asli di Menggunakan @capgo/capacitor-navigasi-asli.