Radix Vue

外观

对话框 ​

一个覆盖在主窗口或另一个对话框窗口上的窗口，使下面的内容处于非活动状态。
vue
<script setup lang="ts">
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogOverlay,
  DialogPortal,
  DialogRoot,
  DialogTitle,
  DialogTrigger,
} from 'radix-vue'
import { Icon } from '@iconify/vue'
</script>

<template>
  <DialogRoot>
    <DialogTrigger
      class="text-grass11 font-semibold shadow-blackA7 hover:bg-mauve3 inline-flex h-[35px] items-center justify-center rounded-[4px] bg-white px-[15px] leading-none shadow-[0_2px_10px] focus:shadow-[0_0_0_2px] focus:shadow-black focus:outline-none"
    >
      Edit profile
    </DialogTrigger>
    <DialogPortal>
      <DialogOverlay class="bg-blackA9 data-[state=open]:animate-overlayShow fixed inset-0 z-30" />
      <DialogContent
        class="data-[state=open]:animate-contentShow fixed top-[50%] left-[50%] max-h-[85vh] w-[90vw] max-w-[450px] translate-x-[-50%] translate-y-[-50%] rounded-[6px] bg-white p-[25px] shadow-[hsl(206_22%_7%_/_35%)_0px_10px_38px_-10px,_hsl(206_22%_7%_/_20%)_0px_10px_20px_-15px] focus:outline-none z-[100]"
      >
        <DialogTitle class="text-mauve12 m-0 text-[17px] font-semibold">
          Edit profile
        </DialogTitle>
        <DialogDescription class="text-mauve11 mt-[10px] mb-5 text-[15px] leading-normal">
          Make changes to your profile here. Click save when you're done.
        </DialogDescription>
        <fieldset class="mb-[15px] flex items-center gap-5">
          <label
            class="text-grass11 w-[90px] text-right text-[15px]"
            for="name"
          > Name </label>
          <input
            id="name"
            class="text-grass11 shadow-green7 focus:shadow-green8 inline-flex h-[35px] w-full flex-1 items-center justify-center rounded-[4px] px-[10px] text-[15px] leading-none shadow-[0_0_0_1px] outline-none focus:shadow-[0_0_0_2px]"
            defaultValue="Pedro Duarte"
          >
        </fieldset>
        <fieldset class="mb-[15px] flex items-center gap-5">
          <label
            class="text-grass11 w-[90px] text-right text-[15px]"
            for="username"
          > Username </label>
          <input
            id="username"
            class="text-grass11 shadow-green7 focus:shadow-green8 inline-flex h-[35px] w-full flex-1 items-center justify-center rounded-[4px] px-[10px] text-[15px] leading-none shadow-[0_0_0_1px] outline-none focus:shadow-[0_0_0_2px]"
            defaultValue="@peduarte"
          >
        </fieldset>
        <div class="mt-[25px] flex justify-end">
          <DialogClose as-child>
            <button
              class="bg-green4 text-green11 hover:bg-green5 focus:shadow-green7 inline-flex h-[35px] items-center justify-center rounded-[4px] px-[15px] font-semibold leading-none focus:shadow-[0_0_0_2px] focus:outline-none"
            >
              Save changes
            </button>
          </DialogClose>
        </div>
        <DialogClose
          class="text-grass11 hover:bg-green4 focus:shadow-green7 absolute top-[10px] right-[10px] inline-flex h-[25px] w-[25px] appearance-none items-center justify-center rounded-full focus:shadow-[0_0_0_2px] focus:outline-none"
          aria-label="Close"
        >
          <Icon icon="lucide:x" />
        </DialogClose>
      </DialogContent>
    </DialogPortal>
  </DialogRoot>
</template>

功能 ​

  • 支持模态和非模态模式。
  • 模态时自动捕获焦点。
  • 可以控制或不受控制。
  • 使用 Title 和 Description 组件管理屏幕阅读器公告。
  • Esc 自动关闭组件。

安装 ​

从命令行安装组件。

sh
$ npm add radix-vue

结构 ​

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

