スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いの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.

手動セットアップを希望する場合は、以下のコマンドを実行してプラグインをインストールし、下記のプラットフォーム別の手順に従ってください：

1. パッケージをインストール

   bun add @capgo/capacitor-sheets

2. Webコンポーネントを登録する

   import '@capgo/capacitor-sheets';

3. セーフエリア用のviewport設定を追加する

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

4. シートを描画する

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

注意

ネイティブプラグインの登録ステップはありません。次を実行してください： bunx cap sync Webアセットやネイティブプロジェクトの変更を同期する必要がある場合にのみ、通常の Capacitor ワークフローの一部として実行してください。

よくある落とし穴

• コンポーネントを登録： import @capgo/capacitor-sheets をブートストラップ時に一度だけ行ってください。そうしないと要素はアップグレードされません。
• ビューポートフィット：未設定 viewport-fit=cover ノッチ付きのスマートフォンでセーフエリアのパディングが崩れます。
• キーボード: 入力フォームがボトムシート内にある場合、ドキュメント記載のフォーカス時のスクロール防止機能を有効にします。

Capacitor セーフエリア

セーフエリアは、以下を通じてデフォルトで有効になっています： 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>

ステータスバーやシステムバーをオーバーレイ表示するアプリでは、正しいインセット値を返すネイティブプラグインを維持してください：

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>

命令的制御 (Imperative Control)

すべてのフレームワーク用ヘルパーは、共通のカスタム要素を構成しています。シートを直接制御することも可能です：

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

インポート元 @capgo/capacitor-sheets/react また、カスタム要素のJSX型定義も登録されます。もしTypeScriptで依然として未知のタグとしてエラーが出る場合は、ソースツリー内に型定義ファイルを追加してください：

src/capgo-sheets.d.ts

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	Sheetの状態、detents、ジェスチャー、モーダル動作、およびイベント
cap-sheet-trigger	宣言的なpresent、dismiss、toggle、およびstepアクション
cap-sheet-portal	オーバーレイのレイヤー制御用オプションのbody portal
cap-sheet-view	セーフエリアとキーボードパディング対応の固定ビューポートホスト
cap-sheet-backdrop	進捗同期型のバックドロップ
cap-sheet-content	アクセシビリティに配慮したシートサーフェス
cap-sheet-bleeding-background	角丸シート用の背景拡張機能
cap-sheet-handle	ドラッグおよびキーボード操作可能なデテントハンドル
cap-sheet-title	アクセシブルなタイトル
cap-sheet-description	アクセシブルな説明文
cap-sheet-special-wrapper	デタッチドシート、カード、ライトボックス用のComposition hook
cap-sheet-stack	スタックされたシートのグルーピング
cap-sheet-outlet	奥行き、パララックス、ページエフェクト用のProgress 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	保護されたセーフエリアのエッジ
swipe	swipe	true	ポインター、タッチ、トラックパッド、ホイールのジェスチャーを有効化
swipeDismissal	swipe-dismissal	true	ジェスチャーによるデテントへの切り替えを許可 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のテーマカラーを暗くする

利用可能なエントリーポイント

• @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 プラグインディレクトリ Capgo プラグインディレクトリのプロダクトワークフローについては、 Capgo による Capacitor プラグイン Capgo による Capacitor プラグインの実装詳細については、 プラグインの追加または更新 プラグインの追加または更新に関する実装詳細については、 Ionic Enterprise プラグインの代替案 Ionic Enterprise Plugin Alternatives のプロダクトワークフロー、および Capgo Native Build Capgo Native Builds のプロダクトワークフローについては、