组件Overlays
Sheet
@mox-hub/ui 组件 · Overlays · canonical
sheet@mox-hub/uiOverlayscanonicalsrc/components/sheet.tsx变体轴
sidetoprightbottomleft物理方向;内缘描边随书写方向镜像
变体演示sheet
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| open | boolean | — | Whether the dialog is currently open. |
| defaultOpen | boolean | — | Whether the dialog is initially open. |
| modal | boolean | "trap-focus" | — | Determines if the dialog enters a modal state when open. |
| onOpenChange | (open: boolean, eventDetails: DialogRoot.ChangeEventDetails) => void | — | Event handler called when the dialog is opened or closed. |
| onOpenChangeComplete | (open: boolean) => void | — | Event handler called after any animations complete when the dialog is opened or closed. |
| disablePointerDismissal | boolean | — | Whether to prevent the dialog from closing on outside presses. |
| actionsRef | React.RefObject<DialogRootActions> | — | A ref to imperative actions. |
| handle | DialogHandle<unknown> | — | A handle to associate the dialog with a trigger. |
| children | React.ReactNode | PayloadChildRenderFunction<unknown> | — | The content of the dialog. |
| triggerId | string | — | ID of the trigger that the dialog is associated with. |
| defaultTriggerId | string | — | ID of the trigger that the dialog is associated with. |
源码
"use client"
import * as React from "react"
import { Dialog as SheetPrimitive } from "@base-ui/react/dialog"
import { useDirection } from "@base-ui/react/direction-provider"
import { useMessages } from "../i18n"
import { cn } from "../lib/utils"
import { Button } from "./button"
import { XIcon } from "lucide-react"
function Sheet({ ...props }: SheetPrimitive.Root.Props) {
return <SheetPrimitive.Root data-slot="sheet" {...props} />
}
function SheetTrigger({ ...props }: SheetPrimitive.Trigger.Props) {
return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />
}
function SheetClose({ ...props }: SheetPrimitive.Close.Props) {
return <SheetPrimitive.Close data-slot="sheet-close" {...props} />
}
function SheetPortal({ ...props }: SheetPrimitive.Portal.Props) {
return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />
}
function SheetOverlay({ className, ...props }: SheetPrimitive.Backdrop.Props) {
return (
<SheetPrimitive.Backdrop
data-slot="sheet-overlay"
className={cn(
"fixed inset-0 z-modal bg-scrim-overlay transition-opacity duration-normal data-ending-style:opacity-0 data-starting-style:opacity-0 supports-backdrop-filter:backdrop-blur-sm",
className
)}
{...props}
/>
)
}
function SheetContent({
className,
children,
side = "right",
showCloseButton = true,
...props
}: SheetPrimitive.Popup.Props & {
side?: "top" | "right" | "bottom" | "left"
showCloseButton?: boolean
}) {
// 宽度默认档按 side 在 JS 里注入纯类(w-3/4 sm:max-w-sm),不能写成
// data-[side=right]:sm:max-w-sm 之类的双变体链——tailwind-merge 不去重
// 变体链不同的类,属性选择器特异性 (0,2,0) 会反杀消费方的 sm:max-w-*xl 覆盖。
const isHorizontal = side === "left" || side === "right"
const direction = useDirection()
// side 是物理方向,而边框必须落在「面板内侧」:LTR 左面板的内侧是右(border-e),
// RTL 左面板的内侧是右(border-s)。逻辑属性不能只写静态一条,否则 RTL 下描边跑到外缘。
const horizontalBorder =
side === "left"
? direction === "rtl"
? "border-s"
: "border-e"
: direction === "rtl"
? "border-e"
: "border-s"
const M = useMessages()
return (
<SheetPortal>
<SheetOverlay />
<SheetPrimitive.Popup
data-slot="sheet-content"
data-side={side}
className={cn(
"fixed z-modal flex flex-col gap-4 overflow-y-auto overscroll-contain bg-popover bg-clip-padding text-sm text-popover-foreground shadow-xs transition duration-normal ease-in-out data-ending-style:opacity-0 data-starting-style:opacity-0 data-[side=bottom]:inset-x-0 data-[side=bottom]:bottom-0 data-[side=bottom]:max-h-[85vh] data-[side=bottom]:border-t data-[side=bottom]:data-ending-style:translate-y-10 data-[side=bottom]:data-starting-style:translate-y-10 data-[side=left]:inset-y-0 data-[side=left]:left-0 data-[side=left]:h-full data-[side=left]:data-ending-style:-translate-x-10 data-[side=left]:data-starting-style:-translate-x-10 data-[side=right]:inset-y-0 data-[side=right]:right-0 data-[side=right]:h-full data-[side=right]:data-ending-style:translate-x-10 data-[side=right]:data-starting-style:translate-x-10 data-[side=top]:inset-x-0 data-[side=top]:top-0 data-[side=top]:max-h-[85vh] data-[side=top]:border-b data-[side=top]:data-ending-style:-translate-y-10 data-[side=top]:data-starting-style:-translate-y-10",
isHorizontal && "w-3/4 sm:max-w-sm",
isHorizontal && horizontalBorder,
className
)}
{...props}
>
{children}
{showCloseButton && (
<SheetPrimitive.Close
data-slot="sheet-close"
render={
<Button
variant="ghost"
className="absolute top-4 end-4 pointer-coarse:size-11"
size="icon-sm"
/>
}
>
<XIcon
/>
<span className="sr-only">{M.common.close}</span>
</SheetPrimitive.Close>
)}
</SheetPrimitive.Popup>
</SheetPortal>
)
}
function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="sheet-header"
className={cn("flex flex-col gap-1.5 p-4 pe-12", className)}
{...props}
/>
)
}
function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="sheet-footer"
className={cn("mt-auto flex flex-col items-end gap-2 p-4", className)}
{...props}
/>
)
}
function SheetTitle({ className, ...props }: SheetPrimitive.Title.Props) {
return (
<SheetPrimitive.Title
data-slot="sheet-title"
className={cn(
"font-heading text-heading-4 font-semibold text-foreground",
className
)}
{...props}
/>
)
}
function SheetDescription({
className,
...props
}: SheetPrimitive.Description.Props) {
return (
<SheetPrimitive.Description
data-slot="sheet-description"
className={cn("text-sm text-muted-foreground", className)}
{...props}
/>
)
}
export {
Sheet,
SheetTrigger,
SheetClose,
SheetContent,
SheetHeader,
SheetFooter,
SheetTitle,
SheetDescription,
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
边缘滑出面板,由 Sheet、Trigger、Content、Header、Title、Footer 组合;side 控制滑出方向。