Capacitor 앱에서 에지 투 에지 디스플레이를 implement 하려는 경우 플러그인, 하이재킹, 또는 workarounds가 필요하지 않습니다. Capacitor 에서 에지 투 에지 디스플레이를 위해 공식적으로 지원합니다. adjustMarginsForEdgeToEdge configuration 옵션 - 그것은 널리 문서화되지 않았습니다.
Capacitor 앱에서 에지 투 에지 레이아웃을 구현하는 개발자들은 특히 Android 15+를 대상으로 할 때 어려움을 겪습니다. 그들은 종종 모던한 에지 투 에지 디자인을 달성하기 위해 커스텀 플러그인 또는 CSS 하이재킹을 사용합니다. 그러나 더 나은, 네이티브한 방법이 있습니다.
에지 투 에지 디스플레이란 무엇인가요?
에지 투 에지 디스플레이는 앱 콘텐츠가 시스템 바(상태 바 및 네비게이션 바) 뒤로 확장되도록 허용하여 더 몰입적이고 현대적인 UI 경험을 제공합니다. Android 15부터, Google은 모든 앱에 에지 투 에지가 표준이 될 것을 밀어붙입니다.
official 솔루션: adjustMarginsForEdgeToEdge
Capacitor 에서 제공하는 configuration 옵션은 이 목적을 위해 특별히 설계되었습니다. 이 문서는 official Capacitor config 문서에 설명되어 있습니다. adjustMarginsForEdgeToEdge __CAPGO_KEEP_0__ config 문서 Capacitor하지만 쉽게 놓치기 쉽습니다.
설정 방법
다음과 같이 추가하세요. capacitor.config.ts 또는 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;JSON 형식으로 다음과 같이 입력하세요.
{
"appId": "com.example.app",
"appName": "My App",
"webDir": "dist",
"android": {
"adjustMarginsForEdgeToEdge": "auto"
}
}설정 옵션
설정 옵션은 adjustMarginsForEdgeToEdge 세 가지 값을 받습니다.
1. "auto" (권장)
adjustMarginsForEdgeToEdge: 'auto'설정 옵션의 기능: 자동으로 Android 15 이상과 설정을 확인합니다. 장치와 설정에 따라 자동으로 여백을 조절합니다. windowOptOutEdgeToEdgeEnforcement 자동으로 Android 15 이상과 설정을 확인하고, 장치와 설정에 따라 여백을 자동으로 조절합니다.
Best for: 대부분의 Android 버전을 지원하는 기기에서 edge-to-edge를 유지하면서 이전 Android 버전과 호환성을 유지하고 싶은 프로덕션 앱에 적합합니다.
2. "force"
adjustMarginsForEdgeToEdge: 'force'What it does: Android 버전이나 다른 설정과 관계없이 edge-to-edge를 강제로 margin 조정합니다.
Best for: 모든 지원하는 Android 버전에서 edge-to-edge 동작을 원하는 앱에 적합합니다.
3. "disable"
adjustMarginsForEdgeToEdge: 'disable'What it does: 자동 margin 조정을 완전히 비활성화합니다.
Best for: edge-to-edge 레이아웃을 수동으로 처리하거나 edge-to-edge 동작을 원하지 않는 앱에 적합합니다.
Note: 현재 "disable" 은 기본값이지만 이 값은 "auto" in Capacitor 8.
Android 15+에서 중요합니다.
Android 15부터, Google은 edge-to-edge 디스플레이를 기본 동작으로 강제합니다. edge-to-edge 레이아웃을 적절하게 처리하지 않는 앱은 다음 UI 문제를 경험할 수 있습니다:
- 시스템 바 뒤에 콘텐츠가 숨겨짐
- 어색한 간격 및 패딩
- 디바이스 간 일관성이 없는 외관
- 사용자 경험의 저하
공식 adjustMarginsForEdgeToEdge config, you ensure your app handles these changes properly without custom code.
완전한 예제
Here’s a complete example configuration for a modern Capacitor app:
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;CSS Considerations
edge-to-edge 디스플레이를 사용할 때, 시스템 바를 고려하여 CSS를 추가해야 할 수 있습니다.
/* 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";
}Testing Your Configuration
설정을 완료한 후 adjustMarginsForEdgeToEdge, 앱을 다음 장치에서 테스트하세요.
- Android 15+ 장치 - 시스템 바를 고려하여 콘텐츠가 올바르게 반영되는지 확인하세요.
- 오래된 Android 버전 - 이전 버전과 호환성을 유지하세요.
- 다양한 화면 크기 - 장치 간 레이아웃이 올바르게 작동하는지 확인하세요.
- 라이트 및 다크 테마 - 테스트 모드
일반적인 실수를 피하는 방법
이러한 경우 플러그인을 사용하지 마세요.
3rd 파티 플러그인을 사용하지 않아도 됩니다. capacitor-edge-to-edge or similar. 네이티브 설정은 이 문제를 깨끗하게 처리합니다. 시스템 크롬에 대한 세부적인 제어를 필요로 하는 경우 adjustMarginsForEdgeToEdge, @capgo/capacitor-네비게이션 바 그리고 @capgo/홈 인디케이터 네이티브 설정을 대체하지 않고 그에 맞춰서 사용하세요.
수동 IMPLEMENTATION과 혼용하지 마세요.
이러한 경우 adjustMarginsForEdgeToEdge, 수동 윈도우 인셋 처리 또는 CSS HACK을 제거하세요.
__CAPGO_KEEP_0__
__CAPGO_KEEP_1__
__CAPGO_KEEP_2__
__CAPGO_KEEP_3__
- __CAPGO_KEEP_4__ __CAPGO_KEEP_5__
- __CAPGO_KEEP_6__ __CAPGO_KEEP_7__
capacitor.config.ts - __CAPGO_KEEP_8__ __CAPGO_KEEP_9__
- __CAPGO_KEEP_10__ __CAPGO_KEEP_11__
# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..
# Rebuild
npx cap copy android
npx cap open android미래를 위한 보장
Capacitor 8을 사용하면 "auto" 기본값이 됩니다. 준비를 위해:
- __CAPGO_KEEP_0__로 테스트하세요
"auto"현재 이유를 빨리 찾기 위해 - CSS 업데이트 안전한 영역을 처리하기 위해
- 레이아웃 검토 엣지 투 엣지 장치에서
추가 리소스
결론
Capacitor 에서 Edge-to-edge 디스플레이는 플러그인, 해킹, 또는 복잡한 해결책이 필요하지 않습니다. adjustMarginsForEdgeToEdge 설정 옵션은 공식적으로 지원되고 미래에 안전한 CLEAN, NATIVE 솔루션을 제공합니다.
대부분의 앱에서 시작하고, 다양한 장치에서 테스트하고, 적절한 Safe Area CSS를 추가하세요. "auto" Android 15 이상으로 앱을 준비하는 데 최소한의 노력으로 앱이 준비되도록 하세요.
문제가 발생하거나 질문이 있으시면? Capacitor 커뮤니티와 공식 문서 추가 도움이 필요하시면 좋은 자원입니다.
Edge-to-Edge 디스플레이를 Capacitor 에서 플러그인 없이 사용하세요.
If you are using __CAPGO_KEEP_0__ Edge-to-Edge Display in Capacitor Without Plugins to plan native media and interface behavior, connect it with __CAPGO_KEEP_0__ Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, capgo @capgo/capacitor-live-activities for the implementation detail in @capgo/capacitor-live-activities, capgo Using @capgo/capacitor-video-player for the native capability in Using @capgo/capacitor-video-player, capgo @capgo/capacitor-video-player for the implementation detail in @capgo/capacitor-video-player, capgo and capgo Using @capgo/capacitor-native-navigation 자연스러운 네이티브 기능을 사용하기 위해 @capgo/capacitor-native-navigation을 사용합니다.
