Appearance
AtModal
沈孟平
最后更新于 2026-10-30 11:40:07
一个封装了全屏和可拖拽的模态框组件。
Tip
可以使用 useModal 来控制模态框的显示隐藏
详细场景见 AtModal 复杂用法。
组件定位
AtModal 是一个偏“命令式”的弹窗容器，而不是简单的 v-model:show 薄封装。它在 NModal 之上补了几件中后台场景很常用的能力：
- 统一的头部、内容区和底部操作区
- 可拖拽
- 可切换全屏
- 内置滚动区域，便于在长表单或详情页中使用
- 支持从
AtConfigProvider读取全局默认配置
推荐使用方式
- 通过
ref或useModal调用open()/close()。 - 如果弹窗内容里还要拿子组件实例，建议
await open()之后再访问。 on-before-close仅拦截update:show(false)入口；默认底部取消和程序调用close不经过它。需要统一阻止关闭时使用自定义 right-action，并参照 复杂用法。
代码演示
基础示例
配合表单使用
注意，需要 await open() 之后才能获取到表单的实例。
API
TIP
AtModalProps 继承自 NaiveUI Modal Props
ModalProvider Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
| content-cls | string | undefined | 内容区样式 | v0.12.29 |
| mask-closable | boolean | false | 点击遮罩时是否发出 update:show 事件 | v0.12.29 |
AtModal Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
| title | string | undefined | 标题 | |
| width | number | string | 800px | 模态框主体宽度 | |
| show-action | boolean | true | 是否显示 action | |
| confirm-loading | boolean | undefined | showAction 为 true 时才有用 | |
| positive-btn-text | string | '确认' | 确认按钮文案 | |
| negative-btn-text | string | '取消' | 取消按钮文案 | |
| draggable | boolean | false | 是否可以拖拽 | |
| fullscreen | boolean | true | 是否显示全屏按钮 | |
| default-fullscreen | boolean | false | 打开时默认全屏 | |
| content-cls | string | undefined | 内容区样式 | |
| on-before-close | function | undefined | 同步拦截 update:show 关闭，返回 false 阻止；不覆盖底部取消和 close | |
| on-confirm | function | undefined | 点击确认按钮回调 | |
| on-cancel | function | undefined | 点击取消按钮回调 |
AtModal Events
| 名称 | 参数 | 说明 | 版本 |
|---|---|---|---|
| confirm | () | 点击确认按钮时触发 | |
| cancel | () | 默认取消按钮或允许的 update:show 关闭触发；程序 close 不触发 |
AtModal Slots
| 名称 | 参数 | 说明 | 版本 |
|---|---|---|---|
| default | () | 模态框主体内容 | |
| header | () | 自定义头部标题区域 | |
| header-extra | () | 自定义头部右上角区域，默认是全屏按钮 | |
| left-action | () | 底部操作区左侧内容 | |
| right-action | () | 底部操作区右侧内容，默认是取消/确认按钮 |
AtModal Expose
| 名称 | 类型 | 说明 | 版本 |
|---|---|---|---|
| open | () => Promise<void> | 打开模态框；如果后续要访问弹窗内部实例，建议 await open() | |
| close | () => void | 关闭模态框 | |
| scroll-ref | ScrollbarInst | 用于在模态框内定位元素: 例如滚动时固定某个元素 | |
| content-max-height | string | 用于外部获取内容可视区高度 |