Getting Started

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

        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

__CAPGO_KEEP_1__

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

__CAPGO_KEEP_2__

__CAPGO_KEEP_3__
__CAPGO_KEEP_4__
```
npm install @capgo/capacitor-sheets
```
__CAPGO_KEEP_5__
```
import '@capgo/capacitor-sheets';
```

__CAPGO_KEEP_6__

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

__CAPGO_KEEP_7__

<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;
}

Capacitor Safe Areas

안전 영역은 기본적으로 사용됩니다. 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>

overlay 상태栏 또는 시스템 바를 가진 앱의 경우, 올바른 inset 값을 노출하는 native 플러그인을 유지하십시오:

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가 여전히 알려지지 않은 태그를 보고 있다면, 소스 tree 내에 선언 파일을 추가하세요.

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>

클립보드 복사

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>
  );
}

Element

__CAPGO_KEEP_0__	__CAPGO_KEEP_0__
`cap-sheet`	Sheet 상태, detents, 제스처, 모달 동작 및 이벤트
`cap-sheet-trigger`	선언적 현재, 닫기, 토글 및 단계 동작
`cap-sheet-portal`	선택적 바디 포탈을 위한 overlay layering
`cap-sheet-view`	안전 영역 및 키보드 패딩을 위한 고정 뷰포트 호스트
`cap-sheet-backdrop`	Progress-synced backdrop
`cap-sheet-content`	접근 가능한 시트 표면
`cap-sheet-bleeding-background`	둥근 모서리 시트를 위한 배경 확장
`cap-sheet-handle`	드래그 가능하고 키보드 접근 가능한 detent handle
`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`	none	CSS 길이(예: `18em 32em`
`safeArea`	`safe-area`	`auto`	안전 영역
`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`	Esc 키 누르면 닫기
`nativeFocusScrollPrevention`	`native-focus-scroll-prevention`	`true`	키보드 위에 보이는 입력 필드 유지
`themeColorDimming`	`theme-color-dimming`	`auto`	모달 시트 WebView 테마 색상 어둡게

Entrypoint이 사용 가능한 것들

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

Getting Started를 계속 진행하세요

__CAPGO_KEEP_0__을 사용 중이라면 Getting Started __CAPGO_KEEP_0__과 연결하여 Capgo 플러그인 디렉토리에서 Capgo 플러그인 디렉토리 내의 제품 워크플로우에 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo의 구현 세부사항에 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부사항에 Ionic Enterprise Plugin Alternatives Ionic Enterprise Plugin Alternatives의 제품 워크플로우를 위해, 그리고 Capgo Native Builds Capgo Native Builds의 제품 워크플로우를 위해.