@capgo/capacitor-sheets

프레임워크에 구애받지 않는 Capacitor WebView에 최적화된 바텀 시트, 드로어, 다이얼로그 및 오버레이입니다.

시작하기 GitHub

프레임워크에 구애받지 않음

표준 기반 커스텀 엘리먼트를 직접 사용하거나 React, Vue, Angular, Svelte, Solid용 설정 헬퍼를 사용하세요.

Capacitor 준비 완료

웹 레이어에서 안전 영역, 키보드 이동, 네이티브 엣지 제스처, WebView 테마 색상 디밍을 고려합니다.

모든 시트 형태

바텀 시트, 사이드 드로어, 탑 시트, 중앙 다이얼로그, 토스트, 분리형 시트, 카드, 페이지, 라이트박스를 구성하세요.

모던 CSS

detents를 다음과 같이 작성하세요: em, rem, 뷰포트 단위, calc(), CSS 변수. 기본 크기는 em 기반으로 유지됩니다.

플랫폼 지원

플랫폼	지원	참고 사항
iOS	웹 레이어	WKWebView 내부의 커스텀 요소
Android	웹 레이어	Android WebView 내부의 커스텀 요소
웹	지원	Capacitor 웹 빌드용 동일한 컴포넌트

언제 사용하나요?

@capgo/capacitor-sheets 특정 UI framework를 도입하지 않고도 고품질 모바일 오버레이가 필요한 Capacitor 앱을 위한 것입니다. 커스텀 엘리먼트로 제공되므로 코어 패키지에는 React, Vue, Angular, Svelte, Solid 런타임 의존성이 없습니다.

다음과 같은 경우에 사용하세요:

하나 이상의 detent가 있는 bottom sheets
좌우 사이드바와 top sheets
중앙 정렬된 dialog, lightbox, card, toast 같은 오버레이
뒤에 있는 앱을 계속 조작할 수 있게 하는 persistent sheets
화면 가장자리에서 들어오는 full-page overlays
sheet 진행도에 따른 stack, depth, parallax 효과
진행도와 거리 값을 제공하는 scroll helpers
노치, 홈 인디케이터, Android 컷아웃, 소프트웨어 키보드에 대응하는 Capacitor-safe 레이아웃

유스케이스 커버리지

유스케이스	Capgo Sheets 패턴
긴 시트	`cap-sheet` 자연스러운 콘텐츠 스크롤 또는 `cap-scroll`
Detent가 적용된 Sheet	`detents="18em 32em"` 및 `stepTo()` 또는 단계 트리거
사이드바	`content-placement="left"` 또는 `content-placement="right"`
바텀 시트	기본값 `content-placement="bottom"`
키보드와 함께 표시되는 Sheet	`native-focus-scroll-prevention` 및 visual viewport offset 처리
토스트	`inert-outside="false"`, `focus-trap="false"`, 외부 클릭으로 닫히지 않음
Detached Sheet	`cap-sheet-special-wrapper` 커스텀 margin과 radius 추가
하단에서 열리는 페이지	전체 높이 바텀 시트 콘텐츠
상단 시트	`content-placement="top"`
스태킹이 적용된 시트	`cap-sheet-stack` depth 변수 활용
Depth가 있는 Sheet	`cap-sheet-outlet` 진행률 기반 트랜스폼
Parallax 페이지	`cap-sheet-outlet` 포함 `cap-scroll` 진행률
페이지	뷰포트 전체를 채우는 콘텐츠가 가장자리에서 진입
라이트박스	`content-placement="center"` 백드롭과 미디어 콘텐츠 포함
Detent가 있는 Persistent Sheet	`default-presented`, `swipe-dismissal="false"`, 그리고 `inert-outside="false"`
카드	컴팩트한 중앙 정렬 시트 콘텐츠

핵심 API

<cap-sheet> 프레젠테이션 상태, detent, 배치, 제스처, 접근성 및 이벤트를 관리합니다.
<cap-sheet-trigger> present, dismiss, toggle 및 detent-step 액션을 선언합니다.
<cap-sheet-view> 오버레이를 배치하고 safe-area 및 키보드 오프셋을 적용합니다.
<cap-sheet-backdrop> 진행률과 동기화된 배경을 렌더링합니다.
<cap-sheet-content> 시트 표면을 렌더링합니다.
<cap-sheet-handle> 드래그 및 키보드 detent 컨트롤을 제공합니다.
<cap-sheet-stack> 겹쳐진 시트의 좌표를 관리합니다.
<cap-sheet-outlet> 시트 진행도를 페이지, 깊이, 패럴랙스 효과에 노출합니다.
<cap-scroll> 및 <cap-scroll-content> 스크롤 진행률 및 거리 헬퍼를 제공합니다.
setupSheet(element, options?) 프레임워크 effect 또는 라이프사이클 훅에서 시트를 구성합니다.

Capacitor 레이아웃 모델

기본 시트 뷰포트는 env(safe-area-inset-*) 및 Capacitor 스타일의 --safe-area-inset-* 폴백 변수를 읽은 다음, 선택된 에지를 오버레이 주변 패딩으로 적용합니다. safe-area="auto" 모든 에지를 보호합니다. 다음을 사용하세요: safe-area="bottom left right" 또는 safe-area="none" 특정 유스케이스에서 다른 동작이 필요한 경우.

키보드 핸들링은 기본적으로 활성화되어 있습니다. 시트는 다음을 수신합니다: visualViewport 리사이즈 및 스크롤 이벤트를 처리하고 뷰포트에 키보드 오프셋을 추가하며 컨트롤에 포커스를 설정합니다 preventScroll 입력 필드가 소프트웨어 키보드 위에 항상 보이도록 합니다.

이 패키지는 웹 레이어에서 실행됩니다. 네이티브 UIKit 또는 Android 하단 시트를 렌더링하지 않으므로, Capacitor에서 중요한 WebView 제약 사항을 준수하면서도 앱의 스타일링을 완전히 제어할 수 있습니다.

데모 및 플레이그라운드

모든 지원되는 사용 사례에 대한 애니메이션 WebP 데모가 저장소 README에 포함되어 있습니다. 예제는 StackBlitz 플레이그라운드에서도 사용할 수 있습니다:

긴 시트	Detents

사이드바	라이트박스

@capgo/capacitor-sheets에서 계속하기

사용 중이라면 @capgo/capacitor-sheets 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항은, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우와, Capgo Native Build Capgo Native Builds의 제품 워크플로우를 위해.