# uni-modal

**Repository Path**: ipenge/uni-modal

## Basic Information

- **Project Name**: uni-modal
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-28
- **Last Updated**: 2025-12-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UniApp Modal 组件 (Vue3 + TypeScript)

一个功能完善、高度可定制的 UniApp 弹窗组件，支持受控模式，内置防页面滚动功能。

## ✨ 特性

- ✅ **Vue3 + TypeScript**: 完整的类型支持，优秀的开发体验
- ✅ **受控组件**: 通过 `v-model:visible` 完全控制弹窗状态
- ✅ **防页面滚动**: 弹窗显示时自动锁定页面滚动，避免交互冲突
- ✅ **高度可定制**: 支持自定义样式、按钮、内容等
- ✅ **插槽支持**: 支持自定义内容和底部按钮
- ✅ **多端兼容**: 支持 H5、小程序、App 等多端
- ✅ **动画效果**: 平滑的进入退出动画
- ✅ **加载状态**: 支持确认按钮加载状态

## 📦 安装

直接将组件文件复制到你的项目中：

```
src/
├── components/
│   └── Modal/
│       ├── index.vue    # 主组件
│       └── index.ts     # 类型导出
└── pages/
    └── index/
        └── index.vue    # 示例页面
```

## 🔧 基础用法

```vue
<template>
  <view>
    <button @click="visible = true">打开弹窗</button>

    <Modal
      v-model:visible="visible"
      title="提示"
      content="这是一个基础弹窗"
      @confirm="handleConfirm"
      @cancel="handleCancel"
    />
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import Modal from '@/components/Modal/index.vue'

const visible = ref(false)

const handleConfirm = () => {
  console.log('确认')
  visible.value = false
}

const handleCancel = () => {
  console.log('取消')
  visible.value = false
}
</script>
```

## 📝 Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| visible | `boolean` | `false` | **必填**，控制弹窗显示/隐藏 |
| title | `string` | `'提示'` | 标题 |
| content | `string` | `''` | 内容（仅在无插槽时显示） |
| showHeader | `boolean` | `true` | 是否显示头部 |
| showClose | `boolean` | `false` | 是否显示关闭按钮 |
| showFooter | `boolean` | `true` | 是否显示底部 |
| showCancel | `boolean` | `true` | 是否显示取消按钮 |
| showConfirm | `boolean` | `true` | 是否显示确认按钮 |
| cancelText | `string` | `'取消'` | 取消按钮文字 |
| confirmText | `string` | `'确定'` | 确认按钮文字 |
| confirmLoading | `boolean` | `false` | 确认按钮加载状态 |
| width | `string \| number` | `'80%'` | 弹窗宽度（支持 rpx 或百分比） |
| maxHeight | `string \| number` | `'60vh'` | 弹窗最大高度 |
| borderRadius | `string \| number` | `'16rpx'` | 圆角 |
| bgColor | `string` | `'#ffffff'` | 背景色 |
| closeOnClickOverlay | `boolean` | `true` | 点击遮罩是否关闭 |
| disableScroll | `boolean` | `true` | 是否禁用页面滚动 |

## 🎨 Events

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| update:visible | 弹窗状态变化 | `(value: boolean)` |
| confirm | 点击确认按钮 | `()` |
| cancel | 点击取消按钮 | `()` |
| close | 点击关闭按钮或遮罩 | `()` |
| open | 弹窗打开时触发 | `()` |

## 🎯 插槽

### 默认插槽
替换整个内容区域：

```vue
<Modal v-model:visible="visible" title="自定义内容">
  <view class="custom-content">
    <text>这里是自定义内容</text>
    <image src="..." />
  </view>
</Modal>
```

### Footer 插槽
自定义底部按钮：

```vue
<Modal v-model:visible="visible" :show-footer="false">
  <template #footer>
    <view class="custom-footer">
      <button @click="handleCancel">自定义取消</button>
      <button @click="handleConfirm">自定义确认</button>
    </view>
  </template>
</Modal>
```

## 🚀 高级用法

### 1. 自定义样式

```vue
<Modal
  v-model:visible="visible"
  title="自定义样式"
  content="自定义颜色和大小"
  :width="340"
  :border-radius="24"
  bg-color="#f8f9fa"
  cancel-text="放弃"
  confirm-text="同意"
/>
```

### 2. 确认按钮加载状态

```vue
<Modal
  v-model:visible="visible"
  :confirm-loading="loading"
  @confirm="handleSubmit"
/>

<script setup>
const loading = ref(false)
const handleSubmit = async () => {
  loading.value = true
  await api.submit()
  loading.value = false
  visible.value = false
}
</script>
```

### 3. 仅显示确认按钮

```vue
<Modal
  v-model:visible="visible"
  title="确认操作"
  :show-cancel="false"
  confirm-text="我明白了"
  @confirm="handleConfirm"
/>
```

### 4. 完全自定义内容

```vue
<Modal
  v-model:visible="visible"
  title="表单提交"
  :show-cancel="false"
  :show-confirm="false"
>
  <form @submit="onSubmit">
    <input type="text" v-model="formData.name" />
    <input type="email" v-model="formData.email" />
  </form>

  <template #footer>
    <button @click="onSubmit">提交</button>
  </template>
</Modal>
```

## 🔒 防页面滚动机制

本组件通过以下方式确保弹窗显示时页面无法滚动：

1. **触摸事件阻止**: 使用 `@touchmove.stop.prevent` 阻止事件冒泡
2. **CSS 控制**: 在 H5 端通过修改 `body.overflow` 属性
3. **组件隔离**: 设置 `touch-action: none` 防止穿透滚动

## 📱 多端兼容性

| 平台 | 兼容性 | 说明 |
|------|--------|------|
| H5 | ✅ 完美支持 | 包括移动端和桌面端 |
| 微信小程序 | ✅ 完美支持 | 包括 iOS 和 Android |
| App (iOS/Android) | ✅ 完美支持 | 原生体验 |
| 支付宝小程序 | ✅ 支持 | 基础功能 |
| 其他小程序 | ✅ 支持 | 基础功能 |

## 🎯 最佳实践

### 1. 状态管理
始终使用 `v-model:visible` 来控制弹窗状态，保持单向数据流：

```vue
<Modal v-model:visible="modalVisible" />
```

### 2. 异步操作
处理异步操作时，使用 `confirmLoading` 提供用户反馈：

```vue
<Modal
  v-model:visible="visible"
  :confirm-loading="loading"
  @confirm="handleAsyncConfirm"
/>

<script setup>
const handleAsyncConfirm = async () => {
  try {
    await api.submit()
    visible.value = false
  } catch (error) {
    // 处理错误
  }
}
</script>
```

### 3. 内容过长处理
当内容过长时，组件会自动在内容区域显示滚动条，不会影响弹窗整体布局。

### 4. 避免嵌套弹窗
尽量避免弹窗嵌套，如确需使用，请确保状态管理清晰。

## 🐛 常见问题

### Q: 为什么页面还是可以滚动？
A: 确保 `disableScroll` 设置为 `true`（默认值），并且在 H5 端检查是否有其他样式覆盖。

### Q: 小程序中防滚动失效？
A: 小程序端主要依赖 `@touchmove.stop.prevent`，确保没有其他组件阻止了事件冒泡。

### Q: 如何修改弹窗层级？
A: 组件默认 `z-index: 999`，如需调整，可通过全局 CSS 覆盖：

```css
.modal-overlay {
  z-index: 1000 !important;
}
```

## 📄 许可

MIT License

## 🤝 贡献

欢迎提交 Issue 和 PR！

---

**开发愉快！** 🎉