Modal 弹窗

17:06

说明

基于 ux-popup 的居中模态框，可配置标题、内容文案、确认/取消按钮及其文案与颜色。默认点击确认或取消即自动关闭；开启 async-close 后点击确认只让按钮进入加载态，关闭时机交由调用方控制。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

点击按钮弹出模态框，支持自定义标题、内容和按钮。

查看源码

<template>
    <ux-button type="primary" @click="show = true">打开弹窗</ux-button>
    <ux-modal
        v-model="show"
        content="这是弹窗内容"
        :show-cancel-button="true"
        @confirm="onConfirm"
        @cancel="onCancel"
    />
</template>

<script setup lang="uts">
const show = ref<boolean>(false);

const onConfirm = () => {
    show.value = false;
    uni.showToast({ title: '点击了确定', icon: 'none' });
};

const onCancel = () => {
    show.value = false;
    uni.showToast({ title: '点击了取消', icon: 'none' });
};
</script>

自定义内容

自定义弹窗标题、内容与确认/取消按钮文案。

查看源码

<template>
    <ux-button type="success" @click="show = true">打开弹窗</ux-button>
    <ux-modal
        v-model="show"
        title="自定义弹窗"
        content="自定义标题与按钮文案的弹窗"
        :show-cancel-button="true"
        confirm-text="好的"
        cancel-text="不了"
        @confirm="onConfirm"
    />
</template>

<script setup lang="uts">
const show = ref<boolean>(false);

const onConfirm = () => {
    show.value = false;
    uni.showToast({ title: '点击了确定', icon: 'none' });
};
</script>

异步关闭

async-close=true 时，点击确认后显示加载状态，由外部控制关闭时机。

查看源码

<template>
    <ux-button type="warning" @click="show = true">打开弹窗</ux-button>
    <text v-if="loading" class="tip">正在处理...</text>
    <ux-modal
        v-model="show"
        title="异步关闭"
        content="点击确定后 2 秒自动关闭"
        :async-close="true"
        :show-cancel-button="true"
        @confirm="onConfirm"
    />
</template>

<script setup lang="uts">
const show = ref<boolean>(false);
const loading = ref<boolean>(false);

const onConfirm = () => {
    loading.value = true;
    setTimeout(() => {
        show.value = false;
        loading.value = false;
    }, 2000);
};
</script>

<style scoped>
.tip {
    font-size: 12px;
    color: #909399;
    margin-top: 6px;
}
</style>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	string | UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
modelValue	是否显示模态框	boolean	false	-
zIndex	层级 z-index	string | number	''	-
title	标题	string	''	-
width	弹窗宽度	string | number	300	-
content	弹窗内容	string	''	-
showTitle	是否显示标题	boolean	true	-
showConfirmButton	是否显示确认按钮	boolean	true	-
showCancelButton	是否显示取消按钮	boolean	false	-
confirmText	确认文案	string	''	-
cancelText	取消文案	string	''	-
confirmColor	确认按钮颜色	string	''	-
cancelColor	取消文字颜色	string	''	-
borderRadius	圆角值	string | number	8	-
titleStyle	标题的样式	UTSJSONObject	-	-
contentStyle	内容的样式	UTSJSONObject	-	-
cancelStyle	取消按钮的样式	UTSJSONObject	-	-
confirmStyle	确定按钮的样式	UTSJSONObject	-	-
zoom	是否开启缩放效果	boolean	true	-
asyncClose	是否异步关闭，只对确定按钮有效	boolean	false	-
maskCloseAble	是否允许点击遮罩关闭 modal	boolean	false	-
marginTop	纵向偏移量：正值下移、负值上移（避开键盘时传负值），透传给 ux-popup 的 margin-top	string | number	0	-
global	是否作为全局根部 modal（通常放在 App.vue 中，给 useModal() 使用）	boolean	false	-
page	是否作为页面级 modal（通常放在页面中，给 useModal({ page: true }) 使用）	boolean | string	false	-

Events

事件名	说明	回调参数	版本
confirm	确认按钮被点击	-	-
cancel	取消按钮被点击	-	-

Slots

插槽名	说明	版本
default	自定义弹窗内容区，存在时替代 content 文案	-
confirm-button	自定义确认按钮内容，存在时替代确认按钮的加载图标与文案	-

注意事项

1. async-close 只对确认按钮生效：点击确认后按钮进入加载态、弹窗不会自动关闭，需调用方在业务完成后把 v-model 置为 false；重新打开会重置加载态。
2. 非异步模式下点击确认或取消，组件会立即把显示状态置为 false（即自动关闭），调用方无需再手动关闭。
3. mask-close-able 默认为 false，即默认点击遮罩不会关闭；需要点遮罩关闭时显式传 true。
4. confirm / cancel 事件不带回调参数，异步请求等业务逻辑完全由调用方接管。
5. 标题、确认与取消文案留空时取组件内置 i18n 文案（默认「提示 / 确认 / 取消」），不是空字符串。
6. 确认按钮颜色默认取主题 primary、取消按钮默认取 contentColor；标题、内容与按钮样式可分别用 title-style、content-style、confirm-style、cancel-style 覆盖。
7. 通过 ref 暴露 clearLoading()，可在外部手动清除确认按钮的加载态。
8. global / page 是为函数式调用（配合 useModal()）预留的开关，当前版本库内未导出该 API，建议先用 v-model 受控方式使用。