Getting Started

复制一个包含安装步骤和完整 Markdown 指南的设置提示。

        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 助手设置来安装插件。使用以下命令将 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.

如果您更喜欢手动设置，请运行以下命令安装插件，并按照以下平台特定的说明进行操作：

安装包
终端窗口
```
npm install @capgo/capacitor-sheets
```
注册 Web 组件
```
import '@capgo/capacitor-sheets';
```

添加安全区域的视口设置

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

渲染一个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;
}

Capacitor安全区域

安全区域默认开启通过 safe-area="auto"。该sheet视图读取浏览器环境值和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>

标题：命令式控制

Copy to clipboard

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 还报告未知标签，请在源树中添加声明文件：

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`	表格状态、凹点、手势、模式行为和事件
`cap-sheet-trigger`	声明性现实、关闭、切换和步骤操作
`cap-sheet-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 for detached sheets, cards, and lightboxes
`cap-sheet-stack`	分组的堆叠sheet
`cap-sheet-outlet`	进度输出器，用于实现深度、抖动和页面效果
`cap-scroll`	滚动进度辅助器
`cap-fixed`	固定层辅助器
`cap-island`	相关浮动岛内容
`cap-external-overlay`	在sheet树之外管理的覆盖内容

主选项

选项	属性	默认值	描述
`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`	按下 Esc 键时消失
`closeOnEscape`	`close-on-escape`	`true`	在键盘上方保持焦点输入
`nativeFocusScrollPrevention`	`native-focus-scroll-prevention`	`true`	__CAPGO_KEEP_0__
`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 中继续

如果您正在使用 Getting Started 来规划原生插件工作，连接它到 Capgo 插件目录在 Capgo 插件目录中为产品工作流程由 Capgo 提供的 Capacitor 插件 for the implementation detail in Capacitor Plugins by Capgo, 添加或更新插件为添加或更新插件的实现细节 Ionic 企业插件替代品为 Ionic 企业插件替代品的产品工作流程 Capgo 原生构建为 Capgo 原生构建的产品工作流程