Dialog

模态框系统,提供声明式 <Dialog> 组件与命令式 dialog.show() 两种用法。命令式用法需要在应用根部挂载 <DialogOpener>(Nuxt 项目自动处理)。

Anatomy

• Dialog模态根,提供 open/modal 等状态
  • DialogContent用户自定义的内容层
  • DialogClose嵌套的关闭触发器(可用 as-child 包裹任意组件)
• DialogOpener挂载后支持 dialog.show()/update()/close() 命令式 API
• Confirm基于 Dialog 的二次确认封装,通常与 dialog.show() 搭配使用

声明式用法

受控 + 非受控皆可,适合需要模板里完整表达结构的场景。

声明式打开

<script setup lang="ts">
import { Button, Dialog } from '@tripo3d/design';
import { ref } from 'vue';

const open = ref(false);
</script>

<template>
  <Button @click="open = true">打开</Button>
  <Dialog v-model:open="open">
    <div class="...">
      <Button @click="open = false">关闭</Button>
    </div>
  </Dialog>
</template>

DialogClose 仅用于命令式弹窗

<DialogClose> 内部调用的是 dialog.close(openerKey),需要配合 dialog.show() 返回的 key 才会生效。声明式 v-model:open 场景请直接把绑定值置为 false,或通过 @click / 按 Esc / 点击遮罩关闭(modal 为 true 时自动支持)。

命令式用法

适合异步流程、跨组件触发、需要动态传参的场景。

dialog.show

命令式打开,返回 key 可用于 update/close。

<script setup lang="ts">
import { Button, dialog } from '@tripo3d/design';
import MyDialog from './my-dialog.vue';

function open() {
  const key = dialog.show(MyDialog, { title: 'hello' });
  // 后续可 dialog.update(key, { title: 'updated' })
  // 也可 dialog.close(key)
}
</script>

<template>
  <Button @click="open">命令式打开</Button>
</template>

挂载 DialogOpener

命令式 API 依赖单例挂载点 <DialogOpener />:

• Nuxt 项目:通过 @tripo3d/design/nuxt 模块自动注入
• Vue 3 项目:需在 App.vue 或根布局中手动挂载一次

<!-- App.vue -->
<template>
  <RouterView />
  <DialogOpener />
</template>

在 Dialog 内部关闭

命令式打开的组件可通过 useDialog() 拿到 close 方法:

<script setup lang="ts">
import { useDialog } from '@tripo3d/design';

const { close } = useDialog();
</script>

<template>
  <Button @click="close">关闭自己</Button>
</template>

Confirm

语义化的二次确认框,通常与 dialog.show() 搭配。

<script setup lang="ts">
import { Confirm, dialog } from '@tripo3d/design';

function onDelete() {
  dialog.show(Confirm, {
    title: '确认删除?',
    description: '此操作不可撤销',
    onConfirm: ({ close }) => {
      // ...执行删除
      close();
    },
  });
}
</script>

API

Dialog Props

名称	类型	默认值	说明
open	boolean	—	受控开关状态
defaultOpen	boolean	—	非受控初始状态
modal	boolean	true	是否锁定背景滚动并拦截交互

Dialog Events

事件	Payload	说明
update:open	(open: boolean)	受控模式下开关变化事件

Confirm Props

名称	类型	默认值	说明
title	string	—	标题文本
description	string	—	描述文本
cancelText	string	'取消'	取消按钮文本
confirmText	string	'确认'	确认按钮文本
onCancel	(ctx: { close(): void }) => void	—	取消回调
onConfirm	(ctx: { close(): void }) => void	—	确认回调,通常在业务完成后调用 close
class	string	—	容器 class

Confirm Slots

插槽	作用域	说明
title	—	覆写标题渲染
description	—	覆写描述渲染
cancel	—	覆写取消按钮
confirm	—	覆写确认按钮

dialog 命令式 API

方法	签名	说明
dialog.show	(component, props?) => key	挂载并打开一个弹窗,返回可用于 update/close 的 key
dialog.update	(key, props) => void	更新已打开弹窗的 props
dialog.close	(key) => void	关闭弹窗(带 150ms 退场动画)

useDialog()

字段	类型	说明
close	() => void	在命令式打开的组件内部关闭自身

可访问性

• 基于 Reka UI 的 DialogRoot,自动管理焦点陷阱与键盘导航
• modal 为真(默认)时,Esc 关闭、背景区域点击关闭、Tab 循环仅在弹窗内
• 打开后自动把焦点移动到首个可聚焦元素,关闭后归还触发器焦点