开始使用

Copy a setup prompt with the install steps and the full markdown guide for this plugin.

        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.

Install the package
Terminal window
```
npm install @capgo/capacitor-sheets
```
Register the web components
```
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 Areas

安全区域默认开启通过 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>

命令式控制

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

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`	用于独立弹出窗口、卡片和轻盒的组合钩子
`cap-sheet-stack`	堆叠的弹出窗口分组
`cap-sheet-outlet`	用于控制深度、抖动和页面效果的进度输出
`cap-scroll`	用于辅助滚动进度的滚动进度帮助
`cap-fixed`	用于辅助固定层的固定层帮助
`cap-island`	与浮动岛相关的内容
`cap-external-overlay`	在弹出窗口树之外管理的覆盖内容

主要选项

__CAPGO_KEEP_0__	属性	默认	描述
`contentPlacement`	`content-placement`	`bottom`	`top`, `bottom`, `left`, `right`或 `center`
`detents`	`detents`	无	例如 `18em 32em`
`safeArea`	`safe-area`	`auto`	Space-separated CSS lengths such as
`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 主题颜色

可用 Entrypoints

@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 企业插件替代品了解 Ionic 企业插件替代品的产品工作流程 Capgo 原生构建了解 Capgo 原生构建的产品工作流程