__Capacitor__ 에지 투 에지 디스플레이

Capacitor 앱에서 에지 투 에지 디스플레이를 구현하려고 하는가요? 플러그인, 해킹, 또는 대안이 필요하지 않습니다. Capacitor는 에지 투 에지 디스플레이를 위한 공식 지원을 제공하고 있습니다. 그것은 단지 널리 알려지지 않은 설정 옵션입니다. adjustMarginsForEdgeToEdge 많은 개발자들은 __CAPGO_KEEP_0__ 앱에서 에지 투 에지 레이아웃을 구현하는 데 어려움을 겪고 있습니다. 특히 Android 15+를 대상으로 할 때. 그들은 종종 현대적인 에지 투 에지 모양을 얻기 위해 커스텀 플러그인 또는 CSS 해킹을 사용합니다. 그러나 더 나은, 네이티브한 방법이 있습니다.

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.

What is Edge-to-Edge Display?

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

The Official Solution: adjustMarginsForEdgeToEdge

Capacitor은 이 목적을 위해 특별히 설계된 adjustMarginsForEdgeToEdge 설정 옵션을 제공합니다. 이 옵션은 공식 Capacitor config 문서에 문서화되어 있습니다. 그러나 쉽게 놓치기 쉽습니다.

How to Configure It

다음과 같이 추가하세요. capacitor.config.ts or 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"
  }
}

설정 옵션

The adjustMarginsForEdgeToEdge option accepts three values:

1. `"auto"` (Recommended)

adjustMarginsForEdgeToEdge: 'auto'

What it does: 자동으로 Android 15 이상과 설정을 확인하고 windowOptOutEdgeToEdgeEnforcement 장치 및 설정에 따라 지능적으로 여백을 조정합니다.

Best for: 대부분의 프로덕션 앱이 지원되는 기기에서 edge-to-edge를 유지하면서 오래된 Android 버전과 호환성을 유지하고 싶은 경우.

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

What it does: edge-to-edge를 유지하기 위해 여백 조정을 강제로 Android 버전이나 다른 설정과 관계없이 합니다.

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 문제를 경험할 수 있습니다.

시스템 바 뒤의 콘텐츠가 숨겨짐
어색한 간격 및 패딩
다양한 기기에서 일관되지 않은 외관
사용자 경험의 저하

공식 adjustMarginsForEdgeToEdge config를 사용하여 앱이 이러한 변경 사항을 적절히 처리하도록 보장합니다. custom 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";
}

설정 확인

설정을 완료한 후 앱을 다음 기기에서 테스트하세요: adjustMarginsForEdgeToEdgeAndroid 15 이상 기기

__CAPGO_KEEP_0__ - 시스템 바를 올바르게 존중하는지 확인하세요.
구형 안드로이드 버전 - 이전 버전과 호환성을 유지하세요.
다양한 화면 크기 - 다양한 기기에서 레이아웃이 작동하는지 확인하세요.
라이트 및 다크 테마 - 두 가지 테마 모드를 테스트하세요.

일반적인 실수

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

Capgo의 내장 설정은 이 기능을 깨끗하게 처리합니다. capacitor-edge-to-edge 수동 구현과 혼합하지 마세요.

You don’t need third-party plugins like

If you’re using __CAPGO_KEEP_0__ , remove any manual window insets handling or CSS hacks you may have added. adjustMarginsForEdgeToEdge__CAPGO_KEEP_0__ Don’t Forget Safe Area CSS

The config handles margin adjustments, but you still need to use CSS safe area insets for proper content padding.

__CAPGO_KEEP_0__ Migration Guide

If you’re currently using plugins or hacks for edge-to-edge:

Remove any edge-to-edge plugins from your dependencies

__CAPGO_KEEP_0__ Add the config option to your __CAPGO_KEEP_0__ Clean and rebuild your Android project
__CAPGO_KEEP_0__ __CAPGO_KEEP_0__ capacitor.config.ts
__CAPGO_KEEP_0__ __CAPGO_KEEP_0__
적절한 장치에서 철저히 테스트하세요 목표 장치에서

# 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 디스플레이는 플러그인, 해킹, 또는 복잡한 작업-around이 필요하지 않습니다. adjustMarginsForEdgeToEdge 설정 옵션은 공식적으로 지원되고 미래에 안전한 CLEAN, NATIVE 솔루션을 제공합니다.

대부분의 앱에서 시작하고, 장치에 대한 테스트를 철저히하고, 적절한 Safe Area CSS를 추가하세요. 앱은 Android 15 이상에 대한 최소 노력으로 준비되었습니다. "auto" 질문이나 문제가 발생하는 경우?

__CAPGO_KEEP_0__ 커뮤니티와 The Capacitor community and __CAPGO_KEEP_0__ are great resources for additional help.

Capacitor에서 플러그인 없이 Edge-to-Edge Display를 계속 진행하세요.

__CAPGO_KEEP_0__을 사용하시는 경우 Edge-to-Edge Display를 Capacitor에서 플러그인 없이 계속 진행하세요. __CAPGO_KEEP_0__과 연결하여 @capgo/capacitor-live-activities를 사용하여 @capgo/capacitor-live-activities의 native capability을 사용하여 @capgo/capacitor-live-activities @capgo/capacitor-live-activities의 implementation detail을 사용하여 @capgo/capacitor-video-player를 사용하여 @capgo/capacitor-video-player의 native capability을 사용하여 @capgo/capacitor-video-player @capgo/capacitor-video-player에 대한 구현 세부 정보입니다. @capgo/capacitor-native-navigation을 사용합니다. @capgo/capacitor-native-navigation을 사용하여 네이티브 기능을 사용합니다.

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