快速入门
复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。
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 skills 添加到你的 AI 工具中:
npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins然后使用以下 prompt:
Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-sheets` plugin in my project.如果你更想手动设置,请运行以下命令安装插件,并按照下方各平台的说明操作:
-
安装软件包
终端窗口 bun add @capgo/capacitor-sheets -
注册 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;}
常见坑点
章节标题为“常见陷阱”- 注册组件:在
@capgo/capacitor-sheets启动时导入一次,否则元素将无法升级。 - 视口适配:缺失
viewport-fit=cover会导致刘海屏手机的安全区域内边距失效。 - 键盘:当输入框位于 Bottom Sheet 内部时,启用文档中说明的焦点滚动预防功能。
Capacitor 安全区域
标题为“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)为每个 Sheet 选择需要保护的边缘:
<cap-sheet safe-area="auto"></cap-sheet><cap-sheet safe-area="bottom left right"></cap-sheet><cap-sheet safe-area="none"></cap-sheet>对于带有状态栏或系统栏叠加层的应用,请保留负责提供正确 Inset 值的原生插件:
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>所有 framework 辅助工具配置的都是同一个底层 custom element。您也可以直接控制 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
标题为“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
标题为“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
标题为 “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
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
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 | 符合无障碍标准的 Sheet 表面 |
cap-sheet-bleeding-background | 适用于圆角 Sheet 的背景扩展 |
cap-sheet-handle | 支持拖拽与键盘操作的 Detent 控制柄 |
cap-sheet-title | 符合无障碍标准的标题 |
cap-sheet-description | 符合无障碍标准的描述 |
cap-sheet-special-wrapper | 适用于分离式 Sheet、卡片及 Lightbox 的组合 Hook |
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 | 允许通过手势收起到 detent 0 |
inertOutside | inert-outside | true | 阻止与模态 Sheet 后方内容交互 |
focusTrap | focus-trap | true | 让键盘焦点保持在 Sheet 内 |
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
从入门指南继续
“从入门指南继续”章节如果你正在使用 快速入门 要规划原生插件工作,请将其与 Capgo 插件目录 查看 Capgo 插件目录中的产品工作流, Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节, 添加或更新插件 查看添加或更新插件中的实现细节, Ionic Enterprise 插件替代方案 查看 Ionic Enterprise 插件替代方案中的产品工作流,以及 Capgo Native Build 查看 Capgo Native Builds 中的产品工作流。