zx-dialog 弹出框组件

介绍

Dialog 弹出框，在浮层中显示弹窗，引导用户进行相关操作。常用于消息提示、消息确认，或在当前页面内完成特定的交互操作。

特性

• 支持函数调用和组件调用两种方式
• 支持自定义标题、内容、按钮文案和颜色
• 支持异步关闭
• 支持自定义样式和主题
• 支持插槽自定义内容
• 内置动画效果
• 支持点击遮罩层关闭

基础用法

消息提示

用于提示一些消息，只包含一个确认按钮。

<template>
  <zx-dialog 
    :show="showDialog" 
    @update:show="(val) => showDialog = val"
    title="提示"
    message="这是一条消息提示"
    @confirm="onConfirm"
  />
</template>

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

const showDialog = ref(false)

const onConfirm = () => {
  console.log('确认')
}
</script>

消息确认

用于确认消息，包含取消和确认按钮。

<template>
  <zx-dialog 
    :show="showDialog" 
    @update:show="(val) => showDialog = val"
    title="提示"
    message="确定要删除这条记录吗？"
    :show-cancel-button="true"
    @confirm="onConfirm"
    @cancel="onCancel"
  />
</template>

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

const showDialog = ref(false)

const onConfirm = () => {
  console.log('确认删除')
}

const onCancel = () => {
  console.log('取消删除')
}
</script>

圆角按钮风格

将 theme 设置为 round-button 可以展示圆角按钮风格的弹窗。

<template>
  <zx-dialog 
    :show="showDialog" 
    @update:show="(val) => showDialog = val"
    title="提示"
    message="圆角按钮风格"
    theme="round-button"
    :show-cancel-button="true"
  />
</template>

自定义内容

通过插槽可以自定义弹窗的内容。

<template>
  <zx-dialog 
    :show="showDialog" 
    @update:show="(val) => showDialog = val"
    title="自定义内容"
  >
    <view class="custom-content">
      <input placeholder="请输入用户名" />
      <input type="password" placeholder="请输入密码" />
    </view>
  </zx-dialog>
</template>

自定义标题

通过 title 插槽可以自定义标题内容。

<template>
  <zx-dialog 
    :show="showDialog" 
    @update:show="(val) => showDialog = val"
    message="这是消息内容"
  >
    <template #title>
      <view class="custom-title">
        <text>🎉 自定义标题</text>
      </view>
    </template>
  </zx-dialog>
</template>

API

Props

| 参数 | 说明 | 类型 | 默认值 | |------|------|------|--------| | show | 是否显示弹窗 | boolean | false | | title | 标题 | string | - | | width | 弹窗宽度，默认单位为 rpx | string | number | 640rpx | | message | 文本内容，支持通过 \n 换行 | string | - | | message-align | 内容水平对齐方式，可选值为 left right center justify | string | center | | theme | 样式风格，可选值为 round-button | string | default | | show-confirm-button | 是否展示确认按钮 | boolean | true | | show-cancel-button | 是否展示取消按钮 | boolean | false | | confirm-button-text | 确认按钮文案 | string | 确认 | | confirm-button-color | 确认按钮颜色 | string | #ee0a24 | | confirm-button-disabled | 是否禁用确认按钮 | boolean | false | | cancel-button-text | 取消按钮文案 | string | 取消 | | cancel-button-color | 取消按钮颜色 | string | #646566 | | cancel-button-disabled | 是否禁用取消按钮 | boolean | false | | z-index | 将弹窗的 z-index 层级设置为一个固定值 | string | number | 2000 | | overlay | 是否展示遮罩层 | boolean | true | | overlay-class | 自定义遮罩层类名 | string | - | | overlay-style | 自定义遮罩层样式 | object | {} | | close-on-click-overlay | 是否在点击遮罩层后关闭弹窗 | boolean | false | | lazy-render | 是否在显示弹层时才渲染节点 | boolean | true | | lock-scroll | 是否锁定背景滚动 | boolean | true | | transition | 动画类名 | string | - |

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | confirm | 点击确认按钮时触发 | - | | cancel | 点击取消按钮时触发 | - | | open | 打开弹窗时触发 | - | | close | 关闭弹窗时触发 | - | | opened | 打开弹窗且动画结束后触发 | - | | closed | 关闭弹窗且动画结束后触发 | - | | update:show | 更新 show 状态 | show: boolean |

Slots

| 名称 | 说明 | |------|------| | default | 自定义内容 | | title | 自定义标题 | | footer | 自定义底部按钮区域 |

方法

通过 ref 可以获取到 Dialog 实例并调用实例方法。

| 方法名 | 说明 | 参数 | 返回值 | |--------|------|------|--------| | open | 打开弹窗 | - | - | | close | 关闭弹窗 | - | - |

<template>
  <zx-dialog ref="dialogRef" />
</template>

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

const dialogRef = ref()

// 打开弹窗
const openDialog = () => {
  dialogRef.value.open()
}

// 关闭弹窗
const closeDialog = () => {
  dialogRef.value.close()
}
</script>

样式变量

组件提供了下列 CSS 变量，可用于自定义样式。

| 名称 | 默认值 | 描述 | |------|--------|------| | --zx-dialog-width | 640rpx | 弹窗宽度 | | --zx-dialog-max-width | 90vw | 弹窗最大宽度 | | --zx-dialog-max-height | 90vh | 弹窗最大高度 | | --zx-dialog-background | #fff | 弹窗背景色 | | --zx-dialog-border-radius | 32rpx | 弹窗圆角 | | --zx-dialog-header-padding | 52rpx 48rpx 0 | 标题内边距 | | --zx-dialog-title-font-size | 32rpx | 标题字体大小 | | --zx-dialog-title-color | #323233 | 标题颜色 | | --zx-dialog-message-padding | 48rpx | 内容内边距 | | --zx-dialog-message-font-size | 28rpx | 内容字体大小 | | --zx-dialog-message-color | #646566 | 内容颜色 | | --zx-dialog-button-height | 100rpx | 按钮高度 | | --zx-dialog-button-font-size | 32rpx | 按钮字体大小 | | --zx-dialog-overlay-background | rgba(0, 0, 0, 0.7) | 遮罩层背景色 |

注意事项

1. 在 uniapp 中使用时，建议将组件放在页面的最外层，避免层级问题
2. 如果需要在弹窗中使用表单组件，建议使用插槽自定义内容
3. 弹窗的 z-index 默认为 2000，如有层级冲突可通过 z-index 属性调整
4. 组件支持 v-model:show 语法糖，可以更方便地控制显示状态

更新日志

v1.0.0

• 初始版本发布
• 支持基础的弹窗功能
• 支持自定义样式和主题
• 支持插槽自定义内容
• 支持动画效果
• 优化点击效果，延长 hover-stay-time
• 修复按钮边框和分隔线显示问题