对话框

¥Dialog

覆盖在主窗口或其他对话框窗口上的窗口，使下方内容呈现为非活动状态。

import * as React from "react";
import { Dialog } from "radix-ui";
import { Cross2Icon } from "@radix-ui/react-icons";
import "./styles.css";

const DialogDemo = () => (
	<Dialog.Root>
		<Dialog.Trigger asChild>
			<button className="Button violet">Edit profile</button>
		</Dialog.Trigger>
		<Dialog.Portal>
			<Dialog.Overlay className="DialogOverlay" />
			<Dialog.Content className="DialogContent">
				<Dialog.Title className="DialogTitle">Edit profile</Dialog.Title>
				<Dialog.Description className="DialogDescription">
					Make changes to your profile here. Click save when you're done.
				</Dialog.Description>
				<fieldset className="Fieldset">
					<label className="Label" htmlFor="name">
						Name
					</label>
					<input className="Input" id="name" defaultValue="Pedro Duarte" />
				</fieldset>
				<fieldset className="Fieldset">
					<label className="Label" htmlFor="username">
						Username
					</label>
					<input className="Input" id="username" defaultValue="@peduarte" />
				</fieldset>
				<div
					style={{ display: "flex", marginTop: 25, justifyContent: "flex-end" }}
				>
					<Dialog.Close asChild>
						<button className="Button green">Save changes</button>
					</Dialog.Close>
				</div>
				<Dialog.Close asChild>
					<button className="IconButton" aria-label="Close">
						<Cross2Icon />
					</button>
				</Dialog.Close>
			</Dialog.Content>
		</Dialog.Portal>
	</Dialog.Root>
);

export default DialogDemo;

Features

Supports modal and non-modal modes.

Focus is automatically trapped within modal.

Can be controlled or uncontrolled.

Manages screen reader announcements with Title and Description components.

Esc closes the component automatically.

安装

¥Installation

从命令行安装组件。

¥Install the component from your command line.

npm install @radix-ui/react-dialog

结构

¥Anatomy

导入所有部分并将它们组合在一起。

¥Import all parts and piece them together.

import { Dialog } from "radix-ui";

export default () => (
	<Dialog.Root>
		<Dialog.Trigger />
		<Dialog.Portal>
			<Dialog.Overlay />
			<Dialog.Content>
				<Dialog.Title />
				<Dialog.Description />
				<Dialog.Close />
			</Dialog.Content>
		</Dialog.Portal>
	</Dialog.Root>
);

API 参考

¥API Reference

根

¥Root

包含对话框的所有部分。

¥Contains all the parts of a dialog.

Prop	Type	Default
`defaultOpen`	`boolean`	No default value
`open`	`boolean`	No default value
`onOpenChange`	`function`	No default value
`modal`	`boolean`	`true`

触发器

¥Trigger

打开对话框的按钮。

¥The button that opens the dialog.

Prop	Type	Default
`asChild`	`boolean`	`false`

Data attribute	Values
`[data-state]`	`"open" \| "closed"`

门户

¥Portal

使用时，将叠加层和内容部分传送到 body 中。

¥When used, portals your overlay and content parts into the body.

Prop	Type	Default
`forceMount`	`boolean`	No default value
`container`	`HTMLElement`	`document.body`

叠加层

¥Overlay

对话框打开时，覆盖视图非活动部分的图层。

¥A layer that covers the inert portion of the view when the dialog is open.

Prop	Type	Default
`asChild`	`boolean`	`false`
`forceMount`	`boolean`	No default value

Data attribute	Values
`[data-state]`	`"open" \| "closed"`

内容

¥Content

包含在打开的对话框中呈现的内容。

¥Contains content to be rendered in the open dialog.

Prop	Type	Default
`asChild`	`boolean`	`false`
`forceMount`	`boolean`	No default value
`onOpenAutoFocus`	`function`	No default value
`onCloseAutoFocus`	`function`	No default value
`onEscapeKeyDown`	`function`	No default value
`onPointerDownOutside`	`function`	No default value
`onInteractOutside`	`function`	No default value

Data attribute	Values
`[data-state]`	`"open" \| "closed"`

关闭

¥Close

关闭对话框的按钮。

¥The button that closes the dialog.

Prop	Type	Default
`asChild`	`boolean`	`false`

标题

¥Title

对话框打开时会显示可访问的标题。

¥An accessible title to be announced when the dialog is opened.

如果你想隐藏标题，请将其封装在我们的视觉隐藏实用程序中，例如 <VisuallyHidden asChild>。

¥If you want to hide the title, wrap it inside our Visually Hidden utility like this <VisuallyHidden asChild>.

Prop	Type	Default
`asChild`	`boolean`	`false`

描述

¥Description

一个可选的可访问描述，在对话框打开时显示。

¥An optional accessible description to be announced when the dialog is opened.

如果你想隐藏描述，请将其封装在我们的视觉隐藏实用程序中，例如 <VisuallyHidden asChild>。如果你想完全删除描述，请删除此部分并将 aria-describedby={undefined} 传递给 Dialog.Content。

