使用高级 Chakra UI 组件更快地构建 💎

了解更多
跳到内容
文档演练场指南博客
赞助商

对话框

用于显示对话框提示

Storybook配方Ark

用法

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>

示例

尺寸

使用 size 属性来改变对话框组件的尺寸。

覆盖

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

全屏

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

位置

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

受控

使用 openonOpenChange 属性来控制对话框组件的可见性。

存储

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

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

上下文

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

初始焦点

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

内部滚动

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

外部滚动

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

运动预设

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

警报对话框

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

外部关闭按钮

这里是一个如何自定义 Dialog.CloseTrigger 组件以将关闭按钮放置在对话框组件外部的示例。

非模态对话框

由于可访问性问题,我们不建议使用非模态对话框。如果您确实需要,可以这样做:

  • modal 属性设置为 false
  • pointerEventsDialog.Positioner 组件上设置为 none
  • (可选)将 closeOnInteractOutside 属性设置为 false

DataList

这里是如何将对话框组件与 DataList 组件组合使用的示例。

属性

属性默认值类型
closeOnEscape true
boolean

按下 Esc 键时是否关闭对话框

closeOnInteractOutside true
boolean

点击外部时是否关闭对话框

lazyMount false
boolean

是否启用懒挂载

modal true
boolean

是否阻止元素外部的指针交互并隐藏其下方所有内容

preventScroll true
boolean

对话框打开时是否阻止其背景滚动

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

对话框的角色

trapFocus true
boolean

对话框打开时是否将焦点限制在对话框内部

unmountOnExit false
boolean

退出时是否卸载。

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

组件的颜色调色板

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

组件的位置

scrollBehavior 'outside'
'inside' | 'outside'

组件的滚动行为

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

组件的尺寸

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

组件的运动预设

aria-label
string

对话框的可读标签,以防对话框标题未渲染

defaultOpen
boolean

对话框首次渲染时的初始打开状态。在您不需要控制其打开状态时使用。

finalFocusEl
() => HTMLElement | null

对话框关闭时接收焦点的元素

id
string

机器的唯一标识符。

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

对话框中元素的 ID。对于组合很有用。

immediate
boolean

是否立即同步当前更改或将其推迟到下一帧

initialFocusEl
() => HTMLElement | null

对话框打开时接收焦点的元素

onEscapeKeyDown
(event: KeyboardEvent) => void

按下 Esc 键时调用的函数

onExitComplete
() => void

动画在关闭状态下结束时调用的函数

onFocusOutside
(event: FocusOutsideEvent) => void

焦点移出组件时调用的函数

onInteractOutside
(event: InteractOutsideEvent) => void

组件外部发生交互时调用的函数

onOpenChange
(details: OpenChangeDetails) => void

对话框打开或关闭时调用的回调函数

onPointerDownOutside
(event: PointerDownOutsideEvent) => void

指针在组件外部按下时调用的函数

open
boolean

对话框是否打开

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

返回持久元素,这些元素: - 不应禁用指针事件 - 不应触发关闭事件

present
boolean

节点是否显示(由用户控制)

restoreFocus
boolean

对话框打开前是否将焦点恢复到之前获得焦点的元素

as
React.ElementType

要渲染的基础元素。

asChild
boolean

使用提供的子元素作为默认渲染元素,结合其属性和行为。

更多详情,请阅读我们的 组合 指南。
unstyled
boolean

是否移除组件的样式。

上一页

Data List

下一页

Drawer