vue
<script setup>
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogOverlay,
  DialogPortal,
  DialogRoot,
  DialogTitle,
  DialogTrigger,
} from 'radix-vue'
</script>

<template>
  <DialogRoot>
    <DialogTrigger />
    <DialogPortal>
      <DialogOverlay />
      <DialogContent>
        <DialogTitle />
        <DialogDescription />
        <DialogClose />
      </DialogContent>
    </DialogPortal>
  </DialogRoot>
</template>

API 参考 ​

根 ​

包含对话框的所有部分

属性默认值类型
defaultOpen
false
boolean

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

modal
true
boolean

对话框的模态性。当设置为 true 时，
对外部元素的交互将被禁用，只有对话框内容对屏幕阅读器可见。

open
boolean

对话框的受控打开状态。可以绑定为 v-model:open。

发射有效载荷
update:open
[value: boolean]

当对话框的打开状态更改时调用的事件处理程序。

插槽 (默认)有效载荷
open
boolean

当前打开状态

触发器 ​

打开对话框的按钮

属性默认值类型
as
'button'
AsTag | 组件

此组件应渲染的元素或组件。可以被 asChild 覆盖

asChild
boolean

更改传递为子元素的默认渲染元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

数据属性值
[data-state]"open" | "closed"

传送门 ​

使用时，会将覆盖层和内容部分传送至 body。

属性默认值类型
disabled
boolean

禁用传送并将组件内联渲染

reference

forceMount
boolean

用于在需要更多控制时强制挂载。当使用 Vue 动画库控制动画时很有用。

to
string | HTMLElement

Vue 原生传送组件属性 :to

reference

覆盖层 ​

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

属性默认值类型
as
'div'
AsTag | 组件

此组件应渲染的元素或组件。可以被 asChild 覆盖

asChild
boolean

更改传递为子元素的默认渲染元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

forceMount
boolean

用于在需要更多控制时强制挂载。当使用 Vue 动画库控制动画时很有用。

数据属性值
[data-state]"open" | "closed"

内容 ​

包含要在打开的对话框中渲染的内容

属性默认值类型
as
'div'
AsTag | 组件

此组件应渲染的元素或组件。可以被 asChild 覆盖

asChild
boolean

更改传递为子元素的默认渲染元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

disableOutsidePointerEvents
boolean

当 true 时，DismissableLayer 外部的元素上的悬停/焦点/单击交互将被禁用。用户需要双击外部元素才能与它们交互：一次关闭 DismissableLayer，另一次触发元素。

forceMount
boolean

用于在需要更多控制时强制挂载。当使用 Vue 动画库控制动画时很有用。

trapFocus
boolean

当 true 时，焦点不能通过键盘、指针或编程方式焦点离开 Content。

发射有效载荷
closeAutoFocus
[event: Event]

在关闭时自动聚焦时调用的事件处理程序。可以被阻止。

escapeKeyDown
[event: KeyboardEvent]

按下 Escape 键时调用的事件处理程序。可以被阻止。

focusOutside
[event: FocusOutsideEvent]

焦点移动到 DismissableLayer 外部时调用的事件处理程序。可以被阻止。

interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]

当在 DismissableLayer 外部发生交互时调用的事件处理程序。具体来说，当在外部发生 pointerdown 事件或焦点移动到其外部时。可以被阻止。

openAutoFocus
[event: Event]

在打开时自动聚焦时调用的事件处理程序。可以被阻止。

pointerDownOutside
[event: PointerDownOutsideEvent]

当在 DismissableLayer 外部发生 pointerdown 事件时调用的事件处理程序。可以被阻止。

数据属性值
[data-state]"open" | "closed"

关闭 ​

关闭对话框的按钮

属性默认值类型
as
'button'
AsTag | 组件

此组件应渲染的元素或组件。可以被 asChild 覆盖

asChild
boolean

更改传递为子元素的默认渲染元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

标题 ​

一个可访问的标题，在打开对话框时宣布。

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

属性默认值类型
as
'h2'
AsTag | 组件

此组件应渲染的元素或组件。可以被 asChild 覆盖

asChild
boolean

更改传递为子元素的默认渲染元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

描述 ​

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

