시작하기

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 명령어를 복사하세요.

        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-assisted 설치를 사용하여 플러그인을 설치할 수 있습니다. 다음 명령어를 사용하여 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>
  );
}

import from @capgo/capacitor-sheets/react 또한 사용자 정의 요소에 대한 JSX 타이핑을 등록합니다. TypeScript가 여전히 알려지지 않은 태그를 보고 있다면, 소스 tree 내에 선언 파일을 추가하세요:

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

컴포넌트

요소	목적
`cap-sheet`	페이지/영역: Capgo 마케팅 웹사이트. 역할: 짧은 UI 레이블 또는 네비게이션 아이템. 메시지 키 `subprocessors_table_purpose` (Subprocessors Table Purpose).
`cap-sheet-trigger`	Sheet 상태, detents, 제스처, 모달 동작 및 이벤트
`cap-sheet-portal`	선언적 현재, 취소, 토글 및 단계 동작
`cap-sheet-view`	선택적 바디 포탈을 위한 overlay layering
`cap-sheet-backdrop`	안정된 뷰포트 호스트와 safe-area 및 키보드 패딩
`cap-sheet-content`	Progress-synced backdrop
`cap-sheet-bleeding-background`	접근 가능한 sheet 표면
`cap-sheet-handle`	둥근 모서리 시트를 위한 배경 확장
`cap-sheet-title`	드래그 가능한 및 키보드 접근 가능한 detent 핸들
`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`	가정점으로 sheet를 닫을 수 있도록 허용합니다. `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

시작부터 계속하세요

native 플러그인 작업을 계획하고 있으시다면 Getting Started native 플러그인 작업을 계획하고 있으시다면 Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, 플러그인 추가 또는 업데이트 Adding or Updating Plugins __CAPGO_KEEP_0__ Native Builds __CAPGO_KEEP_0__ Native Builds Capgo Native Builds for the product workflow in Capgo Native Builds.