시작하기

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-sheets`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/sheets/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그런 다음 아래 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-sheets` plugin in my project.

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

패키지 설치
터미널 창
```
bun add @capgo/capacitor-sheets
```
웹 컴포넌트 등록
```
import '@capgo/capacitor-sheets';
```

safe areas를 위한 viewport 설정 추가

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />

시트 렌더링

<cap-sheet-trigger for="booking-sheet" action="present">Open route</cap-sheet-trigger>

<cap-sheet id="booking-sheet" detents="18em 32em" content-placement="bottom">
  <cap-sheet-portal>
    <cap-sheet-view>
      <cap-sheet-backdrop></cap-sheet-backdrop>
      <cap-sheet-content class="route-sheet">
        <cap-sheet-bleeding-background></cap-sheet-bleeding-background>
        <cap-sheet-handle></cap-sheet-handle>
        <cap-sheet-title>Evening route</cap-sheet-title>
        <cap-sheet-description>Choose a route and confirm pickup.</cap-sheet-description>
        <cap-sheet-trigger action="dismiss">Done</cap-sheet-trigger>
      </cap-sheet-content>
    </cap-sheet-view>
  </cap-sheet-portal>
</cap-sheet>

.route-sheet {
  width: min(100%, 34em);
  padding: 0 1.25em 1.25em;
}

자주 하는 실수

컴포넌트 등록: import @capgo/capacitor-sheets 부트스트랩 시 한 번만 import해야 하며, 그렇지 않으면 요소가 업그레이드되지 않습니다.
Viewport fit: 누락됨 viewport-fit=cover 노치가 있는 폰에서 세이프 에어리어 패딩이 깨집니다.
키보드: 입력창이 바텀 시트 안에 있을 때 문서에 명시된 포커스 스크롤 방지를 활성화합니다.

Capacitor Safe Area 설정

세이프 에어리어는 기본적으로 다음을 통해 활성화됩니다 safe-area="auto". 시트 뷰포트는 브라우저 환경 값과 Capacitor 폴백 변수를 모두 읽어옵니다:

env(safe-area-inset-top)
env(safe-area-inset-bottom)
env(safe-area-inset-left)
env(safe-area-inset-right)
var(--safe-area-inset-top)
var(--safe-area-inset-bottom)
var(--safe-area-inset-left)
var(--safe-area-inset-right)

시트별로 보호할 가장자리를 선택하세요:

<cap-sheet safe-area="auto"></cap-sheet>
<cap-sheet safe-area="bottom left right"></cap-sheet>
<cap-sheet safe-area="none"></cap-sheet>

상태 표시줄이나 시스템 바가 오버레이되는 앱에서는 정확한 inset 값을 노출하는 네이티브 플러그인을 유지하세요:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    StatusBar: {
      overlaysWebView: true,
    },
    Keyboard: {
      resize: 'body',
      resizeOnFullScreen: true,
    },
    SystemBars: {
      insetsHandling: 'css',
    },
  },
};

export default config;

키보드 핸들링은 다음 속성으로 제어됩니다: native-focus-scroll-prevention이며, 기본값은 true입니다. 앱에서 이미 키보드 회피를 직접 처리하는 경우에만 비활성화하세요:

<cap-sheet native-focus-scroll-prevention="false"></cap-sheet>

명령형 제어

모든 프레임워크 헬퍼는 동일한 기반 커스텀 요소를 구성합니다. 시트를 직접 제어할 수도 있습니다:

const sheet = document.querySelector('cap-sheet');

await sheet?.present();
await sheet?.stepTo(2);
await sheet?.step('down');
await sheet?.dismiss();

상태 제어, 분석, 애니메이션 조율을 위해 이벤트를 수신하세요:

sheet?.addEventListener('cap-sheet-presented-change', (event) => {
  console.log(event.detail.presented);
});

sheet?.addEventListener('cap-sheet-active-detent-change', (event) => {
  console.log(event.detail.activeDetent);
});

sheet?.addEventListener('cap-sheet-travel', (event) => {
  console.log(event.detail.progress);
});

React

import { useEffect, useRef } from 'react';
import { setupSheet } from '@capgo/capacitor-sheets/react';
import '@capgo/capacitor-sheets';

export function BookingSheet() {
  const sheetRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (!sheetRef.current) return;

    return setupSheet(sheetRef.current, {
      detents: ['18em', '32em'],
      contentPlacement: 'bottom',
      onPresentedChange: ({ presented }) => console.log({ presented }),
    });
  }, []);

  return (
    <cap-sheet id="booking-sheet" ref={sheetRef}>
      <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
      <cap-sheet-view>
        <cap-sheet-backdrop />
        <cap-sheet-content>
          <cap-sheet-handle />
          <cap-sheet-title>React sheet</cap-sheet-title>
        </cap-sheet-content>
      </cap-sheet-view>
    </cap-sheet>
  );
}

다음에서 import하면 @capgo/capacitor-sheets/react 커스텀 엘리먼트의 JSX 타입 정의도 등록합니다. TypeScript가 여전히 알 수 없는 태그를 표시한다면, 소스 트리에 선언 파일을 추가하세요:

import '@capgo/capacitor-sheets/react';

Vue

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue';
import { setupSheet } from '@capgo/capacitor-sheets/vue';
import '@capgo/capacitor-sheets';

const sheetRef = ref<HTMLElement | null>(null);
let cleanup: (() => void) | undefined;

onMounted(() => {
  if (sheetRef.value) {
    cleanup = setupSheet(sheetRef.value, {
      detents: ['18em', '32em'],
      contentPlacement: 'bottom',
    });
  }
});

onUnmounted(() => cleanup?.());
</script>

