ruoyi-plus-vben5/docs/src/components/common-ui/vben-modal.md

outline

outline
deep

Vben Modal 模态框

框架提供的模态框组件，支持拖拽、全屏、自动高度、loading等功能。

如果文档内没有参数说明，可以尝试在在线示例内寻找

::: info 写在前面

如果你觉得现有组件的封装不够理想，或者不完全符合你的需求，大可以直接使用原生组件，亦或亲手封装一个适合的组件。框架提供的组件并非束缚，使用与否，完全取决于你的需求与自由。

:::

::: tip README

下方示例代码中的，存在一些国际化、主题色未适配问题，这些问题只在文档内会出现，实际使用并不会有这些问题，可忽略，不必纠结。

:::

基础用法

使用 useVbenModal 创建最基础的模态框。

组件抽离

Modal 内的内容一般业务中，会比较复杂，所以我们可以将 modal 内的内容抽离出来，也方便复用。通过 connectedComponent 参数，可以将内外组件进行连接，而不用其他任何操作。

开启拖拽

通过 draggable 参数，可开启拖拽功能。

自动计算高度

弹窗会自动计算内容高度，超过一定高度会出现滚动条，同时结合 loading 效果以及使用 prepend-footer 插槽。

使用 Api

通过 modalApi 可以调用 modal 的方法以及使用 setState 更新 modal 的状态。

数据共享

如果你使用了 connectedComponent 参数，那么内外组件会共享数据，比如一些表单回填等操作。可以用 modalApi 来获取数据和设置数据，配合 onOpenChange，可以满足大部分的需求。

::: info 注意

• VbenModal 组件对与参数的处理优先级是 slot > props > state(通过api更新的状态以及useVbenModal参数)。如果你已经传入了 slot 或者 props，那么 setState 将不会生效，这种情况下你可以通过 slot 或者 props 来更新状态。
• 如果你使用到了 connectedComponent 参数，那么会存在 2 个useVbenModal, 此时，如果同时设置了相同的参数，那么以内部为准（也就是没有设置 connectedComponent 的代码）。比如 同时设置了 onConfirm，那么以内部的 onConfirm 为准。onOpenChange事件除外，内外都会触发。
• 使用了connectedComponent参数时，可以配置destroyOnClose属性来决定当关闭弹窗时，是否要销毁connectedComponent组件（重新创建connectedComponent组件，这将会把其内部所有的变量、状态、数据等恢复到初始状态。）。
• 如果弹窗的默认行为不符合你的预期，可以在src\bootstrap.ts中修改setDefaultModalProps的参数来设置默认的属性，如默认隐藏全屏按钮，修改默认ZIndex等。

:::

API

// Modal 为弹窗组件
// modalApi 为弹窗的方法
const [Modal, modalApi] = useVbenModal({
  // 属性
  // 事件
});

Props

所有属性都可以传入 useVbenModal 的第一个参数中。

属性名	描述	类型	默认值
appendToMain	是否挂载到内容区域（默认挂载到body）	boolean	false
connectedComponent	连接另一个Modal组件	Component	-
destroyOnClose	关闭时销毁connectedComponent	boolean	false
title	标题	string|slot	-
titleTooltip	标题提示信息	string|slot	-
description	描述信息	string|slot	-
isOpen	弹窗打开状态	boolean	false
loading	弹窗加载状态	boolean	false
fullscreen	全屏显示	boolean	false
fullscreenButton	显示全屏按钮	boolean	true
draggable	可拖拽	boolean	false
closable	显示关闭按钮	boolean	true
centered	居中显示	boolean	false
modal	显示遮罩	boolean	true
header	显示header	boolean	true
footer	显示footer	boolean|slot	true
confirmDisabled	禁用确认按钮	boolean	false
confirmLoading	确认按钮loading状态	boolean	false
closeOnClickModal	点击遮罩关闭弹窗	boolean	true
closeOnPressEscape	esc 关闭弹窗	boolean	true
confirmText	确认按钮文本	string|slot	确认
cancelText	取消按钮文本	string|slot	取消
showCancelButton	显示取消按钮	boolean	true
showConfirmButton	显示确认按钮	boolean	true
class	modal的class，宽度通过这个配置	string	-
contentClass	modal内容区域的class	string	-
footerClass	modal底部区域的class	string	-
headerClass	modal顶部区域的class	string	-
bordered	是否显示border	boolean	false
zIndex	弹窗的ZIndex层级	number	1000
overlayBlur	遮罩模糊度	number	-
submitting	标记为提交中，锁定弹窗当前状态	boolean	false

::: info appendToMain

appendToMain可以指定将弹窗挂载到内容区域，打开这种弹窗时，内容区域以外的部分（标签栏、导航菜单等等）不会被遮挡。默认情况下，弹窗会挂载到body上。但是：挂载到内容区域时，作为页面根容器的Page组件，需要设置auto-content-height属性，以便弹窗能够正确计算高度。

:::

Event

以下事件，只有在 useVbenModal({onCancel:()=>{}}) 中传入才会生效。

事件名	描述	类型	版本号
onBeforeClose	关闭前触发，返回 false或者被reject则禁止关闭	()=>Promise<boolean>|boolean	>5.5.2支持Promise
onCancel	点击取消按钮触发	()=>void
onClosed	关闭动画播放完毕时触发	()=>void	>5.4.3
onConfirm	点击确认按钮触发	()=>void
onOpenChange	关闭或者打开弹窗时触发	(isOpen:boolean)=>void
onOpened	打开动画播放完毕时触发	()=>void	>5.4.3

Slots

除了上面的属性类型包含slot，还可以通过插槽来自定义弹窗的内容。

插槽名	描述
default	默认插槽 - 弹窗内容
prepend-footer	取消按钮左侧
append-footer	取消按钮右侧

modalApi

方法	描述	类型	版本
setState	动态设置弹窗状态属性	(((prev: ModalState) => Partial<ModalState>)| Partial<ModalState>)=>modalApi	-
open	打开弹窗	()=>void	-
close	关闭弹窗	()=>void	-
setData	设置共享数据	<T>(data:T)=>modalApi	-
getData	获取共享数据	<T>()=>T	-
useStore	获取可响应式状态	-	-
lock	将弹窗标记为提交中，锁定当前状态	(isLock:boolean)=>modalApi	>5.5.2

::: info lock

lock方法用于锁定当前弹窗的状态，一般用于提交数据的过程中防止用户重复提交或者弹窗被意外关闭、表单数据被改变等等。当处于锁定状态时，弹窗的确认按钮会变为loading状态，同时禁用确认按钮、隐藏关闭按钮、禁止ESC或者点击遮罩等方式关闭弹窗、开启弹窗的spinner动画以遮挡弹窗内容。调用close方法关闭处于锁定状态的弹窗时，会自动解锁。

:::