platforms/.agents/skills/arco-design-vue/references/components/feedback/modal.md

name, description, user-invocable

name	description	user-invocable
arco-vue-modal	Arco Design Vue Modal 对话框 组件参考。用于 Vue 3、`@arco-design/web-vue`、`<a-modal>`、属性、事件、插槽、示例和实现细节。	false

Modal 对话框

简介

对话框的基本用法。

基本用法

<template>
  <a-button @click="handleClick">Open Modal</a-button>
  <a-modal v-model:visible="visible" @ok="handleOk" @cancel="handleCancel">
    <template #title>
      Title
    </template>
    <div>You can customize modal body text by the current situation. This modal will be closed immediately once you press the OK button.</div>
  </a-modal>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const visible = ref(false);

    const handleClick = () => {
      visible.value = true;
    };
    const handleOk = () => {
      visible.value = false;
    };
    const handleCancel = () => {
      visible.value = false;
    }

    return {
      visible,
      handleClick,
      handleOk,
      handleCancel
    }
  },
}
</script>

API

<modal> 属性

参数名	描述	类型	默认值	版本
visible (v-model)	对话框是否可见	boolean	-
default-visible	对话框默认是否可见（非受控状态）	boolean	false
width	对话框的宽度，不设置的情况下会使用样式中的宽度值	number|string	-	2.12.0
top	对话框的距离顶部的高度，居中显示开启的情况下不生效	number|string	-	2.12.0
mask	是否显示遮罩层	boolean	true
title	标题	string	-
title-align	标题的水平对齐方向	'start' | 'center'	'center'	2.17.0
align-center	对话框是否居中显示	boolean	true
unmount-on-close	关闭时是否卸载节点	boolean	false
mask-closable	是否点击遮罩层可以关闭对话框	boolean	true
hide-cancel	是否隐藏取消按钮	boolean	false
simple	是否开启简单模式	boolean	(props: any) => { return props.notice;}

仅列出常用项，低频属性按需查阅官方 API。

<modal> 事件

事件名	描述	参数	版本
ok	点击确定按钮时触发	ev: MouseEvent
cancel	点击取消、关闭按钮时触发	ev: MouseEvent | KeyboardEvent
open	对话框打开后（动画结束）触发	-
close	对话框关闭后（动画结束）触发	-
before-open	对话框打开前触发	-	2.16.0
before-close	对话框关闭前触发	-	2.16.0

<modal> 插槽

插槽名	描述	参数
title	标题	-
footer	页脚	-

<modal> 全局方法

Modal提供的全局方法，可以通过以下三种方法使用：

1. 通过this.$modal调用

2. 在Composition API中，通过getCurrentInstance().appContext.config.globalProperties.$modal调用

3. 导入Modal，通过Modal本身调用

import { createApp } from 'vue'
import { Modal } from '@arco-design/web-vue';

const app = createApp(App);
Modal._context = app._context;

ModalConfig

参数名	描述	类型	默认值	版本
title	标题	RenderContent	-
content	内容	RenderContent	-
footer	页脚	boolean | RenderContent	true
closable	是否显示关闭按钮	boolean	true
okText	确认按钮的内容	string	-
cancelText	取消按钮的内容	string	-
okButtonProps	确认按钮的Props	ButtonProps	-
cancelButtonProps	取消按钮的Props	ButtonProps	-
okLoading	确认按钮是否为加载中状态	boolean	false
hideCancel	是否隐藏取消按钮	boolean	false
mask	是否显示遮罩层	boolean	true
simple	是否开启简单模式	boolean	false

仅列出常用项，低频属性按需查阅官方 API。

ModalReturn

参数名	描述	类型	默认值	版本
close	关闭对话框	() => void	-
update	更新对话框	(config: ModalUpdateConfig) => void	-	2.43.2

ModalMethod

参数名	描述	类型	默认值
open	打开对话框	(config: ModalConfig, appContext?: AppContext) => ModalReturn	-
confirm	打开对话框（简单模式）	(config: ModalConfig, appContext?: AppContext) => ModalReturn	-
info	打开信息对话框	(config: ModalConfig, appContext?: AppContext) => ModalReturn	-
success	打开成功对话框	(config: ModalConfig, appContext?: AppContext) => ModalReturn	-
warning	打开警告对话框	(config: ModalConfig, appContext?: AppContext) => ModalReturn	-
error	打开错误对话框	(config: ModalConfig, appContext?: AppContext) => ModalReturn	-

常用模式

• 异步关闭：可以通过 on-before-ok 更简洁的实现异步关闭功能
• 函数调用：通过函数的方式使用对话框。
• 消息提示：有info, success, warning, error四种类型的消息提示，仅提供一个确认按钮用于关闭消息提示对话框。消息默认会默认开启 simple 和 hideCancel，如果想要取消可以再次设置。
• 对话框的宽度：设置 width="auto" 可以让对话框自适应宽度
• 定制按钮文字：设置 okText 与 cancelText 可以自定义按钮文字。
• 弹出层表单：在对话框中使用表单
• 可拖动：开启 draggable 属性，允许用户拖动对话框。
• 全屏：开启 fullscreen 属性，可以让对话框占满整个容器。

最佳实践

• 新代码优先使用 Vue 3、Composition API 和 <script setup lang="ts">。
• 模板属性使用 kebab-case，事件使用 @event-name，插槽使用 #slot-name。
• 不要套用 React 专属 API，例如 JSX children、Component.Sub 或 Form.useForm。
• 弹窗、抽屉、确认框等显隐状态使用 v-model:visible 或组件提供的方法统一管理。
• 异步操作要配合 loading、禁用态或全局反馈，避免重复提交。