如果要隐藏描述，请将其包装在我们的视觉隐藏实用程序中，例如 <VisuallyHidden asChild>。如果要完全删除描述，请删除此部分并将 :aria-describedby="undefined" 传递给 DialogContent。

属性默认值类型
as
'p'
AsTag | 组件

此组件应渲染的元素或组件。可以被 asChild 覆盖

asChild
boolean

更改传递为子元素的默认渲染元素，合并它们的属性和行为。

阅读我们的 组合 指南以了解更多详细信息。

示例 ​

嵌套对话框 ​

您可以嵌套多层对话框。

vue
<script setup lang="ts">
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogOverlay,
  DialogPortal,
  DialogRoot,
  DialogTitle,
  DialogTrigger,
} from 'radix-vue'
import { Icon } from '@iconify/vue'
</script>

<template>
  <div>
    <DialogRoot>
      <DialogTrigger
        class="text-grass11 font-semibold shadow-blackA7 hover:bg-mauve3 inline-flex h-[35px] items-center justify-center rounded-[4px] bg-white px-[15px] leading-none shadow-[0_2px_10px] focus:shadow-[0_0_0_2px] focus:shadow-black focus:outline-none"
      >
        Open Dialog
      </DialogTrigger>
      <DialogPortal>
        <DialogOverlay class="bg-blackA9 data-[state=open]:animate-overlayShow fixed inset-0 z-30" />
        <DialogContent
          class="data-[state=open]:animate-contentShow fixed top-[50%] left-[50%] max-h-[85vh] w-[90vw] max-w-[450px] translate-x-[-50%] translate-y-[-50%] rounded-[6px] bg-white p-[25px] shadow-[hsl(206_22%_7%_/_35%)_0px_10px_38px_-10px,_hsl(206_22%_7%_/_20%)_0px_10px_20px_-15px] focus:outline-none z-[100]"
        >
          <DialogTitle class="text-mauve12 m-0 text-[17px] font-semibold">
            First Dialog
          </DialogTitle>
          <DialogDescription class="text-mauve11 mt-[10px] mb-5 text-[15px] leading-normal">
            First dialog.
          </DialogDescription>

          <div class="mt-[25px] flex gap-4 justify-end">
            <DialogClose as-child>
              <button
                class="bg-green4 text-green11 hover:bg-green5 focus:shadow-green7 inline-flex h-[35px] items-center justify-center rounded-[4px] px-[15px] font-semibold leading-none focus:shadow-[0_0_0_2px] focus:outline-none"
              >
                Close
              </button>
            </DialogClose>

            <DialogRoot>
              <DialogTrigger
                class="bg-green9 font-semibold shadow-blackA7 hover:bg-green10  inline-flex h-[35px] items-center justify-center rounded-[4px] text-white px-[15px] leading-none shadow-[0_2px_10px] focus:shadow-[0_0_0_2px] focus:shadow-black focus:outline-none"
              >
                Open second
              </DialogTrigger>

              <DialogPortal>
                <DialogOverlay class="bg-blackA9 data-[state=open]:animate-overlayShow fixed inset-0 z-30" />
                <DialogContent
                  class="data-[state=open]:animate-contentShow fixed top-[50%] left-[50%] max-h-[85vh] w-[90vw] max-w-[450px] translate-x-[-50%] translate-y-[-50%] rounded-[6px] bg-white p-[25px] shadow-[hsl(206_22%_7%_/_35%)_0px_10px_38px_-10px,_hsl(206_22%_7%_/_20%)_0px_10px_20px_-15px] focus:outline-none z-[100]"
                >
                  <DialogTitle class="text-mauve12 m-0 text-[17px] font-semibold">
                    Second Dialog
                  </DialogTitle>
                  <DialogDescription class="text-mauve11 mt-[10px] mb-5 text-[15px] leading-normal">
                    Second dialog.
                  </DialogDescription>

                  <div class="flex justify-end">
                    <DialogClose as-child>
                      <button
                        class="bg-green4 text-green11 hover:bg-green5 focus:shadow-green7 inline-flex h-[35px] items-center justify-center rounded-[4px] px-[15px] font-semibold leading-none focus:shadow-[0_0_0_2px] focus:outline-none"
                      >
                        Close
                      </button>
                    </DialogClose>
                  </div>
                </DialogContent>
              </DialogPortal>
            </DialogRoot>
          </div>
          <DialogClose
            class="text-grass11 hover:bg-green4 focus:shadow-green7 absolute top-[10px] right-[10px] inline-flex h-[25px] w-[25px] appearance-none items-center justify-center rounded-full focus:shadow-[0_0_0_2px] focus:outline-none"
            aria-label="Close"
          >
            <Icon icon="lucide:x" />
          </DialogClose>
        </DialogContent>
      </DialogPortal>
    </DialogRoot>
  </div>
