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.

설치

Capgo AI 도움을 받는 설치를 사용하여 플러그인을 설치할 수 있습니다. 다음 명령어를 사용하여 Capgo 기능을 AI 도구에 추가하세요:

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.

만약 Manual Setup을 선호한다면, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래의 플랫폼별 지침을 따르세요:

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

안전 영역을 위한 뷰포트 설정 추가

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

제목 "Capacitor Safe Areas"

__CAPGO_KEEP_0__ 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 값을 노출하는 것을 유지하세요:

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

리액트

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

복사 @capgo/capacitor-sheets/react import하는

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

복사

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

앵귤러

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

스벨트

<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	목적
`cap-sheet`	Sheet 상태, detents, 제스처, 모달 동작 및 이벤트
`cap-sheet-trigger`	선언적 현재, 닫기, 토글 및 단계 동작
`cap-sheet-portal`	선택적 오버레이 layering을 위한 바디 portal
`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`	Composition hook for detached sheets, cards, and lightboxes
`cap-sheet-stack`	Stacked sheet grouping
`cap-sheet-outlet`	Progress outlet for depth, parallax, and page effects
`cap-scroll`	Scroll progress helper
`cap-fixed`	Fixed layer helper
`cap-island`	Related floating island content
`cap-external-overlay`	Overlay content managed outside the sheet tree

Main Options

Option	Attribute	Default	설명
`contentPlacement`	`content-placement`	`bottom`	`top`, `bottom`, `left`, `right`, 또는 `center`
`detents`	`detents`	없음	공백으로 구분된 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 테마 색상이 모달에서 어둡게 설정됩니다.

사용 가능한 엔트리 포인트

@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에서 계속 진행하세요.

native 플러그인 작업을 계획하고 있으시다면 Getting Started native 플러그인 작업을 계획하고 있으시다면 __CAPGO_KEEP_0__ 플러그인 디렉토리와 연결하세요. Capgo 플러그인 디렉토리에서 제품 워크플로우를 Capgo 플러그인 디렉토리에서 구현하세요. Capgo 플러그인으로 __CAPGO_KEEP_1__ Capacitor 플러그인으로 Capgo 구현 상세를 구현하세요. Capacitor 플러그인으로 Capgo 구현 상세를 구현하세요. 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 세부 사항 아이오닉 엔터프라이즈 플러그인 대체 아이오닉 엔터프라이즈 플러그인 제품 워크플로우 Capgo 네이티브 빌드 Capgo 네이티브 빌드 제품 워크플로우