플러그인 없이 Capacitor에서 Edge-to-Edge 디스플레이 구현하기

Capacitor 앱에 edge-to-edge 디스플레이를 구현하려고 하시나요? 편법이나 플러그인, 우회 방법은 필요 없습니다. Capacitor는 다음을 통해 edge-to-edge 디스플레이를 공식 지원합니다. adjustMarginsForEdgeToEdge 설정 옵션이 있지만, 관련 문서가 충분하지 않습니다.

Capacitor 앱에서 에지 투 에지(edge-to-edge) 레이아웃을 구현하는 데 많은 개발자가 어려움을 겪고 있습니다. 특히 Android 15 이상을 타겟팅할 때 더욱 그렇습니다. 현대적인 에지 투 에지 디자인을 위해 커스텀 플러그인이나 CSS 해킹을 사용하는 경우가 많지만, 더 나은 네이티브 방식이 있습니다.

에지 투 에지 디스플레이란 무엇인가요?

에지 투 에지 디스플레이를 사용하면 앱 콘텐츠가 시스템 바(상태 표시줄 및 네비게이션 바) 뒤까지 확장되어 더욱 몰입감 있고 현대적인 UI 경험을 제공합니다. Android 15부터 Google은 모든 앱의 표준으로 에지 투 에지를 권장하고 있습니다.

공식 솔루션: adjustMarginsForEdgeToEdge

Capacitor는 이 목적을 위한 adjustMarginsForEdgeToEdge 전용 설정 옵션을 제공합니다. 이는 공식 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 option은 세 가지 값을 받습니다:

1. `"auto"` (권장)

adjustMarginsForEdgeToEdge: 'auto'

기능 설명: Android 15+ 및 해당 설정을 자동으로 확인합니다. windowOptOutEdgeToEdgeEnforcement 기기와 설정에 따라 마진을 스마트하게 조정합니다.

추천 대상: 이전 Android 버전과의 호환성을 유지하면서 지원되는 기기에서 edge-to-edge를 원하는 대부분의 프로덕션 앱.

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

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

추천 대상: 모든 지원되는 Android 버전에서 edge-to-edge 동작을 원하는 앱.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

기능 설명: 자동 마진 조정을 완전히 비활성화합니다.

추천 대상: edge-to-edge 레이아웃을 수동으로 처리하거나 해당 동작을 원하지 않는 앱.

참고: 현재는 "disable" 기본값이지만, 다음으로 변경될 예정입니다: "auto" Capacitor 8 버전부터.

Android 15+에서 이것이 중요한 이유

Android 15부터 Google은 edge-to-edge 디스플레이를 기본 동작으로 강제합니다. edge-to-edge 레이아웃을 제대로 처리하지 않은 앱은 다음과 같은 UI 문제가 발생할 수 있습니다:

시스템 바에 가려지는 콘텐츠
어색한 간격과 패딩
기기별로 일관되지 않은 화면
좋지 않은 사용자 경험

공식 config를 사용하면 adjustMarginsForEdgeToEdge 커스텀 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 고려 사항

edge-to-edge 디스플레이를 사용할 때는 safe area 처리를 위해 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 버전 - 하위 호환성 확보 여부 확인
다양한 화면 크기 - 모든 기기에서 레이아웃이 정상 작동하는지 검증
라이트 및 다크 테마 - 두 가지 테마 모드 모두 테스트

피해야 할 흔한 실수

플러그인을 사용하지 마세요

다음과 같은 서드파티 플러그인은 필요하지 않습니다: capacitor-edge-to-edge 또는 이와 유사한 방식입니다. Native Build 설정으로 이를 깔끔하게 처리할 수 있습니다. 설정을 활성화한 후 시스템 크롬(system chrome)을 세밀하게 제어해야 한다면 adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar 및 @capgo/home-indicator Native config를 대체하는 대신 이를 보완하는 방식으로 사용하세요.

수동 구현 방식과 혼용하지 마세요

만약 다음을 사용 중이라면, adjustMarginsForEdgeToEdge기존에 추가했던 수동 window insets 처리나 CSS hack을 모두 제거해야 합니다.

Safe Area CSS를 잊지 마세요

Config가 마진 조절은 처리하지만, 콘텐츠 패딩을 적절히 적용하려면 여전히 CSS safe area insets를 사용해야 합니다.

마이그레이션 가이드

현재 edge-to-edge 구현을 위해 플러그인이나 hack을 사용 중이라면:

edge-to-edge 플러그인 제거 의존성에서 삭제
설정 옵션 추가 …에 capacitor.config.ts
Clean 및 rebuild Android 프로젝트
철저한 테스트 대상 기기에서

# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..

# Rebuild
npx cap copy android
npx cap open android

미래 대응(Future-Proofing)

Capacitor 8 버전부터는 "auto" 기본값으로 설정됩니다. 준비 사항:

다음으로 테스트 "auto" 지금 바로 문제를 조기에 발견할 수 있도록
CSS를 업데이트하여 safe area를 올바르게 처리하세요
레이아웃을 검토하세요 edge-to-edge가 활성화된 기기에서

추가 리소스

마치며

Capacitor의 edge-to-edge 디스플레이는 플러그인, 꼼수, 복잡한 우회 방법이 필요하지 않습니다. adjustMarginsForEdgeToEdge 이 설정 옵션은 공식적으로 지원되며 향후에도 문제없는 깔끔한 네이티브 솔루션을 제공합니다.

다음으로 시작하세요 "auto" 대부분의 앱은 다양한 기기에서 철저히 테스트하고 적절한 safe area CSS를 추가하세요. 최소한의 노력으로 Android 15 및 그 이후 버전에도 완벽히 대응할 수 있습니다.

궁금한 점이나 문제가 발생했나요? Capacitor 커뮤니티와 공식 문서 함께라면 추가적인 도움을 받기에 좋습니다.

Capacitor에서 플러그인 없이 Edge-to-Edge Display 구현하기 다음 단계

사용 중이라면 플러그인 없이 Capacitor에서 Edge-to-Edge 디스플레이 구현하기 네이티브 미디어 및 인터페이스 동작을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-live-activities 사용 @capgo/capacitor-live-activities 사용에서의 네이티브 기능, @capgo/capacitor-live-activities @capgo/capacitor-live-activities의 구현 세부 사항, @capgo/capacitor-video-player 사용 @capgo/capacitor-video-player 사용 시 네이티브 기능은, @capgo/capacitor-video-player 구현 세부 사항은 @capgo/capacitor-video-player에서 확인하고, @capgo/capacitor-native-navigation 사용하기 @capgo/capacitor-native-navigation. 사용 시의 Native 기능