uniapp-dyckui 4.1.1

package/src/components/MyComs/Popup/README.md

@@ -0,0 +1,684 @@
+# Popup 弹窗组件
+
+<div align="center">
+
+![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+![Vue](https://img.shields.io/badge/Vue-3.x-brightgreen.svg)
+![Platform](https://img.shields.io/badge/platform-H5%20%7C%20MiniApp%20%7C%20App-orange.svg)
+
+一个功能强大、灵活易用的弹窗组件，支持多种位置、动画效果和自定义配置。
+
+</div>
+
+---
+
+## 📋 目录
+
+- [特性介绍](#-特性介绍)
+- [快速开始](#-快速开始)
+- [API文档](#-api文档)
+- [使用示例](#-使用示例)
+- [最佳实践](#-最佳实践)
+- [常见问题](#-常见问题)
+
+---
+
+## ✨ 特性介绍
+
+### 🎯 核心功能
+- ✅ **双向绑定**：支持 `v-model` 双向绑定控制显示/隐藏
+- 🎨 **多种位置**：支持居中、顶部、底部、左侧、右侧位置
+- 🎭 **丰富动画**：支持淡入淡出、缩放、滑动等动画效果
+- 🖼️ **灵活遮罩**：可配置遮罩层透明度和点击关闭行为
+- ⌨️ **键盘支持**：支持 ESC 键关闭弹窗
+- 🔒 **滚动锁定**：弹窗打开时自动锁定背景滚动
+- 📱 **响应式设计**：完美适配各种屏幕尺寸
+
+### 🎨 视觉效果
+- 🎪 **模态/非模态**：支持带遮罩和无遮罩两种模式
+- 🎯 **自定义样式**：支持自定义头部、内容和底部区域
+- 🎬 **流畅动画**：所有动画效果均使用 CSS3 实现，性能优异
+- 🎨 **现代设计**：采用现代扁平化设计风格
+
+### 🛠️ 技术特点
+- 📦 **零依赖**：纯 CSS3 + Vue3 实现，无第三方依赖
+- ⚡ **高性能**：使用 CSS3 硬件加速，流畅不卡顿
+- 🔧 **易扩展**：支持插槽和事件回调，方便扩展
+- 📚 **类型安全**：完整的 TypeScript 类型定义
+
+---
+
+## 🚀 快速开始
+
+### 安装使用
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import Popup from '@/components/MyComs/Popup/index.vue'
+
+const showPopup = ref(false)
+</script>
+
+<template>
+  <button @click="showPopup = true">打开弹窗</button>
+  
+  <Popup v-model="showPopup" title="弹窗标题">
+    弹窗内容
+  </Popup>
+</template>
+```
+
+### 最小化配置
+
+```vue
+<Popup v-model="visible">
+  最简单的弹窗
+</Popup>
+```
+
+---
+
+## 📚 API文档
+
+### Props 属性
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `modelValue` | `Boolean` | `false` | 控制弹窗显示/隐藏（支持v-model） |
+| `title` | `String` | `''` | 弹窗标题 |
+| `position` | `'center' \| 'top' \| 'bottom' \| 'left' \| 'right'` | `'center'` | 弹窗位置 |
+| `animation` | `'fade' \| 'scale' \| 'slide'` | `'slide'` | 动画效果 |
+| `mask` | `Boolean` | `true` | 是否显示遮罩层 |
+| `maskOpacity` | `Number` | `0.5` | 遮罩层透明度（0-1） |
+| `closeOnMaskClick` | `Boolean` | `true` | 点击遮罩是否关闭弹窗 |
+| `showCloseButton` | `Boolean` | `true` | 是否显示关闭按钮 |
+| `closeOnEsc` | `Boolean` | `true` | 是否支持Esc键关闭 |
+| `showConfirmButton` | `Boolean` | `false` | 是否显示确认按钮 |
+| `confirmText` | `String` | `'确定'` | 确认按钮文本 |
+| `showCancelButton` | `Boolean` | `false` | 是否显示取消按钮 |
+| `cancelText` | `String` | `'取消'` | 取消按钮文本 |
+| `width` | `String \| Number` | `'50%'` | 弹窗宽度 |
+| `height` | `String \| Number` | `'100%'` | 弹窗高度 |
+| `maxWidth` | `String \| Number` | `'500px'` | 弹窗最大宽度 |
+| `lockScroll` | `Boolean` | `true` | 是否禁止背景滚动 |
+
+### Events 事件
+
+| 事件名 | 触发时机 | 参数 |
+|--------|----------|------|
+| `update:modelValue` | 弹窗显示状态改变 | `Boolean: visible` |
+| `open` | 弹窗打开时 | - |
+| `close` | 弹窗关闭时 | - |
+| `maskClick` | 点击遮罩层时 | - |
+| `confirm` | 点击确认按钮时 | - |
+| `cancel` | 点击取消按钮时 | - |
+| `closeButtonClick` | 点击关闭按钮时 | - |
+
+### Slots 插槽
+
+| 插槽名 | 说明 |
+|--------|------|
+| `default` | 弹窗内容区域（默认插槽） |
+| `header` | 弹窗头部区域（自定义头部时使用） |
+| `footer` | 弹窗底部区域（自定义底部按钮时使用） |
+
+---
+
+## 📝 使用示例
+
+### 🎯 基本使用
+
+```vue
+<template>
+  <button @click="showPopup = true">打开弹窗</button>
+  
+  <Popup v-model="showPopup" title="弹窗标题">
+    弹窗内容
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import Popup from '@/components/MyComs/Popup/index.vue'
+
+const showPopup = ref(false)
+</script>
+```
+
+### 🔘 带确认取消按钮
+
+```vue
+<template>
+  <button @click="showConfirm = true">打开确认弹窗</button>
+  
+  <Popup
+    v-model="showConfirm"
+    title="确认操作"
+    :show-confirm-button="true"
+    :show-cancel-button="true"
+    @confirm="handleConfirm"
+    @cancel="handleCancel"
+  >
+    确定要执行此操作吗？
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import Popup from '@/components/MyComs/Popup/index.vue'
+
+const showConfirm = ref(false)
+
+const handleConfirm = () => {
+  console.log('确认操作')
+  showConfirm.value = false
+}
+
+const handleCancel = () => {
+  console.log('取消操作')
+  showConfirm.value = false
+}
+</script>
+```
+
+### 🎨 不同位置弹窗
+
+```vue
+<template>
+  <div class="button-group">
+    <button @click="showTopPopup = true">顶部弹窗</button>
+    <button @click="showBottomPopup = true">底部弹窗</button>
+    <button @click="showLeftPopup = true">左侧弹窗</button>
+    <button @click="showRightPopup = true">右侧弹窗</button>
+  </div>
+  
+  <!-- 顶部弹窗 -->
+  <Popup v-model="showTopPopup" position="top" title="顶部弹窗">
+    这是一个从顶部弹出的消息提示弹窗
+  </Popup>
+  
+  <!-- 底部弹窗 -->
+  <Popup v-model="showBottomPopup" position="bottom" title="底部弹窗">
+    这是一个从底部弹出的菜单选择弹窗
+  </Popup>
+  
+  <!-- 左侧弹窗 -->
+  <Popup v-model="showLeftPopup" position="left" width="60%" title="左侧菜单">
+    这是一个侧边栏菜单弹窗
+  </Popup>
+  
+  <!-- 右侧弹窗 -->
+  <Popup v-model="showRightPopup" position="right" width="60%" title="右侧面板">
+    这是一个详情面板弹窗
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import Popup from '@/components/MyComs/Popup/index.vue'
+
+const showTopPopup = ref(false)
+const showBottomPopup = ref(false)
+const showLeftPopup = ref(false)
+const showRightPopup = ref(false)
+</script>
+```
+
+### 🎭 动画效果演示
+
+```vue
+<template>
+  <div class="demo-section">
+    <h3>动画效果</h3>
+    <div class="button-group">
+      <button @click="showFadePopup = true">淡入淡出</button>
+      <button @click="showScalePopup = true">缩放效果</button>
+      <button @click="showSlidePopup = true">滑动效果</button>
+    </div>
+  </div>
+
+  <!-- 淡入淡出动画 -->
+  <Popup
+    v-model="showFadePopup"
+    title="淡入淡出动画"
+    animation="fade"
+    :show-confirm-button="true"
+    @confirm="showFadePopup = false"
+  >
+    这是一个使用淡入淡出动画效果的弹窗
+  </Popup>
+
+  <!-- 缩放动画 -->
+  <Popup
+    v-model="showScalePopup"
+    title="缩放动画"
+    animation="scale"
+    :show-confirm-button="true"
+    @confirm="showScalePopup = false"
+  >
+    这是一个使用缩放动画效果的弹窗
+  </Popup>
+
+  <!-- 滑动动画 -->
+  <Popup
+    v-model="showSlidePopup"
+    title="滑动动画"
+    animation="slide"
+    :show-confirm-button="true"
+    @confirm="showSlidePopup = false"
+  >
+    这是一个使用滑动动画效果的弹窗
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import Popup from '@/components/MyComs/Popup/index.vue'
+
+const showFadePopup = ref(false)
+const showScalePopup = ref(false)
+const showSlidePopup = ref(false)
+</script>
+```
+
+### 🛠️ 自定义头部和底部
+
+```vue
+<template>
+  <button @click="showCustomPopup = true">自定义弹窗</button>
+  
+  <Popup v-model="showCustomPopup">
+    <!-- 自定义头部 -->
+    <template #header>
+      <view class="custom-header">
+        <text class="custom-header-title">🎉 欢迎使用</text>
+        <text class="custom-header-subtitle">这是一个精美的自定义头部</text>
+      </view>
+    </template>
+    
+    <view class="popup-content">
+      <p>这是弹窗的主要内容区域，您可以在这里放置任何内容。</p>
+      <p>支持文本、图片、表单等各种元素。</p>
+    </view>
+
+    <!-- 自定义底部 -->
+    <template #footer>
+      <view class="custom-footer">
+        <button class="custom-btn custom-btn-cancel" @click="showCustomPopup = false">
+          返回
+        </button>
+        <button class="custom-btn custom-btn-save" @click="handleSave">
+          保存
+        </button>
+        <button class="custom-btn custom-btn-submit" @click="handleSubmit">
+          提交
+        </button>
+      </view>
+    </template>
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import Popup from '@/components/MyComs/Popup/index.vue'
+
+const showCustomPopup = ref(false)
+
+const handleSave = () => {
+  console.log('保存操作')
+  // 这里可以添加保存逻辑
+}
+
+const handleSubmit = () => {
+  console.log('提交操作')
+  showCustomPopup.value = false
+}
+</script>
+
+<style scoped>
+.custom-header {
+  text-align: center;
+  padding: 20px;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  border-radius: 16px 16px 0 0;
+}
+
+.custom-header-title {
+  font-size: 36rpx;
+  font-weight: 600;
+  margin-bottom: 8rpx;
+}
+
+.custom-header-subtitle {
+  font-size: 24rpx;
+  opacity: 0.8;
+}
+
+.popup-content {
+  padding: 40rpx;
+  line-height: 1.6;
+}
+
+.custom-footer {
+  display: flex;
+  justify-content: center;
+  gap: 20rpx;
+  padding: 20rpx;
+}
+
+.custom-btn {
+  padding: 16rpx 32rpx;
+  border: none;
+  border-radius: 8rpx;
+  font-size: 28rpx;
+  cursor: pointer;
+  transition: all 0.3s ease;
+}
+
+.custom-btn-cancel {
+  background-color: #f5f7fa;
+  color: #606266;
+}
+
+.custom-btn-save {
+  background-color: #409eff;
+  color: white;
+}
+
+.custom-btn-submit {
+  background-color: #67c23a;
+  color: white;
+}
+
+.custom-btn:hover {
+  transform: translateY(-2rpx);
+  box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.15);
+}
+</style>
+```
+
+### 🎨 高级配置示例
+
+```vue
+<template>
+  <button @click="showAdvancedPopup = true">高级配置弹窗</button>
+  
+  <Popup
+    v-model="showAdvancedPopup"
+    title="高级配置"
+    position="center"
+    animation="scale"
+    :mask="true"
+    :mask-opacity="0.7"
+    :close-on-mask-click="true"
+    :show-close-button="true"
+    :show-confirm-button="true"
+    :show-cancel-button="true"
+    confirm-text="确认"
+    cancel-text="取消"
+    width="80%"
+    :max-width="'400px'"
+    :lock-scroll="true"
+    :close-on-esc="true"
+    @confirm="handleAdvancedConfirm"
+    @cancel="handleAdvancedCancel"
+    @mask-click="handleMaskClick"
+    @open="handlePopupOpen"
+    @close="handlePopupClose"
+  >
+    <view class="advanced-content">
+      <text>这是一个高级配置的弹窗示例</text>
+      <text>包含了所有可配置的选项</text>
+    </view>
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import Popup from '@/components/MyComs/Popup/index.vue'
+
+const showAdvancedPopup = ref(false)
+
+const handleAdvancedConfirm = () => {
+  console.log('高级弹窗确认')
+  showAdvancedPopup.value = false
+}
+
+const handleAdvancedCancel = () => {
+  console.log('高级弹窗取消')
+  showAdvancedPopup.value = false
+}
+
+const handleMaskClick = () => {
+  console.log('点击了遮罩层')
+}
+
+const handlePopupOpen = () => {
+  console.log('弹窗打开了')
+}
+
+const handlePopupClose = () => {
+  console.log('弹窗关闭了')
+}
+</script>
+
+<style scoped>
+.advanced-content {
+  padding: 40rpx;
+  text-align: center;
+}
+
+.advanced-content text {
+  display: block;
+  margin-bottom: 20rpx;
+  font-size: 28rpx;
+  color: #606266;
+}
+</style>
+```
+
+---
+
+## 💡 最佳实践
+
+### 🎯 场景选择指南
+
+| 使用场景 | 推荐配置 | 说明 |
+|----------|----------|------|
+| **信息提示** | `position: center`, `animation: fade` | 简洁明了，不干扰用户操作 |
+| **确认操作** | `showConfirmButton: true`, `showCancelButton: true` | 提供明确的确认和取消选项 |
+| **菜单选择** | `position: bottom`, `animation: slide` | 适合移动端的底部操作面板 |
+| **侧边栏** | `position: left/right`, `width: 60%` | 类似抽屉的侧边导航 |
+| **表单填写** | `position: center`, `lockScroll: true` | 避免背景滚动干扰 |
+| **图片预览** | `maskOpacity: 0.9`, `showCloseButton: true` | 突出显示内容 |
+
+### 🚀 性能优化建议
+
+1. **合理使用动画**
+   ```vue
+   <!-- 推荐：使用硬件加速的动画 -->
+   <Popup animation="fade" />
+   
+   <!-- 避免：在低端设备上使用复杂动画 -->
+   <Popup animation="scale" />
+   ```
+
+2. **控制弹窗数量**
+   ```vue
+   <!-- 推荐：使用v-if条件渲染 -->
+   <Popup v-if="showPopup" v-model="showPopup" />
+   
+   <!-- 避免：同时显示多个弹窗 -->
+   ```
+
+3. **优化内容渲染**
+   ```vue
+   <!-- 推荐：懒加载内容 -->
+   <Popup v-model="showPopup">
+     <LazyContent v-if="showPopup" />
+   </Popup>
+   ```
+
+### 🎨 样式定制指南
+
+1. **全局样式覆盖**
+   ```css
+   /* 在全局CSS中定义自定义样式 */
+   .custom-popup .popup-container {
+     border-radius: 20rpx;
+     background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+   }
+   ```
+
+2. **响应式适配**
+   ```vue
+   <Popup 
+     :width="isMobile ? '90%' : '50%'"
+     :max-width="isMobile ? '350px' : '500px'"
+   />
+   ```
+
+### 🔧 常见陷阱避免
+
+1. **v-model 绑定问题**
+   ```vue
+   <!-- 错误：直接使用 props 值 -->
+   <Popup :modelValue="propsValue" />
+   
+   <!-- 正确：使用 ref 响应式变量 -->
+   <Popup v-model="localValue" />
+   ```
+
+2. **事件处理优化**
+   ```vue
+   <!-- 推荐：使用箭头函数或显式绑定 -->
+   @confirm="() => handleConfirm(id)"
+   @cancel="handleCancel.bind(this, id)"
+   ```
+
+3. **内存泄漏预防**
+   ```vue
+   <script setup lang="ts">
+   import { onUnmounted } from 'vue'
+   
+   // 组件卸载时清理资源
+   onUnmounted(() => {
+     // 清理定时器、事件监听等
+   })
+   </script>
+   ```
+
+---
+
+## ❓ 常见问题
+
+### 🔍 FAQ
+
+**Q: 如何禁用 ESC 键关闭弹窗？**
+```vue
+<Popup :close-on-esc="false" v-model="show" />
+```
+
+**Q: 如何在弹窗外部点击时不关闭？**
+```vue
+<Popup :close-on-mask-click="false" v-model="show" />
+```
+
+**Q: 如何自定义弹窗的动画时长？**
+```vue
+<!-- 目前固定为0.3s，可通过CSS覆盖 -->
+<Popup v-model="show" class="custom-duration" />
+
+<style>
+.custom-duration .popup-container {
+  transition: all 0.5s ease;
+}
+</style>
+```
+
+**Q: 在uni-app小程序中如何使用？**
+```vue
+<!-- 完全兼容，无需特殊配置 -->
+<Popup v-model="showPopup" title="小程序弹窗">
+  小程序内容
+</Popup>
+```
+
+**Q: 如何实现无遮罩的弹窗？**
+```vue
+<Popup :mask="false" v-model="showPopup">
+  无遮罩弹窗
+</Popup>
+```
+
+**Q: 弹窗内容过长如何处理？**
+```vue
+<Popup v-model="showPopup">
+  <scroll-view scroll-y style="max-height: 400rpx;">
+    长内容区域
+  </scroll-view>
+</Popup>
+```
+
+**Q: 如何监听弹窗的打开/关闭事件？**
+```vue
+<Popup 
+  v-model="showPopup" 
+  @open="onOpen" 
+  @close="onClose"
+/>
+
+<script setup>
+const onOpen = () => console.log('弹窗打开了')
+const onClose = () => console.log('弹窗关闭了')
+</script>
+```
+
+### 🐛 问题排查
+
+1. **弹窗不显示**
+   - 检查 `v-model` 绑定的变量是否为响应式
+   - 确认 `showPopup` 初始值为 `true`
+
+2. **动画效果异常**
+   - 检查是否与其他CSS动画冲突
+   - 确认浏览器支持CSS3动画
+
+3. **在某些设备上显示异常**
+   - 检查viewport设置
+   - 确认uni-app版本兼容性
+
+4. **事件不触发**
+   - 检查事件处理函数是否正确定义
+   - 确认函数作用域正确
+
+---
+
+## 📄 更新日志
+
+### v1.0.0 (2024-01-01)
+- ✨ 初始版本发布
+- 🎯 支持五种位置模式
+- 🎭 支持三种动画效果
+- 🛠️ 完整的TypeScript类型定义
+- 📱 响应式设计适配
+- 🔧 丰富的配置选项
+
+---
+
+## 📄 许可证
+
+MIT License
+
+---
+
+<div align="center">
+
+**如果这个组件对您有帮助，请给个 ⭐ Star！**
+
+Made with ❤️ by Your Team
+
+</div>

package/src/components/MyComs/Popup/index.ts

@@ -0,0 +1,2 @@
+import Component from './index.vue';
+export default Component;