Panduan Memulai

Salin prompt setup yang berisi langkah install dan panduan markdown lengkap untuk plugin ini.

        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.

Instalasi

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

Instal package
Jendela terminal
```
bun add @capgo/capacitor-sheets
```
Daftarkan web components
```
import '@capgo/capacitor-sheets';
```

Tambahkan pengaturan viewport untuk safe areas

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

Render sheet

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

Kesalahan umum

Daftarkan komponen: import @capgo/capacitor-sheets sekali saat bootstrap, atau elemen tidak akan di-upgrade.
Viewport fit: tidak ada viewport-fit=cover merusak padding safe area di ponsel ber-notch.
Keyboard: aktifkan pencegahan scroll fokus yang terdokumentasi saat input berada di dalam bottom sheet.

Capacitor Area Aman

Safe areas diaktifkan secara default melalui safe-area="auto". Viewport sheet membaca nilai environment browser dan variabel fallback 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)

Pilih tepi yang dilindungi per sheet:

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

Untuk aplikasi dengan status bar overlay atau system bar, pertahankan plugin native yang bertanggung jawab untuk mengekspos nilai inset yang benar:

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

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

export default config;

Penanganan keyboard dikendalikan oleh native-focus-scroll-prevention, yang secara default diatur ke true. Nonaktifkan hanya jika aplikasi Anda sudah menangani penghindaran keyboard:

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

Kontrol Imperatif

Semua helper framework mengonfigurasi custom element yang sama di baliknya. Anda juga dapat mengontrol sheet secara langsung:

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

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

Dengarkan event untuk state yang terkontrol, analitik, atau animasi yang terkoordinasi:

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

Mengimpor dari @capgo/capacitor-sheets/react juga mendaftarkan typings JSX untuk elemen kustom. Jika TypeScript masih melaporkan tag yang tidak dikenal, tambahkan file deklarasi di dalam tree sumber Anda:

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

Komponen

Elemen	Tujuan
`cap-sheet`	State sheet, detents, gesture, perilaku modal, dan event
`cap-sheet-trigger`	Aksi deklaratif untuk present, dismiss, toggle, dan step
`cap-sheet-portal`	Body portal opsional untuk layering overlay
`cap-sheet-view`	Viewport host tetap dengan padding safe-area dan keyboard
`cap-sheet-backdrop`	Backdrop yang tersinkronisasi dengan progres
`cap-sheet-content`	Permukaan sheet yang aksesibel
`cap-sheet-bleeding-background`	Ekstensi latar belakang untuk sheet dengan tepi membulat
`cap-sheet-handle`	Handle detent yang bisa digeser dan diakses via keyboard
`cap-sheet-title`	Judul yang aksesibel
`cap-sheet-description`	Deskripsi yang aksesibel
`cap-sheet-special-wrapper`	Hook komposisi untuk sheet terpisah, kartu, dan lightbox
`cap-sheet-stack`	Pengelompokan sheet bertumpuk
`cap-sheet-outlet`	Outlet progres untuk efek kedalaman, paralaks, dan halaman
`cap-scroll`	Helper progres scroll
`cap-fixed`	Helper lapisan tetap
`cap-island`	Konten floating island terkait
`cap-external-overlay`	Konten overlay yang dikelola di luar sheet tree

Opsi utama

Opsi	Atribut	Default	Deskripsi
`contentPlacement`	`content-placement`	`bottom`	`top`, `bottom`, `left`, `right`, atau `center`
`detents`	`detents`	none	Panjang CSS yang dipisahkan spasi, seperti `18em 32em`
`safeArea`	`safe-area`	`auto`	Tepi safe-area yang dilindungi
`swipe`	`swipe`	`true`	Aktifkan gestur pointer, sentuh, trackpad, dan scroll wheel
`swipeDismissal`	`swipe-dismissal`	`true`	Izinkan gestur untuk menutup ke detent `0`
`inertOutside`	`inert-outside`	`true`	Cegah interaksi di belakang sheet modal
`focusTrap`	`focus-trap`	`true`	Jaga fokus keyboard tetap di dalam sheet
`closeOnOutsideClick`	`close-on-outside-click`	`true`	Tutup saat mengklik backdrop atau view
`closeOnEscape`	`close-on-escape`	`true`	Tutup saat menekan Escape
`nativeFocusScrollPrevention`	`native-focus-scroll-prevention`	`true`	Jaga input yang difokuskan tetap terlihat di atas keyboard
`themeColorDimming`	`theme-color-dimming`	`auto`	Redupkan warna tema WebView saat modal

Entrypoints yang tersedia

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

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan pekerjaan plugin native, hubungkan dengan Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi pada Menambahkan atau Memperbarui Plugin, Alternatif Plugin Ionic Enterprise untuk alur kerja produk di alternatif plugin Ionic Enterprise, dan Capgo Native Build untuk alur kerja produk di Capgo Native Builds.