</template>

异步表单提交后关闭 ​

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

vue
<script setup>
import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTrigger } from 'radix-vue'

const wait = () => new Promise(resolve => setTimeout(resolve, 1000))
const open = ref(false)
</script>

<template>
  <DialogRoot v-model:open="open">
    <DialogTrigger>Open</DialogTrigger>
    <DialogPortal>
      <DialogOverlay />
      <DialogContent>
        <form
          @submit.prevent="
            (event) => {
              wait().then(() => (open = false));
            }
          "
        >
          <!-- some inputs -->
          <button type="submit">
            Submit
          </button>
        </form>
      </DialogContent>
    </DialogPortal>
  </DialogRoot>
</template>

可滚动覆盖层 ​

将内容移动到覆盖层内以渲染具有溢出的对话框。

vue
// index.vue
<script setup>
import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTrigger } from 'radix-vue'
import './styles.css'
</script>

<template>
  <DialogRoot>
    <DialogTrigger />
    <DialogPortal>
      <DialogOverlay class="DialogOverlay">
        <DialogContent class="DialogContent">
          ...
        </DialogContent>
      </DialogOverlay>
    </DialogPortal>
  </DialogRoot>
</template>
css
/* 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;
}

但是，这种方法有一个弊端，即用户可能会点击滚动条并无意中关闭对话框。目前还没有通用的解决方案可以解决这个问题，但是您可以在 DialogContent 中添加以下代码段来阻止在点击滚动条时关闭模态。

vue
<DialogContent
  @pointer-down-outside="(event) => {
    const originalEvent = event.detail.originalEvent;
    const target = originalEvent.target as HTMLElement;
    if (originalEvent.offsetX > target.clientWidth || originalEvent.offsetY > target.clientHeight) {
      event.preventDefault();
    }
  }"
>

自定义传送门容器 ​

自定义对话框传送到的元素。

vue
<script setup>
import { DialogContent, DialogOverlay, DialogPortal, DialogRoot, DialogTrigger } from 'radix-vue'

const container = ref(null)
</script>

<template>
  <div>
    <DialogRoot>
      <DialogTrigger />
      <DialogPortal to="container">
        <DialogOverlay />
        <DialogContent>...</DialogContent>
      </DialogPortal>
    </DialogRoot>

    <div ref="container" />
  </div>
</template>

在外部交互时禁用关闭 ​

例如，如果您有一些全局 Toast 提示组件，在点击它时不应关闭对话框。

vue
<script setup lang="ts">
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogOverlay,
  DialogPortal,
  DialogRoot,
  DialogTitle,
  DialogTrigger,
} from 'radix-vue'
import { Icon } from '@iconify/vue'

import { Toaster, toast } from 'vue-sonner'
</script>

<template>
  <div>
    <DialogRoot>
      <DialogTrigger
        class="text-grass11 font-semibold shadow-blackA7 hover:bg-mauve3 inline-flex h-[35px] items-center justify-center rounded-[4px] bg-white px-[15px] leading-none shadow-[0_2px_10px] focus:shadow-[0_0_0_2px] focus:shadow-black focus:outline-none"
      >
        Open Dialog
      </DialogTrigger>
      <DialogPortal>
        <DialogOverlay class="bg-blackA9 data-[state=open]:animate-overlayShow fixed inset-0 z-30" />
        <DialogContent
          class="data-[state=open]:animate-contentShow fixed top-[50%] left-[50%] max-h-[85vh] w-[90vw] max-w-[450px] translate-x-[-50%] translate-y-[-50%] rounded-[6px] bg-white p-[25px] shadow-[hsl(206_22%_7%_/_35%)_0px_10px_38px_-10px,_hsl(206_22%_7%_/_20%)_0px_10px_20px_-15px] focus:outline-none z-[100]"
          @interact-outside="event => {
            const target = event.target as HTMLElement;
            if (target?.closest('[data-sonner-toaster]')) return event.preventDefault()
          }"
        >
          <DialogTitle class="text-mauve12 m-0 text-[17px] font-semibold">
            Dialog Title
          </DialogTitle>
          <DialogDescription class="text-mauve11 mt-[10px] mb-5 text-[15px] leading-normal">
            Dialog description
          </DialogDescription>

          <button
            class="bg-green4 text-green11 hover:bg-green5 focus:shadow-green7 inline-flex h-[35px] items-center justify-center rounded-[4px] px-[15px] font-semibold leading-none focus:shadow-[0_0_0_2px] focus:outline-none"
            @click="() => toast('Event has been created', {
              action: {
                label: 'Undo',
                onClick: () => console.log('Undo'),
              },
            })"
          >
            Give me a toast
          </button>

          <DialogClose
            class="text-grass11 hover:bg-green4 focus:shadow-green7 absolute top-[10px] right-[10px] inline-flex h-[25px] w-[25px] appearance-none items-center justify-center rounded-full focus:shadow-[0_0_0_2px] focus:outline-none"
            aria-label="Close"
          >
            <Icon icon="lucide:x" />
          </DialogClose>
        </DialogContent>
      </DialogPortal>
    </DialogRoot>

    <ClientOnly>
      <Teleport to="html">
        <Toaster />
      </Teleport>
    </ClientOnly>
  </div>
</template>

无障碍性 ​

符合 对话框 WAI-ARIA 设计模式。

关闭图标按钮 ​

在提供图标（或字体图标）时，请记住为屏幕阅读器用户正确标记它。

html
<DialogRoot>
  <DialogTrigger />
  <DialogPortal>
    <DialogOverlay />
    <DialogContent>
      <DialogTitle />
      <DialogDescription />
      <DialogClose aria-label="Close">
        <span aria-hidden>×</span>
      </DialogClose>
    </DialogContent>
  </DialogPortal>
</DialogRoot>

键盘交互 ​

键描述
空格
打开/关闭对话框
Enter
打开/关闭对话框
Tab
将焦点移动到下一个可聚焦元素。
Shift + Tab
将焦点移动到上一个可聚焦元素。
Esc
关闭对话框并将焦点移动到 DialogTrigger。

自定义 API ​

通过将基本部分抽象到您自己的组件中来创建您自己的 API。

抽象覆盖层和关闭按钮 ​

此示例抽象了 DialogOverlay 和 DialogClose 部分。

用法 ​

vue
<script setup>
import { Dialog, DialogContent, DialogTrigger } from './your-dialog'
</script>

<template>
  <Dialog>
    <DialogTrigger>Dialog trigger</DialogTrigger>
    <DialogContent>Dialog Content</DialogContent>
  </Dialog>
</template>

实现 ​

ts
// your-dialog.ts
export { default as DialogContent } from 'DialogContent.vue'
export { DialogRoot as Dialog, DialogTrigger } from 'radix-vue'
vue
<!-- DialogContent.vue -->
<script setup lang="ts">
import { DialogClose, DialogContent, type DialogContentEmits, type DialogContentProps, DialogOverlay, DialogPortal, useEmitAsProps, } from 'radix-vue'
import { Cross2Icon } from '@radix-icons/vue'

const props = defineProps<DialogContentProps>()
const emits = defineEmits<DialogContentEmits>()

const emitsAsProps = useEmitAsProps(emits)
</script>

<template>
  <DialogPortal>
    <DialogOverlay />
    <DialogContent v-bind="{ ...props, ...emitsAsProps }">
      <slot />

      <DialogClose>
        <Cross2Icon />
        <span class="sr-only">Close</span>
      </DialogClose>
    </DialogContent>
  </DialogPortal>
</template>