Modal 弹窗

弹窗组件（Modal）用于在当前页面之上展示临时内容，支持 <Teleport> 传送、滚动穿透锁定、ESC 拦截、遮罩点击关闭等交互。

基础用法

通过 v-model 控制弹窗的显示与隐藏。弹窗包含头部（标题 + 关闭按钮）、内容区和底部操作栏。

查看代码

<script setup lang="ts">
import { ref } from 'vue'
const visible = ref(false)
</script>

<template>
  <button class="btn btn-primary" @click="visible = true">打开基础弹窗</button>
  <TModal v-model="visible" title="基础弹窗">
    <p>弹窗内容</p>
    <template #footer>
      <button class="btn btn-link link-secondary" @click="visible = false">取消</button>
      <button class="btn btn-primary ms-auto" @click="visible = false">确认</button>
    </template>
  </TModal>
</template>

居中弹窗

设置 centered 属性使弹窗在视口垂直居中。

<TModal v-model="visible" title="居中弹窗" centered>
  <p>这个弹窗在屏幕中垂直居中显示。</p>
</TModal>

不同尺寸

通过 size 属性控制弹窗宽度，支持 sm / lg / xl 三种预设尺寸。

查看代码

<script setup lang="ts">
const sizeRef = ref<'sm' | 'lg' | 'xl'>('sm')
</script>

<template>
  <button class="btn btn-secondary" @click="sizeRef = 'sm'; visible = true">小弹窗 (sm)</button>
  <button class="btn btn-secondary" @click="sizeRef = 'lg'; visible = true">大弹窗 (lg)</button>
  <button class="btn btn-secondary" @click="sizeRef = 'xl'; visible = true">超大弹窗 (xl)</button>
  <TModal v-model="visible" :size="sizeRef" centered>...</TModal>
</template>

可滚动内容

设置 scrollable 使弹窗内容区域可滚动，头部和底部操作栏固定。

<TModal v-model="visible" title="滚动内容弹窗" scrollable>
  <p v-for="i in 20" :key="i">这是第 {{ i }} 行内容。</p>
  <template #footer>
    <button class="btn btn-primary" @click="visible = false">关闭</button>
  </template>
</TModal>

表单弹窗

弹窗内可放置表单元素。

查看代码

<TModal v-model="visible" title="登录表单" centered>
  <div class="mb-3">
    <label class="form-label">用户名</label>
    <input v-model="username" type="text" class="form-control">
  </div>
  <template #footer>
    <button class="btn btn-primary ms-auto" @click="visible = false">提交</button>
  </template>
</TModal>

顶部状态条

通过 status 属性为弹窗添加彩色顶部状态条。

<TModal v-model="visible" title="操作成功" centered status="success">
  <p>操作已成功完成。</p>
</TModal>

模糊背景

设置 blur 属性使遮罩层具有毛玻璃模糊效果。

<TModal v-model="visible" title="毛玻璃效果" centered blur>
  <p>遮罩层带有毛玻璃模糊效果。</p>
</TModal>

API

Props

参数	类型	默认值	说明
modelValue	boolean	false	v-model 绑定值，控制弹窗显示/隐藏
title	string	—	弹窗标题
size	'sm' | 'lg' | 'xl' | 'fullscreen'	—	弹窗尺寸
fullWidth	boolean	false	全宽模式（max-width: none）
centered	boolean	false	是否垂直居中
scrollable	boolean	false	内容区域是否可滚动
closable	boolean	true	是否显示关闭按钮
closeOnBackdrop	boolean	true	点击遮罩层是否关闭
closeOnEsc	boolean	true	按 ESC 键是否关闭
status	TablerColor	—	顶部状态条颜色
blur	boolean	false	是否启用背景毛玻璃模糊
teleportTo	string	'body'	Teleport 传送目标选择器

Slots

名称	说明
default	弹窗主体内容
title	自定义标题区域
header	自定义整个头部（替换默认标题 + 关闭按钮）
footer	底部操作栏
status	顶部状态条

Emits

事件	参数	说明
update:modelValue	(value: boolean)	v-model 更新事件
open	—	弹窗开始打开时触发
opened	—	弹窗打开动画完成后触发
close	—	弹窗开始关闭时触发
closed	—	弹窗关闭动画完成后触发