组件Overlays
Dialog
@mox-hub/ui 组件 · Overlays · canonical
dialog@mox-hub/uiOverlayscanonicalsrc/components/dialog.tsx变体轴
sizedefaultwidexlfulldefault 居中 448 / wide 宽面板 896 / xl 超宽 1152 / full 全屏工作面
变体演示dialog
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 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/translatorprops,其次用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 | 断点内最大宽度 | 适用场景 |
|---|---|---|
default | sm:max-w-md(448px) | 表单、确认、设置 |
wide | sm:max-w-4xl(896px) | 多卡并排、大组件承载 |
xl | sm:max-w-6xl(1152px) | PDF 预览、宽表格 |
full | 整屏(inset-0) | 图表精读、全屏工作面 |
窄屏(< sm)下所有档位仍受 max-w-[calc(100%-2rem)] 约束,保持呼吸边距。