Skip to Content
文档

对话框

用于显示对话框提示

SourceStorybookRecipeArk

用法

¥Usage

import { Dialog } from "@chakra-ui/react"
<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Backdrop />
  <Dialog.Positioner>
    <Dialog.Content>
      <Dialog.CloseTrigger />
      <Dialog.Header>
        <Dialog.Title />
      </Dialog.Header>
      <Dialog.Body />
      <Dialog.Footer />
    </Dialog.Content>
  </Dialog.Positioner>
</Dialog.Root>

示例

¥Examples

尺寸

¥Sizes

使用 size 属性更改对话框组件的大小。

¥Use the size prop to change the size of the dialog component.

封面

¥Cover

使用 size="cover" 属性使对话框组件覆盖整个屏幕，同时显示后面的一小部分页面。

¥Use the size="cover" prop to make the dialog component cover the entire screen while revealing a small portion of the page behind.

全屏

¥Fullscreen

使用 size="full" 属性使对话框组件占据整个屏幕。

¥Use the size="full" prop to make the dialog component take up the entire screen.

放置位置

¥Placement

使用 placement 属性更改对话框组件的位置。

¥Use the placement prop to change the placement of the dialog component.

受控

¥Controlled

使用 open 和 onOpenChange 属性控制对话框组件的可见性。

¥Use the open and onOpenChange prop to control the visibility of the dialog component.

商店

¥Store

控制对话框的另一种方法是使用 RootProvider 组件和 useDialog 存储钩子。

¥An alternative way to control the dialog is to use the RootProvider component and the useDialog store hook.

这样，你就可以从对话框外部访问对话框的状态和方法。

¥This way you can access the dialog state and methods from outside the dialog.

上下文

¥Context

使用 DialogContext 组件从对话框外部访问对话框状态和方法。

¥Use the DialogContext component to access the dialog state and methods from outside the dialog.

嵌套对话框

¥Nested Dialogs

你可以通过在另一个 Dialog.Root 组件中使用 Dialog.Root 组件来嵌套对话框。

¥You can nest dialogs by using the Dialog.Root component inside another Dialog.Root component.

初始焦点

¥Initial Focus

使用 initialFocusEl 属性设置对话框组件的初始焦点。

¥Use the initialFocusEl prop to set the initial focus of the dialog component.

内部滚动

¥Inside Scroll

使用 scrollBehavior=inside 属性更改对话框内容溢出时的滚动行为。

¥Use the scrollBehavior=inside prop to change the scroll behavior of the dialog when its content overflows.

外部滚动

¥Outside Scroll

使用 scrollBehavior=outside 属性更改对话框内容溢出时的滚动行为。

¥Use the scrollBehavior=outside prop to change the scroll behavior of the dialog when its content overflows.

运动预设

¥Motion Preset

使用 motionPreset 属性更改对话框组件的动画。

¥Use the motionPreset prop to change the animation of the dialog component.

警报对话框

¥Alert Dialog

设置 role: "alertdialog" 属性可将对话框组件更改为警报对话框。

¥Set the role: "alertdialog" prop to change the dialog component to an alert dialog.

外部关闭按钮

¥Close Button Outside

以下示例展示了如何自定义 Dialog.CloseTrigger 组件，将关闭按钮置于对话框组件之外。

¥Here's an example of how to customize the Dialog.CloseTrigger component to position the close button outside the dialog component.

非模态对话框

¥Non-Modal Dialog

由于非模态对话框存在可访问性问题，我们不建议使用它们。如果你需要，可以执行以下操作：

¥We don't recommend using a non-modal dialog due to the accessibility concerns they present. In event you need it, here's what you can do:

  • 将 modal prop 设置为 false

  • 在 Dialog.Positioner 组件上将 pointerEvents 设置为 none

  • （可选）将 closeOnInteractOutside 属性设置为 false

DataList

以下示例展示了如何使用 DataList 组件组合对话框组件。

¥Here's an example of how to compose the dialog component with the DataList component.

属性

¥Props

根元素

¥Root

PropDefaultType
closeOnEscape true
boolean

Whether to close the dialog when the escape key is pressed

closeOnInteractOutside true
boolean

Whether to close the dialog when the outside is clicked

defaultOpen false
boolean

The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog.

lazyMount false
boolean

Whether to enable lazy mounting

modal true
boolean

Whether to prevent pointer interaction outside the element and hide all content below it

preventScroll true
boolean

Whether to prevent scrolling behind the dialog when it's opened

role '\'dialog\''
'dialog' | 'alertdialog'

The dialog's role

skipAnimationOnMount false
boolean

Whether to allow the initial presence animation.

trapFocus true
boolean

Whether to trap focus inside the dialog when it's opened

unmountOnExit false
boolean

Whether to unmount on exit.

colorPalette 'gray'
'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'cyan' | 'purple' | 'pink'

The color palette of the component

placement 'top'
'center' | 'top' | 'bottom'

The placement of the component

scrollBehavior 'outside'
'inside' | 'outside'

The scrollBehavior of the component

size 'md'
'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'cover' | 'full'

The size of the component

motionPreset 'scale'
'scale' | 'slide-in-bottom' | 'slide-in-top' | 'slide-in-left' | 'slide-in-right' | 'none'

The motionPreset of the component

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
unstyled
boolean

Whether to remove the component's style.

aria-label
string

Human readable label for the dialog, in event the dialog title is not rendered

finalFocusEl
() => MaybeElement

Element to receive focus when the dialog is closed

id
string

The unique identifier of the machine.

ids
Partial<{ trigger: string positioner: string backdrop: string content: string closeTrigger: string title: string description: string }>

The ids of the elements in the dialog. Useful for composition.

immediate
boolean

Whether to synchronize the present change immediately or defer it to the next frame

initialFocusEl
() => MaybeElement

Element to receive focus when the dialog is opened

onEscapeKeyDown
(event: KeyboardEvent) => void

Function called when the escape key is pressed

onExitComplete
VoidFunction

Function called when the animation ends in the closed state

onFocusOutside
(event: FocusOutsideEvent) => void

Function called when the focus is moved outside the component

onInteractOutside
(event: InteractOutsideEvent) => void

Function called when an interaction happens outside the component

onOpenChange
(details: OpenChangeDetails) => void

Function to call when the dialog's open state changes

onPointerDownOutside
(event: PointerDownOutsideEvent) => void

Function called when the pointer is pressed down outside the component

open
boolean

The controlled open state of the dialog

persistentElements
(() => Element | null)[]

Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event

present
boolean

Whether the node is present (controlled by the user)

restoreFocus
boolean

Whether to restore focus to the element that had focus before the dialog was opened

Previous

操作栏

Next

抽屉