Modal 模态框 | Tuff Docs

用法

基础

v-model 控制显隐，footer 插槽放置操作按钮。

示例加载中...

全屏面板

fullscreen 撑满可见视口：正文滚动，头部与底栏固定，底栏避开底部安全区。

<TxModal v-model="previewOpen" fullscreen :title="current?.name">
  <img :src="current.url" alt="">
  <template #footer>
    <TxButton variant="ghost" @click="previewOpen = false">关闭</TxButton>
  </template>
</TxModal>

最佳实践

只用于确认、单步输入或短决策；需要导航、筛选或长表单时用抽屉或页面。
自定义 header 时保留可见标题并让 title 留空，否则 aria-labelledby 会指向不存在的元素。
破坏性或最终操作放在 footer，次要操作的视觉权重低于主操作。
fullscreen 只用于内容本身占满屏幕的场景（图片、图表预览），短确认不要用。
长耗时的异步状态不要只存在模态框内容里；关闭会取消任务时，由父级显式建模取消。

API 参考

属性

属性名	类型	默认值	说明
`modelValue`	`boolean`	必填	是否显示，用于 `v-model`。
`title`	`string`	`''`	默认头部标题；非空时与 `aria-labelledby` 关联。
`width`	`string`	`'480px'`	面板宽度，推荐 `min(92vw, 520px)` 这类响应式值；`fullscreen` 时忽略。
`fullscreen`	`boolean`	`false`	面板撑满可见视口，去掉圆角与阴影。

事件

事件名	参数	说明
`update:modelValue`	`(value: boolean)`	请求改变可见状态时触发。
`close`	`()`	点击遮罩、按 Escape 或点击关闭按钮后触发。

插槽

插槽名	Props	说明
`default`	-	主体内容。
`header`	-	替换标题区域，保留内置关闭按钮。
`footer`	-	底部操作区；未提供时不渲染。

概述

遮罩 teleport 到 body，打开时从共享 z-index manager 取得新层级，关闭时由 v-if 移除。
遮罩为 role="dialog"、aria-modal="true"；打开时获得焦点，关闭或卸载时焦点回到打开前的元素。
Tab 与 Shift+Tab 在最上层的模态框内循环；即使焦点落到 body，底层抽屉也不会响应 Escape。
点击遮罩空白、Escape 与关闭按钮依次派发 update:modelValue(false) 与 close。
fullscreen 只改变布局，对话框语义与焦点管理不变；没有可点击的遮罩空白，因此头部或底栏必须保留可见的关闭入口。
TModal 把 props、attrs、事件与 default / header / footer 插槽转发给 TxModal。

技术实现

全屏面板在支持时使用 100dvh 高度，底栏下内边距带上 safe-area-inset-bottom。
源码：packages/tuffex/packages/components/src/modal/（TxModal.vue 与包装组件 TModal.vue）。

查看源码

packages/tuffex/packages/components/src/modal/index.ts