Edge-to-Edge Display in Capacitor Without Plugins

Capacitor 앱에서 edge-to-edge 디스플레이를 구현하려고 하는가? 플러그인, 트릭, 또는 작업-around이 필요하지 않습니다. Capacitor 에서 에지 투 에지 디스플레이를 구현하는 공식 지원이 있습니다. 단지 널리 문서화되지 않았습니다. adjustMarginsForEdgeToEdge 기사 저자

많은 개발자들은 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를 표준으로 밀고 있습니다.

공식적인 해결책: adjustMarginsForEdgeToEdge

Capacitor는 adjustMarginsForEdgeToEdge __CAPGO_KEEP_0__의 공식적인 Capacitor config 문서Edge-to-Edge 레이아웃을 구성하는 방법

Edge-to-Edge 레이아웃을 구성하려면

JSON 형식으로 다음과 같이 추가하세요: 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;

__CAPGO_KEEP_0__의

{
  "appId": "com.example.app",
  "appName": "My App",
  "webDir": "dist",
  "android": {
    "adjustMarginsForEdgeToEdge": "auto"
  }
}

설정 옵션

The adjustMarginsForEdgeToEdge 옵션은 세 가지 값을 받습니다:

1. `"auto"` (권장)

adjustMarginsForEdgeToEdge: 'auto'

무엇을 하는가: Android 15 이상과 설정을 자동으로 확인하고 windowOptOutEdgeToEdgeEnforcement 장치 및 구성에 따라 지능적으로 마진을 조정합니다.

어떤 경우에 적합한가: Android 15 이상 지원 장치에서 Edge-to-Edge를 유지하면서 이전 Android 버전과 호환성을 유지하고자 하는 대부분의 프로덕션 앱에 적합합니다.

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

무엇을 하는가: Edge-to-Edge를 유지하기 위해 Android 버전이나 다른 설정에 관계없이 마진 조정을 강제합니다.

어떤 경우에 적합한가: Android 버전을 지원하는 모든 버전에서 edge-to-edge 동작을 원하는 앱들.

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

이것이 하는 일: 자동 마진 조정 완전히 비활성화.

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

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

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

시스템 바 뒤에 콘텐츠가 숨겨짐

시스템 바의 뒤에 숨겨진 콘텐츠
불편한 간격과 패딩
기기 간의 불일치한 외관
사용자 경험의 저하

공식 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 고려 사항

엣지 투 엣지 디스플레이를 사용할 때는 안전 영역을 처리하기 위해 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 버전 - 이전 호환성을 보장하세요
다양한 화면 크기 - 장치 간 레이아웃이 작동하는지 확인하세요
라이트 및 다크 테마 - 두 가지 테마 모드를 테스트하세요

일반적인 실수 피하기

이용하지 마세요

이용하지 마세요. third-party 플러그인처럼 capacitor-edge-to-edge or similar. native config는 이 문제를 깨끗하게 처리합니다. 시스템 창 크기를 세밀하게 제어해야 하는 경우 adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar 그리고 @capgo/홈 인디케이터 자연스러운 구성으로 원본 설정을 보완하지 않습니다.

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

만약 당신이 adjustMarginsForEdgeToEdge수동 윈도우 인셋 처리나 CSS 트릭을 사용하고 있다면 제거하세요.

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

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

이동 안내서

현재 에지 투 에지 플러그인이나 트릭을 사용하고 있다면 제거하세요.

이동 안내서 의존성에서
설정 옵션을 추가하세요 에 capacitor.config.ts
Android 프로젝트를 다시 빌드하세요 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를 업데이트하세요 안전 영역을 올바르게 처리하기 위해
레이아웃을 검토하세요 엣지-투-엣지 활성화된 기기에서

추가 리소스

결론

Capacitor에서 엣지-투-엣지 디스플레이는 플러그인, 해킹, 또는 복잡한 작업-around이 필요하지 않습니다. 구성 옵션은 공식적으로 지원되고 미래에 안전한 깨끗한 네이티브 솔루션을 제공합니다. adjustMarginsForEdgeToEdge 리소스

시작하기 "auto" 대부분의 앱의 경우, 다양한 기기에서 테스트하고 적절한 안전 영역 CSS를 추가하여 Android 15 이상을 위한 앱을 준비하세요.

문제가 발생하거나 질문이 있으시면? Capacitor 커뮤니티와 공식 문서 추가 도움을 받으려면 훌륭한 자원입니다.