Ordo UI
组件Overlays

Sheet

@mox-hub/ui 组件 · Overlays · canonical

sheet@mox-hub/uiOverlayscanonicalsrc/components/sheet.tsx

变体轴

side
toprightbottomleft物理方向;内缘描边随书写方向镜像
变体演示sheet

Props API

Prop类型默认值说明
openboolean—Whether the dialog is currently open.
defaultOpenboolean—Whether the dialog is initially open.
modalboolean | "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.
disablePointerDismissalboolean—Whether to prevent the dialog from closing on outside presses.
actionsRefReact.RefObject<DialogRootActions>—A ref to imperative actions.
handleDialogHandle<unknown>—A handle to associate the dialog with a trigger.
childrenReact.ReactNode | PayloadChildRenderFunction<unknown>—The content of the dialog.
triggerIdstring—ID of the trigger that the dialog is associated with.
defaultTriggerIdstring—ID of the trigger that the dialog is associated with.

源码

packages/ui/src/components/sheet.tsx
"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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

边缘滑出面板,由 Sheet、Trigger、Content、Header、Title、Footer 组合;side 控制滑出方向。