@capgo/capacitor-sheets

框架无关的底部弹层、抽屉、对话框和浮层，专为 Capacitor WebView 优化。

立即开始 GitHub

不限框架

直接使用基于标准的 Custom Elements，或使用适用于 React、Vue、Angular、Svelte 和 Solid 的 setup 辅助函数。

Capacitor 已就绪

在 Web 层即可适配安全区域、键盘移动、原生边缘手势以及 WebView 主题色变暗。

各种 Sheet 形状

构建底部 Sheet、侧边抽屉、顶部 Sheet、居中对话框、Toast、分离式 Sheet、卡片、页面和灯箱。

现代 CSS

用以下方式定义 Detents em, rem，视口单位， calc()，以及 CSS 变量，同时默认尺寸仍以 em 为基础。

平台支持

平台	支持	备注
iOS	Web 层	WKWebView 中的自定义元素
Android	Web 层	Android WebView 中的自定义元素
Web 端	是	Capacitor Web 构建使用相同的组件

适用场景

@capgo/capacitor-sheets 面向需要高质量移动端 Overlay、又不想绑定特定 UI framework 的 Capacitor 应用。它以 custom elements 形式发布，因此核心包没有 React、Vue、Angular、Svelte 或 Solid 的 runtime 依赖。

在以下场景中使用：

带有一个或多个 detent 的底部 Sheet
左侧或右侧 Sidebar 以及顶部 Sheet
居中 Dialog、Lightbox、Card 以及类似 Toast 的 Overlay
让后方应用保持可交互的 Persistent Sheet
从边缘进入的全屏 Overlay
由 Sheet 进度驱动的堆叠、深度和视差效果
可获取进度和距离值的 Scroll Helpers
适配刘海、Home Indicator、Android 挖孔和软键盘的 Capacitor 安全布局

使用场景覆盖

使用场景	Capgo Sheets 模式
长表格	`cap-sheet` 支持原生内容滚动，或 `cap-scroll`
带有 Detent 的 Sheet	`detents="18em 32em"` 加 `stepTo()` 或通过步骤触发
侧边栏	`content-placement="left"` 或 `content-placement="right"`
底部抽屉 (Bottom Sheet)	默认 `content-placement="bottom"`
支持键盘交互的抽屉	`native-focus-scroll-prevention` 以及视觉视口偏移处理
Toast 提示	`inert-outside="false"`, `focus-trap="false"`, 且不支持点击外部关闭
分离式抽屉	`cap-sheet-special-wrapper` 支持自定义边距与圆角
底部全屏页面	全高底部抽屉内容
顶部抽屉	`content-placement="top"`
支持层叠效果的抽屉	`cap-sheet-stack` 支持深度变量
带深度的 Sheet	`cap-sheet-outlet` 以及进度驱动的变换
视差页面	`cap-sheet-outlet` 配合 `cap-scroll` 进度
页面	全视口内容从边缘进入
灯箱	`content-placement="center"` 带背景遮罩和媒体内容
带 Detent 的常驻 Sheet	`default-presented`, `swipe-dismissal="false"`，以及 `inert-outside="false"`
卡片	紧凑居中的 Sheet 内容

核心 API

<cap-sheet> 负责展示状态、detents、位置、手势、无障碍和事件。
<cap-sheet-trigger> 声明 present、dismiss、toggle 和 detent-step 操作。
<cap-sheet-view> 定位遮罩层并应用 safe-area 和键盘偏移量。
<cap-sheet-backdrop> 渲染与进度同步的背景遮罩。
<cap-sheet-content> 渲染 Sheet 表面层。
<cap-sheet-handle> 提供拖拽和键盘 detent 控制。
<cap-sheet-stack> 协调堆叠的 Sheet。
<cap-sheet-outlet> 将 Sheet 进度暴露给页面、深度和视差效果。
<cap-scroll> 以及 <cap-scroll-content> 提供滚动进度和距离的辅助函数。
setupSheet(element, options?) 通过 framework effects 或生命周期钩子配置 sheet。

Capacitor 布局模型

默认的 sheet 视口读取 env(safe-area-inset-*) 以及 Capacitor 风格的 --safe-area-inset-* 备用变量，然后将选定的边缘作为 overlay 周围的内边距。 safe-area="auto" 保护所有边缘；当 safe-area="bottom left right" 或 safe-area="none" 有特定用例需要不同行为时使用。

默认启用键盘处理。sheet 会监听 visualViewport resize 和 scroll 事件，为视口添加键盘偏移，并通过 preventScroll 让输入框在软键盘上方保持可见。

该包运行在 Web 层，不渲染原生 UIKit 或 Android bottom sheet，因此你的应用可以完全控制样式，同时仍遵守 Capacitor 中关键的 WebView 约束。

演示与 Playground

仓库 README 中提供了每个受支持用例的 Animated WebP 演示。示例也可在 StackBlitz playground 中查看：

长表格	Detents

侧边栏	灯箱

继续探索 @capgo/capacitor-sheets

如果你正在使用 @capgo/capacitor-sheets 要规划原生插件工作，请将其与 Capgo 插件目录查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件查看由 Capgo 提供的 Capacitor 插件中的实现细节，添加或更新插件查看添加或更新插件中的实现细节， Ionic Enterprise 插件替代方案查看 Ionic Enterprise 插件替代方案中的产品工作流，以及 Capgo Native Build 查看 Capgo Native Builds 中的产品工作流。