开始教程

复制一个带有安装步骤和完整 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"。视图区域读取浏览器环境值和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)

选择每个sheet的保护边缘：

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

命令式控制

所有框架助手都配置相同的自定义元素。您还可以直接控制一个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);
});

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>

复制到剪贴板

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

Components	元素组件
`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`	脱离的表格、卡片和光盒的组合钩子
`cap-sheet-stack`	堆叠的表格分组
`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`	点击背景或视图时关闭
`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

如果您正在使用 Getting Started 来规划原生插件工作，连接它与 Capgo 插件目录在Capgo 插件目录中 Capacitor 插件由Capgo 在Capacitor 插件由Capgo中添加或更新插件在添加或更新插件中 Ionic Enterprise Plugin Alternatives Ionic Enterprise Plugin Alternatives 的产品工作流程,以及 Capgo 原生构建 Capgo 原生构建的产品工作流程,。