¥If you want to hide the description, wrap it inside our Visually Hidden utility like this <VisuallyHidden asChild>. If you want to remove the description entirely, remove this part and pass aria-describedby={undefined} to Dialog.Content.

Prop	Type	Default
`asChild`	`boolean`	`false`

示例

¥Examples

异步表单提交后关闭

¥Close after asynchronous form submission

使用受控属性，在异步操作完成后以编程方式关闭对话框。

¥Use the controlled props to programmatically close the Dialog after an async operation has completed.

import * as React from "react";
import { Dialog } from "radix-ui";

const wait = () => new Promise((resolve) => setTimeout(resolve, 1000));

export default () => {
	const [open, setOpen] = React.useState(false);

	return (
		<Dialog.Root open={open} onOpenChange={setOpen}>
			<Dialog.Trigger>Open</Dialog.Trigger>
			<Dialog.Portal>
				<Dialog.Overlay />
				<Dialog.Content>
					<form
						onSubmit={(event) => {
							wait().then(() => setOpen(false));
							event.preventDefault();
						}}
					>
						{/** some inputs */}
						<button type="submit">Submit</button>
					</form>
				</Dialog.Content>
			</Dialog.Portal>
		</Dialog.Root>
	);
};

可滚动覆盖层

¥Scrollable overlay

将内容移至叠加层内，以渲染带有溢出的对话框。

¥Move the content inside the overlay to render a dialog with overflow.

// index.jsx
import { Dialog } from "radix-ui";
import "./styles.css";

export default () => {
	return (
		<Dialog.Root>
			<Dialog.Trigger />
			<Dialog.Portal>
				<Dialog.Overlay className="DialogOverlay">
					<Dialog.Content className="DialogContent">...</Dialog.Content>
				</Dialog.Overlay>
			</Dialog.Portal>
		</Dialog.Root>
	);
};

/* styles.css */
.DialogOverlay {
	background: rgba(0 0 0 / 0.5);
	position: fixed;
	top: 0;
	left: 0;
	right: 0;
	bottom: 0;
	display: grid;
	place-items: center;
	overflow-y: auto;
}

.DialogContent {
	min-width: 300px;
	background: white;
	padding: 30px;
	border-radius: 4px;
}

自定义门户容器

¥Custom portal container

自定义对话框的入口元素。

¥Customise the element that your dialog portals into.

import * as React from "react";
import { Dialog } from "radix-ui";

export default () => {
	const [container, setContainer] = React.useState(null);
	return (
		<div>
			<Dialog.Root>
				<Dialog.Trigger />
				<Dialog.Portal container={container}>
					<Dialog.Overlay />
					<Dialog.Content>...</Dialog.Content>
				</Dialog.Portal>
			</Dialog.Root>

			<div ref={setContainer} />
		</div>
	);
};

可访问性

¥Accessibility

遵循对话框 WAI-ARIA 设计模式。

¥Adheres to the Dialog WAI-ARIA design pattern.

键盘交互

¥Keyboard Interactions

Key	Description
`Space`	Opens/closes the dialog.
`Enter`	Opens/closes the dialog.
`Tab`	Moves focus to the next focusable element.
`Shift + Tab`	Moves focus to the previous focusable element.
`Esc`	Closes the dialog and moves focus to `Dialog.Trigger`.

自定义 API

¥Custom APIs

通过将原始部分抽象到你自己的组件中来创建你自己的 API。

¥Create your own API by abstracting the primitive parts into your own component.

抽象覆盖层和关闭按钮

¥Abstract the overlay and the close button

此示例抽象了 Dialog.Overlay 和 Dialog.Close 部分。

¥This example abstracts the Dialog.Overlay and Dialog.Close parts.

用法

¥Usage

import { Dialog, DialogTrigger, DialogContent } from "./your-dialog";

export default () => (
	<Dialog>
		<DialogTrigger>Dialog trigger</DialogTrigger>
		<DialogContent>Dialog Content</DialogContent>
	</Dialog>
);

实现

¥Implementation

// your-dialog.jsx
import * as React from "react";
import { Dialog as DialogPrimitive } from "radix-ui";
import { Cross1Icon } from "@radix-ui/react-icons";

export const DialogContent = React.forwardRef(
	({ children, ...props }, forwardedRef) => (
		<DialogPrimitive.Portal>
			<DialogPrimitive.Overlay />
			<DialogPrimitive.Content {...props} ref={forwardedRef}>
				{children}
				<DialogPrimitive.Close aria-label="Close">
					<Cross1Icon />
				</DialogPrimitive.Close>
			</DialogPrimitive.Content>
		</DialogPrimitive.Portal>
	),
);

export const Dialog = DialogPrimitive.Root;
export const DialogTrigger = DialogPrimitive.Trigger;

Previous上下文菜单

Next下拉菜单

概览

指南

组件

实用工具

对话框