@capgo/capacitor-sheets

Build Silk-style sheets, drawers, dialogs, toasts, lightboxes, cards, and page overlays in any Capacitor frontend.

开始使用 GitHub

框架无关

直接使用基于标准的自定义元素或使用React、Vue、Angular、Svelte和Solid的设置助手.

Capacitor

从Web层中尊严地处理安全区域、键盘移动、原生边缘手势和WebView主题颜色减淡.

每个sheet形状

组合底部sheet、侧边抽屉、顶部sheet、居中的对话框、toast、分离的sheet、卡片、页面和光箱.

现代CSS

使用 em, rem,视口单位, calc(),和CSS变量来设置尺寸，而尺寸的默认值仍然 em 基于。

When To Use It

@capgo/capacitor-sheets 适用于需要高质量移动弹出层但不需要采用特定UI框架的Capacitor应用。它以自定义元素形式提供，因此核心包不依赖于React、Vue、Angular、Svelte或Solid运行时。

使用它时需要:

底部弹出层（含一个或多个凹点）
左侧或右侧侧边栏和顶部弹出层
居中的对话框、光箱、卡片和toast样式弹出层
始终显示的弹出层，保持应用后面可交互
从边缘进入的全屏弹出层
由弹出层进度驱动的堆栈、深度和抖动效果
暴露进度和距离值的滚动辅助
Capacitor安全的布局，适用于凸起、主屏幕指示器、Android切口和软件键盘

用例覆盖

用例	Capgo Sheets模式
长Sheet	`cap-sheet` 自然内容滚动或 `cap-scroll`
Sheet with Detent	`detents="18em 32em"` 加 `stepTo()` 或一个步骤触发器
侧边栏	`content-placement="left"` 或 `content-placement="right"`
底部弹出窗	默认 `content-placement="bottom"`
带有键盘和视觉视口偏移处理的弹出窗	`native-focus-scroll-prevention` Toast
,并且不支持外部点击关闭	`inert-outside="false"`, `focus-trap="false"`脱离式弹出窗
加上自定义边距和圆角	`cap-sheet-special-wrapper` 从底部弹出窗
全屏底部弹出窗内容	Capgo
顶部面板	`content-placement="top"`
具有堆叠的面板	`cap-sheet-stack` 具有深度变量
具有深度的面板	`cap-sheet-outlet` 和进度驱动的变换
抖动页面	`cap-sheet-outlet` 具有 `cap-scroll` 进度
页面	全视图内容从边缘进入
光盒	`content-placement="center"` 具有背景和媒体内容
Persistent Sheet with Detent	`default-presented`, `swipe-dismissal="false"`, 和 `inert-outside="false"`
Card	紧凑居中的弹出窗口内容

核心 API

<cap-sheet> 控制弹出窗口的显示状态、凹点、位置、手势、辅助功能和事件。
<cap-sheet-trigger> 声明了present、dismiss、toggle和detent-step动作。
<cap-sheet-view> 调整弹出窗口的位置并应用安全区域和键盘偏移。
<cap-sheet-backdrop> 渲染一个进度同步的背景。
<cap-sheet-content> 渲染弹出窗口的表面。
<cap-sheet-handle> 提供拖动和键盘凹点控制。
<cap-sheet-stack> 坐标堆叠的表格。
<cap-sheet-outlet> 暴露给页面、深度和抖动效果的表格进度。
<cap-scroll> 和 <cap-scroll-content> 暴露滚动进度和距离辅助函数。
setupSheet(element, options?) 配置一个从框架效果或生命周期钩子中获取的表格。

Capacitor 布局模型

默认表格视图读取 env(safe-area-inset-*) 和 Capacitor-样式 --safe-area-inset-* fallback 变量，然后将选定的边作为覆盖层的填充。 safe-area="auto" 保护所有边；使用 safe-area="bottom left right" 或 safe-area="none" 当一个场景需要不同的行为时。

键盘处理默认启用。该弹出窗口监听 visualViewport resize 和 scroll 事件，向视口添加键盘偏移，并将 preventScroll 控制焦点到输入框，以便输入框始终可见于软件键盘上。

该包在 web 层运行。它不渲染原生 UIKit 或 Android 底部弹出窗口，因此您的应用程序始终保持全面的样式控制，同时仍然尊严 WebView 的约束，尤其是 Capacitor。

演示和沙盒

支持的每个场景都有 Animated WebP 演示，位于仓库 README 中。示例也可作为 StackBlitz playgrounds 获得：

长弹出窗口	凹点

侧边栏	光盘

继续从@capgo/capacitor-sheets

如果您正在使用 @capgo/capacitor-sheets 与 Capgo Native 插件目录 for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, __CAPGO_KEEP_0__ Native 插件的实现细节添加或更新插件添加或更新插件的实现细节 Capgo Native Builds 为产品工作流程在Capgo原生构建中.