<template>
  <cap-sheet id="booking-sheet" ref="sheetRef">
    <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
    <cap-sheet-view>
      <cap-sheet-backdrop />
      <cap-sheet-content>
        <cap-sheet-handle />
        <cap-sheet-title>Vue sheet</cap-sheet-title>
      </cap-sheet-content>
    </cap-sheet-view>
  </cap-sheet>
</template>

Angular

import { AfterViewInit, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild } from '@angular/core';
import { setupSheet } from '@capgo/capacitor-sheets/angular';
import '@capgo/capacitor-sheets';

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <cap-sheet id="booking-sheet" #sheet>
      <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
      <cap-sheet-view>
        <cap-sheet-backdrop></cap-sheet-backdrop>
        <cap-sheet-content>
          <cap-sheet-handle></cap-sheet-handle>
          <cap-sheet-title>Angular sheet</cap-sheet-title>
        </cap-sheet-content>
      </cap-sheet-view>
    </cap-sheet>
  `,
})
export class AppComponent implements AfterViewInit {
  @ViewChild('sheet', { static: true }) sheet?: ElementRef<HTMLElement>;

  ngAfterViewInit(): void {
    if (this.sheet?.nativeElement) {
      setupSheet(this.sheet.nativeElement, {
        detents: ['18em', '32em'],
        contentPlacement: 'bottom',
      });
    }
  }
}

Svelte

<script lang="ts">
  import { sheet } from '@capgo/capacitor-sheets/svelte';
  import '@capgo/capacitor-sheets';
</script>

<cap-sheet id="booking-sheet" use:sheet={{ detents: ['18em', '32em'], contentPlacement: 'bottom' }}>
  <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
  <cap-sheet-view>
    <cap-sheet-backdrop />
    <cap-sheet-content>
      <cap-sheet-handle />
      <cap-sheet-title>Svelte sheet</cap-sheet-title>
    </cap-sheet-content>
  </cap-sheet-view>
</cap-sheet>

Solid

import { onCleanup, onMount } from 'solid-js';
import { setupSheet } from '@capgo/capacitor-sheets/solid';
import '@capgo/capacitor-sheets';

export function BookingSheet() {
  let sheetEl!: HTMLElement;

  onMount(() => {
    const cleanup = setupSheet(sheetEl, {
      detents: ['18em', '32em'],
      contentPlacement: 'bottom',
    });

    onCleanup(cleanup);
  });

  return (
    <cap-sheet id="booking-sheet" ref={sheetEl}>
      <cap-sheet-trigger action="present">Open</cap-sheet-trigger>
      <cap-sheet-view>
        <cap-sheet-backdrop />
        <cap-sheet-content>
          <cap-sheet-handle />
          <cap-sheet-title>Solid sheet</cap-sheet-title>
        </cap-sheet-content>
      </cap-sheet-view>
    </cap-sheet>
  );
}

컴포넌트

요소	목적
`cap-sheet`	시트 상태, 디텐트, 제스처, 모달 동작 및 이벤트
`cap-sheet-trigger`	선언적 present, dismiss, toggle, step 액션
`cap-sheet-portal`	오버레이 레이어링을 위한 선택적 body 포털
`cap-sheet-view`	safe-area 및 키보드 패딩이 적용된 고정 뷰포트 호스트
`cap-sheet-backdrop`	진행도와 동기화된 배경
`cap-sheet-content`	접근성 지원 시트 서피스
`cap-sheet-bleeding-background`	둥근 모서리 시트를 위한 배경 확장
`cap-sheet-handle`	드래그 및 키보드 접근이 가능한 detent 핸들
`cap-sheet-title`	접근성 지원 제목
`cap-sheet-description`	접근성 지원 설명
`cap-sheet-special-wrapper`	분리된 시트, 카드, 라이트박스를 위한 컴포지션 훅
`cap-sheet-stack`	스택된 시트 그룹핑
`cap-sheet-outlet`	깊이, 패럴랙스, 페이지 효과를 위한 진행도 아웃렛
`cap-scroll`	스크롤 진행률 헬퍼
`cap-fixed`	고정 레이어 헬퍼
`cap-island`	관련 플로팅 아일랜드 콘텐츠
`cap-external-overlay`	시트 트리 외부에서 관리되는 오버레이 콘텐츠

주요 옵션

옵션	항목	기본값	설명
`contentPlacement`	`content-placement`	`bottom`	`top`, `bottom`, `left`, `right`, 또는 `center`
`detents`	`detents`	없음	공백으로 구분된 CSS 길이 값, 예: `18em 32em`
`safeArea`	`safe-area`	`auto`	보호된 safe-area 가장자리
`swipe`	`swipe`	`true`	포인터, 터치, 트랙패드, 휠 제스처 활성화
`swipeDismissal`	`swipe-dismissal`	`true`	제스처로 detent까지 닫기 허용 `0`
`inertOutside`	`inert-outside`	`true`	모달 시트 뒤 상호작용 방지
`focusTrap`	`focus-trap`	`true`	시트 내부에 키보드 포커스 유지
`closeOnOutsideClick`	`close-on-outside-click`	`true`	백드롭 또는 뷰 클릭 시 닫기
`closeOnEscape`	`close-on-escape`	`true`	Escape 키 입력 시 닫기
`nativeFocusScrollPrevention`	`native-focus-scroll-prevention`	`true`	포커스된 입력창이 키보드 위에 보이도록 유지
`themeColorDimming`	`theme-color-dimming`	`auto`	모달 표시 중 WebView 테마 색상 어둡게 처리

사용 가능한 Entrypoints

@capgo/capacitor-sheets
@capgo/capacitor-sheets/react
@capgo/capacitor-sheets/vue
@capgo/capacitor-sheets/angular
@capgo/capacitor-sheets/svelte
@capgo/capacitor-sheets/solid

시작하기 다음 단계

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