Ordo UI
组件Overlays

Dialog

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

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

变体轴

size
defaultwidexlfulldefault 居中 448 / wide 宽面板 896 / xl 超宽 1152 / full 全屏工作面
变体演示dialog

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/dialog.tsx
"use client"

import * as React from "react"
import { Dialog as DialogPrimitive } from "@base-ui/react/dialog"

import { useMessages } from "../i18n"
import { cn } from "../lib/utils"
import { Button } from "./button"
import { XIcon } from "lucide-react"

function Dialog({ ...props }: DialogPrimitive.Root.Props) {
  return <DialogPrimitive.Root data-slot="dialog" {...props} />
}

function DialogTrigger({ ...props }: DialogPrimitive.Trigger.Props) {
  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />
}

function DialogPortal({ ...props }: DialogPrimitive.Portal.Props) {
  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
}

function DialogClose({ ...props }: DialogPrimitive.Close.Props) {
  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />
}

function DialogOverlay({
  className,
  ...props
}: DialogPrimitive.Backdrop.Props) {
  return (
    <DialogPrimitive.Backdrop
      data-slot="dialog-overlay"
      className={cn(
        "fixed inset-0 isolate z-modal bg-scrim-overlay backdrop-blur-sm duration-normal data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
        className
      )}
      {...props}
    />
  )
}

function DialogContent({
  className,
  children,
  showCloseButton = true,
  keepDefaultWidth = true,
  size = "default",
  ...props
}: DialogPrimitive.Popup.Props & {
  showCloseButton?: boolean
  keepDefaultWidth?: boolean
  /**
   * 形态档(§19.4 D2:新形态在组件内新增变体轴,不靠消费方 className 覆盖;宽度档规范见宪法 §10.8):
   * - default:居中呼吸弹窗(基线,sm:max-w-md;消费方可 className 覆盖 max-w 微调至 lg/xl/2xl 既有事实档)
   * - wide:宽面板(多卡并排/大组件承载,sm:max-w-4xl=896)——补 2xl(672) 与 full 之间的宽弹窗缺口档
   * - xl:超宽工作面(PDF 预览/宽表格,sm:max-w-6xl=1152)——1440 窗口下不靠 className 覆盖
   * - full:全屏工作面(图表精读/大内容承载)——inset-0 整屏 flex 列
   */
  size?: "default" | "wide" | "xl" | "full"
}) {
  const M = useMessages()

  return (
    <DialogPortal>
      <DialogOverlay />
      <DialogPrimitive.Popup
        data-slot="dialog-content"
        data-size={size}
        className={cn(
          size === "full"
            ? "fixed inset-0 z-modal flex h-dvh w-full flex-col gap-0 overflow-y-auto overscroll-contain rounded-none border-0 bg-background p-0 text-sm text-foreground shadow-none duration-normal outline-none data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0"
            :
          "fixed top-1/2 left-1/2 z-modal grid max-h-[85vh] w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-6 overflow-y-auto overscroll-contain rounded-xl bg-popover/95 backdrop-blur-xl p-6 text-sm text-popover-foreground border border-border/70 shadow-xs ring-1 ring-border/40 duration-normal outline-none data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
          keepDefaultWidth && size === "default" && "sm:max-w-md",
          size === "wide" && "sm:max-w-4xl",
          size === "xl" && "sm:max-w-6xl",
          className
        )}
        {...props}
      >
        {children}
        {showCloseButton && (
          <DialogPrimitive.Close
            data-slot="dialog-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>
          </DialogPrimitive.Close>
        )}
      </DialogPrimitive.Popup>
    </DialogPortal>
  )
}

function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="dialog-header"
      className={cn("flex flex-col gap-2 pe-12", className)}
      {...props}
    />
  )
}

function DialogFooter({
  className,
  showCloseButton = false,
  children,
  ...props
}: React.ComponentProps<"div"> & {
  showCloseButton?: boolean
}) {
  const M = useMessages()

  return (
    <div
      data-slot="dialog-footer"
      className={cn(
        "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
        className
      )}
      {...props}
    >
      {/* P3-06:Close 先渲染,column-reverse 下才排在操作按钮下方;桌面右对齐用 order-last */}
      {showCloseButton && (
        <DialogPrimitive.Close
          render={<Button variant="outline" className="sm:order-last" />}
        >
          {M.common.close}
        </DialogPrimitive.Close>
      )}
      {children}
    </div>
  )
}

function DialogTitle({ className, ...props }: DialogPrimitive.Title.Props) {
  return (
    <DialogPrimitive.Title
      data-slot="dialog-title"
      className={cn("font-heading text-heading-4 font-semibold", className)}
      {...props}
    />
  )
}

function DialogDescription({
  className,
  ...props
}: DialogPrimitive.Description.Props) {
  return (
    <DialogPrimitive.Description
      data-slot="dialog-description"
      className={cn(
        "text-sm text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
        className
      )}
      {...props}
    />
  )
}

export {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogOverlay,
  DialogPortal,
  DialogTitle,
  DialogTrigger,
}

可访问性与 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。

用法说明

通用模态弹窗,由 Dialog、Trigger、Content、Header、Title、Description、Footer 组合;受控用 open 与 onOpenChange。PDF 预览/宽表格用 size="xl"(sm:max-w-6xl),不要再靠 className 覆盖 max-w。

宽度档位

DialogContent 的 size 轴覆盖居中弹窗的常见宽度,消费方不再用 className="sm:max-w-…" 覆盖:

size断点内最大宽度适用场景
defaultsm:max-w-md(448px)表单、确认、设置
widesm:max-w-4xl(896px)多卡并排、大组件承载
xlsm:max-w-6xl(1152px)PDF 预览、宽表格
full整屏(inset-0)图表精读、全屏工作面

窄屏(< sm)下所有档位仍受 max-w-[calc(100%-2rem)] 约束,保持呼吸边距。