SuperAPI AI 工具集

shadcn-syntax-sheet

设计与创作

查看项目

更新于 10-16 05:44

技能介绍

用途:Sheet 是 Dialog 的衍生组件,从视口四个边缘之一滑入,适合构建过滤器面板、侧滑抽屉、离屏导航、设置托盘等边缘锚定容器。它复用 Radix Dialog 原语,状态模型、无障碍规则与受控/非受控语义均与 Dialog 相同,额外增加的是 SheetContent 上的 side 属性和重命名的导出。

主要能力:Sheet 在 v4 导出八个原语,命名对应 Dialog:Sheet、SheetTrigger、SheetClose、SheetContent、SheetHeader、SheetFooter、SheetTitle、SheetDescription。SheetContent 接收 side 属性,取值为 right(默认)、left、top、bottom,决定滑入方向与定位类。SheetContent 内部已渲染 Radix Dialog.Portal 和 Dialog.Overlay,无需自行组合。v4 不导出 SheetPortal 或 SheetOverlay。

使用方式:通过 pnpm dlx shadcn@latest add sheet 安装后,从 @/components/ui/sheet 导入。side 必须字面量写在 SheetContent 上,不要放在根 Sheet 上,否则会被静默忽略。受控状态用 open 配合 onOpenChange,切勿只传 open。触发器为非 button 元素时用 asChild。自定义宽度时向 SheetContent 追加 className,让 cn() 合并,不要替换整个 className 字符串,否则会丢失滑入关键帧。表单场景可将内容包在滚动容器中,保持 Header 与 Footer 固定。

适用场景与选择:居中确认、短表单、警告用 Dialog;侧边导航、过滤器、设置、长表单用 Sheet;移动优先、需要拖拽关闭的底部面板用 Drawer;桌面与移动都想原生体验则结合 shadcn-impl-responsive-dialog-drawer 配方。

限制与无障碍:SheetTitle 是必需的,缺失会触发 dev 警告且屏幕阅读器无标题;SheetDescription 强烈推荐,若省略需向 SheetContent 传 aria-describedby={undefined} 消除警告。焦点在打开时自动锁定并关闭时归还触发器,不要自行添加会与 Radix 冲突的焦点管理。默认 Escape 与外部点击关闭,可通过 onEscapeKeyDown、onPointerDownOutside 覆盖。modal 默认 true 时锁定页面滚动;modal={false} 会禁用焦点陷阱与滚动锁,仅用于非阻塞模式。参考文件 methods.md、examples.md、anti-patterns.md 提供完整签名、六个示例与反模式对照,具体内容暂未提供。