Skip to content

@neosjs/dialog ​

对话框组件。基于 Teleport 与 Overlay 实现,内置焦点圈定(FocusTrap),支持拖拽、调整大小、全屏切换、延迟打开/关闭等能力,是 Modal 之外更完整的对话交互容器。

安装 ​

sh
pnpm add @neosjs/dialog
sh
npm i @neosjs/dialog
sh
yarn add @neosjs/dialog

快速上手 ​

通过 v-model 控制显示,title 设置标题,默认插槽填充内容。

vue
<script setup lang="ts">
import { Dialog } from '@neosjs/dialog'
import { ref } from 'vue'

const visible = ref(false)
</script>

<template>
  <button @click="visible = true">
    打开对话框
  </button>

  <Dialog v-model="visible" title="提示" width="420px">
    <p>对话框内容</p>
    <template #footer>
      <button @click="visible = false">
        取消
      </button>
    </template>
  </Dialog>
</template>

拖拽 / 缩放 / 全屏 ​

  • draggable 开启后可拖住头部移动对话框;overflow 允许拖出视口外。
  • resizeable(默认开启)后,拖动右下角红色角标可调整大小,范围被限制在 100px ~ 1000px。
  • fullscreenable 开启后头部出现全屏切换按钮,切换时触发 changeScreenState 事件;也可用 fullscreen 直接指定全屏状态。

关闭前拦截 ​

beforeClose 会在关闭流程前被调用,传入 done 函数,只有调用 done() 才会真正关闭。

vue
<Dialog v-model="visible" :before-close="handleBeforeClose" title="确认关闭?">
  <p>内容</p>
</Dialog>
ts
function handleBeforeClose(done: (cancel?: boolean) => void) {
  // 做一些校验或确认,完成后调用 done 关闭
  done()
}

Props ​

参数类型默认值说明
model-value / v-modelbooleanfalse是否显示对话框
titlestring''对话框标题
widthstring | number—宽度
heightstring | number—高度
topstring—非全屏时距顶部的距离(margin-top)
centerbooleanfalse是否水平居中对齐头部与底部内容
centeredbooleantrue是否垂直居中对话框
draggablebooleanfalse是否可拖拽
overflowbooleanfalse拖拽时是否允许超出视口
resizeablebooleantrue是否可通过右下角调整大小
fullscreenbooleanfalse是否全屏
fullscreenablebooleanfalse是否显示全屏切换按钮
closeablebooleantrue是否显示关闭按钮
close-iconstring—自定义关闭按钮图标
modalbooleantrue是否显示遮罩
modal-classstring—遮罩的自定义类名
mask-closeablebooleanfalse点击遮罩是否可关闭
escape-closeablebooleantrue按 ESC 是否可关闭
lock-scrollbooleantrue打开时是否锁定页面滚动
append-to-bodybooleanfalse是否附加到 body,嵌套对话框时应设置为 true
append-tostring | HTMLElement'body'挂载的目标容器
destroy-on-closebooleanfalse关闭时是否销毁元素
open-delaynumber0打开延迟(ms)
close-delaynumber0关闭延迟(ms)
before-close(done: (cancel?: boolean) => void) => void—关闭前回调,可拦截关闭
z-indexnumber—自定义 z-index,不传时自动递增
trap-focusbooleanfalse是否圈定焦点
header-aria-levelstring'2'头部标题的 aria-level 属性

Emits ​

事件名参数说明
update:model-value(value: boolean)显示状态变化时触发
open—打开时触发
opened—打开动画结束时触发
close—关闭流程开始时触发
closed—关闭动画结束时触发
open-auto-focus—打开时焦点圈定完成后触发
close-auto-focus—关闭时焦点释放后触发
change-screen-state(state: boolean)全屏状态切换时触发,true 为全屏

Slots ​

插槽名参数说明
headerclose / title-id / title-class头部区域;作用域参数为关闭函数、标题 id 与标题类名
title—标题内容,优先级高于 header 插槽
default—对话框内容
footer—底部区域

方法 ​

通过 ref 可调用以下方法:

方法名参数说明
resetPosition—重置拖拽后的位置,恢复初始状态