@neosjs/dialog
对话框组件。基于 Teleport 与 Overlay 实现,内置焦点圈定(FocusTrap),支持拖拽、调整大小、全屏切换、延迟打开/关闭等能力,是 Modal 之外更完整的对话交互容器。
安装
sh
pnpm add @neosjs/dialogsh
npm i @neosjs/dialogsh
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-model | boolean | false | 是否显示对话框 |
| title | string | '' | 对话框标题 |
| width | string | number | — | 宽度 |
| height | string | number | — | 高度 |
| top | string | — | 非全屏时距顶部的距离(margin-top) |
| center | boolean | false | 是否水平居中对齐头部与底部内容 |
| centered | boolean | true | 是否垂直居中对话框 |
| draggable | boolean | false | 是否可拖拽 |
| overflow | boolean | false | 拖拽时是否允许超出视口 |
| resizeable | boolean | true | 是否可通过右下角调整大小 |
| fullscreen | boolean | false | 是否全屏 |
| fullscreenable | boolean | false | 是否显示全屏切换按钮 |
| closeable | boolean | true | 是否显示关闭按钮 |
| close-icon | string | — | 自定义关闭按钮图标 |
| modal | boolean | true | 是否显示遮罩 |
| modal-class | string | — | 遮罩的自定义类名 |
| mask-closeable | boolean | false | 点击遮罩是否可关闭 |
| escape-closeable | boolean | true | 按 ESC 是否可关闭 |
| lock-scroll | boolean | true | 打开时是否锁定页面滚动 |
| append-to-body | boolean | false | 是否附加到 body,嵌套对话框时应设置为 true |
| append-to | string | HTMLElement | 'body' | 挂载的目标容器 |
| destroy-on-close | boolean | false | 关闭时是否销毁元素 |
| open-delay | number | 0 | 打开延迟(ms) |
| close-delay | number | 0 | 关闭延迟(ms) |
| before-close | (done: (cancel?: boolean) => void) => void | — | 关闭前回调,可拦截关闭 |
| z-index | number | — | 自定义 z-index,不传时自动递增 |
| trap-focus | boolean | false | 是否圈定焦点 |
| header-aria-level | string | '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
| 插槽名 | 参数 | 说明 |
|---|---|---|
| header | close / title-id / title-class | 头部区域;作用域参数为关闭函数、标题 id 与标题类名 |
| title | — | 标题内容,优先级高于 header 插槽 |
| default | — | 对话框内容 |
| footer | — | 底部区域 |
方法
通过 ref 可调用以下方法:
| 方法名 | 参数 | 说明 |
|---|---|---|
| resetPosition | — | 重置拖拽后的位置,恢复初始状态 |