Dialog 对话框

在当前页面上方显示需要用户处理的内容。

滚动锁与宽度补偿

打开对话框时，蒙版会覆盖整个视口并锁定背景页面滚动；关闭后恢复打开前的滚动状态。滚动锁与普通页面内容的宽度补偿由 Reka UI 负责；固定定位区域可使用其提供的 --scrollbar-width 保持宽度稳定。

命令行安装

npx @loongship-kit/ui add dialog button input

组件结构

角色	组件	职责	使用条件
根组件	Dialog	管理显示状态、焦点和模态行为	必需
触发与关闭	DialogTrigger、DialogClose	打开或关闭对话框	按需
浮层结构	DialogPortal、DialogOverlay	传送内容并渲染背景遮罩	常规模态用法需要
内容容器	DialogContent	承载对话框主体和关闭按钮	必需
语义内容	DialogTitle、DialogDescription	提供可访问标题和描述	标题必需，描述按需

基础用法

查看代码

<script setup lang="ts">
import { Button } from '@/components/loongship/button'
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogOverlay,
  DialogPortal,
  DialogTitle,
  DialogTrigger
} from '@/components/loongship/dialog'
</script>

<template>
  <Dialog>
    <DialogTrigger as-child>
      <Button variant="outline">查看船舶信息</Button>
    </DialogTrigger>
    <DialogPortal>
      <DialogOverlay />
      <DialogContent>
        <DialogTitle>EVER GIVEN</DialogTitle>
        <DialogDescription>IMO 9811000 · 当前状态：航行中</DialogDescription>
        <DialogClose as-child>
          <Button variant="outline">关闭</Button>
        </DialogClose>
      </DialogContent>
    </DialogPortal>
  </Dialog>
</template>

内置关闭按钮

DialogContent 默认显示右上角关闭按钮，无需手动添加。

编辑表单

查看代码

<template>
  <Dialog>
    <DialogTrigger as-child><Button>编辑船舶</Button></DialogTrigger>
    <DialogPortal>
      <DialogOverlay />
      <DialogContent>
        <DialogTitle>编辑船舶</DialogTitle>
        <DialogDescription>更新船名和呼号，完成后保存。</DialogDescription>
        <div class="dialog-demo-form">
          <label><span>船名</span><Input v-model="vesselName" /></label>
          <label><span>呼号</span><Input v-model="callSign" /></label>
        </div>
        <div class="dialog-demo-actions">
          <DialogClose as-child><Button variant="outline">取消</Button></DialogClose>
          <DialogClose as-child><Button>保存</Button></DialogClose>
        </div>
      </DialogContent>
    </DialogPortal>
  </Dialog>
</template>

受控状态

使用 v-model:open 从业务代码控制显示状态。

Open: false

查看代码

<template>
  <div class="vp-demo-showcase-column">
    <Button variant="outline" @click="open = true">打开对话框</Button>
    <span>Open: {{ open }}</span>
    <Dialog v-model:open="open">
      <DialogPortal>
        <DialogOverlay />
        <DialogContent>
          <DialogTitle>编辑航次</DialogTitle>
          <DialogDescription>保存或关闭后返回当前页面。</DialogDescription>
          <div class="dialog-demo-actions">
            <DialogClose as-child><Button>完成</Button></DialogClose>
          </div>
        </DialogContent>
      </DialogPortal>
    </Dialog>
  </div>
</template>

自定义关闭方式

自定义关闭入口

不需要右上角关闭按钮时，设置 show-close-button="false"，并在内容中放置自己的 DialogClose。

查看代码

<template>
  <Dialog>
    <DialogTrigger as-child><Button variant="outline">查看航次提醒</Button></DialogTrigger>
    <DialogPortal>
      <DialogOverlay />
      <DialogContent :show-close-button="false">
        <DialogTitle>航次提醒</DialogTitle>
        <DialogDescription>该船预计在 24 小时内抵达目的港。</DialogDescription>
        <div class="dialog-demo-actions">
          <DialogClose as-child><Button>知道了</Button></DialogClose>
        </div>
      </DialogContent>
    </DialogPortal>
  </Dialog>
</template>

API

Dialog（主组件）

属性

属性	类型	默认值	说明
v-model:open	boolean	-	受控显示状态
defaultOpen	boolean	false	非受控模式的初始状态
modal	boolean	true	是否阻止与弹窗外内容交互
unmountOnHide	boolean	true	关闭时是否卸载内容

事件

事件	参数	说明
update:open	value: boolean	显示状态改变时触发

插槽

插槽	参数	说明
default	{ open: boolean, close: () => void }	弹窗结构

子组件

DialogTrigger / DialogClose — 打开与关闭入口

属性

属性	类型	默认值	说明
as	string | Component	'button'	渲染元素
asChild	boolean	false	合并到唯一子元素，适合配合 Button

插槽

组件	插槽	参数	说明
DialogTrigger	default	—	打开按钮内容
DialogClose	default	—	关闭按钮内容

DialogPortal — 浮层传送容器

属性

属性	类型	默认值	说明
to	string | HTMLElement	'body'	Teleport 目标
disabled	boolean	false	是否禁用 Teleport
defer	boolean	false	是否延迟解析目标

插槽

插槽	参数	说明
default	—	通常依次放置 DialogOverlay 和 DialogContent

DialogOverlay — 模态背景遮罩

属性

属性	类型	默认值	说明
forceMount	boolean	false	关闭时仍挂载，便于自定义动画
as	string | Component	'div'	渲染元素
asChild	boolean	false	合并到唯一子元素
class	ClassValue	-	自定义类名

插槽

插槽	参数	说明
default	—	自定义遮罩层内容

DialogContent — 对话框内容容器

属性

属性	类型	默认值	说明
forceMount	boolean	false	关闭时仍挂载，便于自定义动画
disableOutsidePointerEvents	boolean	true（modal）	是否禁用弹窗外指针交互
as	string | Component	'div'	渲染元素
asChild	boolean	false	合并到唯一子元素
class	ClassValue	-	自定义类名
showCloseButton	boolean	true	是否显示右上角关闭按钮

事件

事件	参数	说明
escapeKeyDown	KeyboardEvent	按下 Escape 时触发
pointerDownOutside	PointerDownOutsideEvent	在内容外按下指针时触发
focusOutside	FocusOutsideEvent	焦点移到内容外时触发
interactOutside	PointerDownOutsideEvent | FocusOutsideEvent	在内容外发生交互时触发
openAutoFocus	Event	打开后自动聚焦前触发
closeAutoFocus	Event	关闭后恢复焦点前触发

阻止默认行为

以上事件均可通过 preventDefault() 阻止对应默认行为。

插槽

插槽	参数	说明
default	—	弹窗主体内容

DialogTitle / DialogDescription — 可访问标题与描述

属性

组件	默认元素	作用
DialogTitle	h2	提供弹窗的无障碍标题
DialogDescription	p	提供弹窗的无障碍描述

插槽

组件	插槽	参数	说明
DialogTitle	default	—	标题内容
DialogDescription	default	—	描述内容

无障碍要求

每个 DialogContent 应提供标题；没有可见描述时，应按 Reka UI 的无障碍要求提供隐藏描述或显式移除描述关联。