__Capacitor__ 에지 투 에지 디스플레이

Capacitor 앱에서 에지 투 에지 디스플레이를 구현하려고 하는가요? Capacitor는 에지 투 에지 디스플레이를 위한 공식 지원을 제공합니다. adjustMarginsForEdgeToEdge 설정 옵션 - 그것은 단지 널리 문서화되지 않은 것입니다.

많은 개발자들은 Capacitor 앱에서 에지 투 에지 레이아웃에 어려움을 겪는데, 특히 Android 15+를 대상으로 할 때. 그들은 종종 모던한 에지 투 에지 모양을 달성하기 위해 커스텀 플러그인이나 CSS 해킹을 사용합니다. 그러나 더 나은, 네이티브한 방법이 있습니다.

Edge-to-Edge Display는 무엇입니까?

Edge-to-edge display는 앱 콘텐츠가 시스템 바(상태 바 및 네비게이션 바) 뒤로 확장되도록 허용하여 더 몰입적이고 현대적인 UI 경험을 제공합니다. Android 15부터 Google은 모든 앱에 에지 투 에지가 표준이 될 것을 밀어붙입니다.

공식적인 해결책: adjustMarginsForEdgeToEdge

Capacitor는 이 목적을 위해 adjustMarginsForEdgeToEdge 설정 옵션을 제공합니다. 이 옵션은 공식 __CAPGO_KEEP_0__ config 문서에 문서화되어 있습니다. official Capacitor config documentation설정 방법

__CAPGO_KEEP_0__에 추가하십시오.

또는 capacitor.config.ts __CAPGO_KEEP_0__ 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 추천하는 경우:

지원하는 기기에서 edge-to-edge를 원하는 대부분의 프로덕션 앱에 적합하며, 이전 Android 버전과 호환성을 유지합니다. 무엇을 하는가:

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

Android 버전이나 다른 설정에 관계없이 edge-to-edge를 위한 마진 조정을 강제합니다. __CAPGO_KEEP_0__

Best for: Android 버전을 지원하는 모든 버전에서 edge-to-edge 동작을 원하는 앱.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

What it does: 자동 여백 조정 설정을 완전히 비활성화합니다.

Best for: edge-to-edge 동작을 원하지 않거나 edge-to-edge 레이아웃을 수동으로 처리하는 앱.

Note: 현재 "disable" 는 기본값이지만 __CAPGO_KEEP_0__ 8에서 "auto" in Capacitor 8.

Why This Matters for Android 15+

Android 15부터 Google은 edge-to-edge 디스플레이를 기본 동작으로 강제합니다. edge-to-edge 레이아웃을 적절하게 처리하지 않는 앱은 다음 UI 문제를 경험할 수 있습니다:

시스템 바 뒤에 숨겨진 콘텐츠
불편한 간격과 패딩
디바이스 간에 일관된 디자인
나쁜 사용자 경험

공식 __CAPGO_KEEP_0__를 사용하여 adjustMarginsForEdgeToEdge config를 사용하면 앱이 이러한 변경 사항을 적절하게 처리할 수 있으며, 사용자 지정 code 없이합니다.

완전한 예제

모던 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;

CSS 고려 사항

엣지 투 엣지 디스플레이를 사용할 때는 안전 영역을 처리하기 위해 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";
}

설정 테스트

설정을 구성한 후 adjustMarginsForEdgeToEdge, 앱을 테스트하세요:

Android 15 이상 장치 - 시스템 바를 올바르게 존중하는지 확인하세요
오래된 Android 버전 - 이전 호환성을 보장하세요
다양한 화면 크기 - 장치 간 레이아웃이 작동하는지 확인하세요
라이트 및 다크 테마 - 두 가지 테마 모드를 테스트하세요

일반적인 실수를 피하세요

이용하지 마세요: 이 기능을 위해 플러그인을 사용하지 마세요

이용하지 마세요: 이 기능을 위해 3rd-party 플러그인을 사용하지 마세요 capacitor-edge-to-edge 또는 유사한 설정입니다. Native config는 이 문제를 깨끗하게 처리합니다.

수동 구현과 혼합하지 마세요.

Capacitor를 사용하고 있다면 adjustMarginsForEdgeToEdge, 수동 윈도우 인셋 처리 또는 CSS 해킹을 추가한 경우 제거하세요.

안전 영역 CSS를 잊지 마세요.

config는 마진 조정을 처리하지만, 올바른 콘텐츠 패딩을 위해 CSS 안전 영역 인셋을 사용해야 합니다.

이동 안내서

현재 Edge-to-Edge 플러그인 또는 해킹을 사용하고 있다면:

의존성에서 Edge-to-Edge 플러그인을 제거하세요. config 옵션을 추가하세요.
Capacitor를 사용하고 있다면 , 수동 윈도우 인셋 처리 또는 CSS 해킹을 추가한 경우 제거하세요. capacitor.config.ts
정리하고 다시 빌드하세요 Android 프로젝트
적절한 장치에서 철저히 테스트하세요 목표 장치

# 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" 준비를 위해:

현재로 "auto" 이유를 빨리 잡으려면 안전한 영역을 적절하게 처리하기 위해 CSS를 업데이트하세요
업데이트 이유를 빨리 잡으려면
레이아웃을 검토하세요 엣지 투 엣지 지원 장치에서

추가 리소스

결론

Edge-to-edge display in Capacitor doesn’t require plugins, hacks, or complicated workarounds. The adjustMarginsForEdgeToEdge 설정 옵션은 공식적으로 지원되고 미래에 안전한 CLEAN, NATIVE 솔루션을 제공합니다.

대부분의 앱에서 시작하여, 장치에 대한 충분한 테스트를 수행하고, 적절한 안전 영역 CSS를 추가하세요. "auto" Android 15 이상에 대한 앱이 최소한의 노력으로 준비되도록 하세요.

질문이나 문제가 발생하는 경우? Capacitor 커뮤니티와 공식 문서 는 추가적인 도움을 받기 위한 훌륭한 자원입니다.

Capacitor에서 플러그인 없이 에지 투 에지 디스플레이