__Capacitor 에서 Edge-to-Edge Display_

Capacitor 앱에서 에지 투 에지 디스플레이를 구현하려고 하는가요? 플러그인, 해킹, 또는 우회가 필요하지 않습니다. Capacitor는 에지 투 에지 디스플레이를 위한 공식 지원을 제공합니다. adjustMarginsForEdgeToEdge __CAPGO_KEEP_0__ 옵션 - 그것은 단지 널리 문서화되지 않은 것입니다.

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

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

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

official Solution: adjustMarginsForEdgeToEdge

Capacitor은 adjustMarginsForEdgeToEdge Edge-to-Edge를 위해 이 목적을 위해 특별히 설계된 옵션을 제공합니다. 이 옵션은 공식 __CAPGO_KEEP_0__ config 문서에 문서화되어 있습니다. official Capacitor config documentationEdge-to-Edge를 구성하는 방법

__CAPGO_KEEP_0__에 이 옵션을 추가하세요.

__CAPGO_KEEP_0__ 또는 __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 추천하는 경우:

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

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

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

Best for: Android 15 이상 버전을 지원하는 모든 버전에서 edge-to-edge 동작을 원하는 앱에 적합합니다.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

What it does: 자동 마진 조정 adjustment를 완전히 비활성화합니다.

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

Note: 현재는 기본값이지만 __CAPGO_KEEP_0__ 8 버전에서 "disable" Why This Matters for Android 15+ "auto" in Capacitor 8.

UI 문제

edge-to-edge 레이아웃

__CAPGO_KEEP_0__ 시스템 바 뒤에 숨겨진 콘텐츠
__CAPGO_KEEP_0__의 불편한 여백 및 패딩
__CAPGO_KEEP_0__의 불일치된 디바이스 간의 디자인
__CAPGO_KEEP_0__의 나쁜 사용자 경험

공식 __CAPGO_KEEP_0__을 사용하여 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+ 기기에서 앱을 테스트하세요.

- 시스템 바를 올바르게 존중하는지 확인하세요. 오래된 Android 버전
- 이전 버전과 호환성을 유지하세요. 다양한 화면 크기
- 다양한 기기에서 레이아웃이 작동하는지 확인하세요. 라이트 및 다크 테마
- 두 가지 테마 모드를 테스트하세요. 일반적인 실수

이용하지 마세요.

이러한 경우 3rd 파티 플러그인 사용을 피하세요.

You don’t need third-party plugins like __CAPGO_KEEP_0__. capacitor-edge-to-edge 또는 유사한 기능을 사용할 수 있습니다. native config는 이 문제를 깨끗하게 처리합니다. 시스템 chrome에 대한 세부적인 제어가 필요하다면 활성화된 후에 adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar 그리고 @capgo/home-indicator native config를 대체하지 않고 native config를 보완하세요.

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

현재 adjustMarginsForEdgeToEdge, 수동 윈도우 인셋 처리 또는 CSS 트릭을 추가한 경우 제거하세요.

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

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

이동 안내서

현재 edge-to-edge에 대한 플러그인 또는 트릭을 사용하는 경우:

edge-to-edge 플러그인 제거 의존성에서 제거하세요
설정 옵션을 추가하세요 에 추가하세요 capacitor.config.ts
Android 프로젝트를 정리하고 다시 빌드하세요 목표 기기에서 철저히 테스트하세요
미래를 대비하세요 __CAPGO_KEEP_0__ 8이 기본값이 될 것입니다. 준비를 위해:

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

# Rebuild
npx cap copy android
npx cap open android

목표 기기에서 철저히 테스트하세요

Remember that Capacitor 8 will make "auto" 테스트하세요

테스트하세요 "auto" 지금 이유를 빨리 잡기 위해
CSS 업데이트 안전한 영역을 올바르게 처리하기 위해
레이아웃 검토 엣지 투 엣지 지원 장치에서

추가 리소스

결론

Capacitor 에서 엣지 투 엣지 디스플레이는 플러그인, 해킹, 복잡한 작업을 필요로 하지 않습니다. adjustMarginsForEdgeToEdge 설정 옵션은 깨끗하고 원활한 네이티브 솔루션을 제공하며 공식적으로 지원되고 미래에 대한 보장을 제공합니다.

시작하려면 "auto" 대부분의 앱의 경우, 장치별로 충분히 테스트하고 적절한 안전 영역 CSS를 추가하세요. 앱은 Android 15 이상에 대한 최소 노력으로 준비되었습니다.

문제가 발생하거나 질문이 있으시면? The Capacitor community and 공식 문서 추가 도움이 필요하시면 좋은 자원입니다.

Keep going from Edge-to-Edge Display in Capacitor Without Plugins

Edge-to-Edge Display in Capgo Without Plugins를 사용하여 네이티브 미디어 및 인터페이스 동작을 계획하고 있습니다. Edge-to-Edge Display in Capacitor Without Plugins Edge-to-Edge Display in Capgo Without Plugins를 사용하여 네이티브 미디어 및 인터페이스 동작을 계획하고 있습니다. Using @capgo/capacitor-live-activities capgo의 원생 기능을 위한 Using @capacitor-live-activities, @capgo/capacitor-live-activities capgo의 구현 세부사항을 위한 @capacitor-live-activities, Using @capgo/capacitor-video-player capgo의 원생 기능을 위한 Using @capacitor-video-player, @capgo/capacitor-video-player capgo의 구현 세부사항을 위한 @capacitor-video-player, 그리고 Using @capgo/capacitor-native-navigation capgo의 원생 기능을 위한 Using @capacitor-native-navigation.

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