uniapp-dyckui 4.1.1

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

@@ -0,0 +1,600 @@
+# 🎯 PullRefresh 下拉刷新组件
+
+<div align="center">
+
+![PullRefresh](https://img.shields.io/badge/PullRefresh-v1.0.0-blue.svg)
+![Vue](https://img.shields.io/badge/Vue-3.x-green.svg)
+![TypeScript](https://img.shields.io/badge/TypeScript-4.x-blue.svg)
+![UniApp](https://img.shields.io/badge/UniApp-3.x-red.svg)
+
+功能强大、灵活易用的下拉刷新与无限滚动组件
+
+</div>
+
+---
+
+## ✨ 特性
+
+- 🎯 **智能下拉刷新**：支持触摸下拉触发刷新，释放可刷新提示
+- 📜 **无限滚动加载**：滚动到底部自动加载更多数据
+- 🎨 **丰富的状态显示**：下拉距离、释放可刷新、刷新中、刷新完成等状态
+- 📱 **响应式设计**：完美适配各种屏幕尺寸
+- ⚡ **高性能优化**：节流处理，平滑动画效果
+- 🛠️ **高度可配置**：支持自定义文本、阈值、动画等
+- 🔄 **独立功能控制**：可独立启用/禁用下拉刷新和无限滚动
+- 🎭 **事件回调完善**：提供完整的生命周期事件
+
+---
+
+## 📚 目录
+
+- [特性](#-特性)
+- [快速开始](#-快速开始)
+- [API 文档](#-api-文档)
+- [使用示例](#-使用示例)
+- [最佳实践](#-最佳实践)
+- [常见问题](#-常见问题)
+- [更新日志](#-更新日志)
+- [许可证](#-许可证)
+
+---
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# 复制组件到项目中
+cp src/components/MyComs/PullRefresh src/your-project/components/
+```
+
+### 基础用法
+
+```vue
+<template>
+  <PullRefresh
+    :loading="loading"
+    :refreshLoading="refreshLoading"
+    :hasMore="hasMore"
+    :error="error"
+    @refresh="onRefresh"
+    @loadMore="onLoadMore"
+    @retry="onRetry"
+  >
+    <div class="list-container">
+      <div v-for="item in listData" :key="item.id" class="list-item">
+        {{ item.title }}
+      </div>
+    </div>
+  </PullRefresh>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import PullRefresh from '@/components/MyComs/PullRefresh/index.vue'
+
+const listData = ref([])
+const loading = ref(false)
+const refreshLoading = ref(false)
+const hasMore = ref(true)
+const error = ref(false)
+
+// 下拉刷新
+const onRefresh = async () => {
+  refreshLoading.value = true
+  // 模拟异步请求
+  await new Promise(resolve => setTimeout(resolve, 1500))
+  listData.value = []
+  for (let i = 1; i <= 10; i++) {
+    listData.value.push({ id: i, title: `刷新后的列表项${i}` })
+  }
+  hasMore.value = true
+  refreshLoading.value = false
+}
+
+// 加载更多
+const onLoadMore = async () => {
+  if (loading.value || !hasMore.value) return
+  loading.value = true
+  await new Promise(resolve => setTimeout(resolve, 1500))
+  const startIndex = listData.value.length + 1
+  for (let i = startIndex; i < startIndex + 10; i++) {
+    listData.value.push({ id: i, title: `列表项${i}` })
+  }
+  if (listData.value.length >= 30) {
+    hasMore.value = false
+  }
+  loading.value = false
+}
+
+// 重试加载
+const onRetry = () => {
+  error.value = false
+  onLoadMore()
+}
+</script>
+```
+
+### 使用示例代码片段
+```vue
+<template>
+  <PullRefresh
+    :loading="loading"
+    :refreshLoading="refreshLoading"
+    :hasMore="hasMore"
+    :error="error"
+    :threshold="30"
+    :refreshThreshold="40"
+    :refreshText="'下拉刷新'"
+    :releaseText="'释放可刷新'"
+    :refreshingText="'正在刷新...'"
+    :refreshSuccessText="'刷新成功'"
+    :loadingText="'加载中...'"
+    :errorText="'加载失败'"
+    :noMoreText="'没有更多数据了'"
+    @refresh="onRefresh"
+    @loadMore="onLoadMore"
+    @retry="onRetry"
+  >
+    <div class="list-container">
+      <div v-for="item in listData" :key="item.id" class="list-item">
+        {{ item.title }}
+      </div>
+    </div>
+  </PullRefresh>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const listData = ref([])
+const loading = ref(false)
+const refreshLoading = ref(false)
+const hasMore = ref(true)
+const error = ref(false)
+
+// 初始化数据
+const initData = () => {
+  for (let i = 1; i <= 10; i++) {
+    listData.value.push({ id: i, title: `列表项${i}` })
+  }
+}
+
+// 下拉刷新
+const onRefresh = async () => {
+  refreshLoading.value = true
+  // 模拟异步请求
+  await new Promise(resolve => setTimeout(resolve, 1500))
+  // 清空并重新加载数据
+  listData.value = []
+  for (let i = 1; i <= 10; i++) {
+    listData.value.push({ id: i, title: `刷新后的列表项${i}` })
+  }
+  hasMore.value = true
+  refreshLoading.value = false
+}
+
+// 加载更多
+const onLoadMore = async () => {
+  if (loading.value || !hasMore.value) return
+  loading.value = true
+  // 模拟异步请求
+  await new Promise(resolve => setTimeout(resolve, 1500))
+  // 添加新数据
+  const startIndex = listData.value.length + 1
+  for (let i = startIndex; i < startIndex + 10; i++) {
+    listData.value.push({ id: i, title: `列表项${i}` })
+  }
+  // 模拟数据加载完毕
+  if (listData.value.length >= 30) {
+    hasMore.value = false
+  }
+  loading.value = false
+}
+
+// 重试加载
+const onRetry = () => {
+  error.value = false
+  onLoadMore()
+}
+
+// 初始化
+initData()
+</script>
+
+<style scoped>
+.list-container {
+  padding: 16px;
+}
+
+.list-item {
+  padding: 12px;
+  margin-bottom: 8px;
+  background-color: #f5f5f5;
+  border-radius: 8px;
+}
+</style>
+```
+
+---
+
+## 📚 API 文档
+
+### 🔧 Props 属性
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `loading` | `Boolean` | `false` | 无限滚动加载状态 |
+| `refreshLoading` | `Boolean` | `false` | 下拉刷新加载状态 |
+| `hasMore` | `Boolean` | `true` | 是否还有更多数据 |
+| `error` | `Boolean` | `false` | 加载失败状态 |
+| `threshold` | `Number` | `30` | 触发无限滚动的阈值距离（像素） |
+| `refreshThreshold` | `Number` | `40` | 下拉刷新触发阈值（像素） |
+| `throttleTime` | `Number` | `200` | 节流时间（毫秒） |
+| `loadingText` | `String` | `'加载中...'` | 加载中提示文本 |
+| `errorText` | `String` | `'加载失败'` | 加载失败提示文本 |
+| `retryText` | `String` | `'点击重试'` | 重试按钮文本 |
+| `noMoreText` | `String` | `'没有更多数据了'` | 无更多数据提示文本 |
+| `refreshText` | `String` | `'下拉刷新'` | 下拉刷新提示文本 |
+| `releaseText` | `String` | `'释放可刷新'` | 释放可刷新提示文本 |
+| `refreshingText` | `String` | `'正在刷新...'` | 正在刷新提示文本 |
+| `refreshSuccessText` | `String` | `'刷新成功'` | 刷新成功提示文本 |
+| `refreshErrorText` | `String` | `'刷新失败'` | 刷新失败提示文本 |
+| `useWindowScroll` | `Boolean` | `false` | 是否使用窗口作为滚动容器 |
+| `enableInfiniteScroll` | `Boolean` | `false` | 是否启用无限滚动 |
+| `enableRefresh` | `Boolean` | `true` | 是否启用下拉刷新 |
+
+### 🎯 事件 Events
+
+| 事件名 | 回调参数 | 说明 |
+|--------|----------|------|
+| `refresh` | - | 下拉刷新触发时调用 |
+| `loadMore` | - | 滚动到底部触发加载更多时调用 |
+| `retry` | - | 点击加载失败重试按钮时调用 |
+
+---
+
+## 💡 使用示例
+
+### 🎨 自定义样式示例
+
+```vue
+<template>
+  <PullRefresh
+    v-model:loading="loading"
+    v-model:refreshLoading="refreshLoading"
+    :hasMore="hasMore"
+    :error="error"
+    refreshText="下拉刷新数据"
+    releaseText="释放立即刷新"
+    refreshingText="刷新中..."
+    refreshSuccessText="刷新成功！"
+    loadingText="加载中..."
+    noMoreText="没有更多了"
+    @refresh="handleRefresh"
+    @loadMore="handleLoadMore"
+  >
+    <view class="custom-list">
+      <view v-for="item in dataList" :key="item.id" class="custom-item">
+        <image :src="item.avatar" class="avatar" />
+        <view class="content">
+          <text class="title">{{ item.title }}</text>
+          <text class="desc">{{ item.description }}</text>
+        </view>
+      </view>
+    </view>
+  </PullRefresh>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const dataList = ref([])
+const loading = ref(false)
+const refreshLoading = ref(false)
+const hasMore = ref(true)
+const error = ref(false)
+
+const handleRefresh = async () => {
+  refreshLoading.value = true
+  try {
+    // 模拟API调用
+    const response = await fetch('/api/data?refresh=true')
+    const newData = await response.json()
+    dataList.value = newData
+    error.value = false
+  } catch (err) {
+    error.value = true
+  } finally {
+    refreshLoading.value = false
+  }
+}
+
+const handleLoadMore = async () => {
+  if (loading.value || !hasMore.value) return
+  
+  loading.value = true
+  try {
+    const response = await fetch(`/api/data?offset=${dataList.value.length}`)
+    const newData = await response.json()
+    dataList.value.push(...newData)
+    
+    if (newData.length < 10) {
+      hasMore.value = false
+    }
+    error.value = false
+  } catch (err) {
+    error.value = true
+  } finally {
+    loading.value = false
+  }
+}
+</script>
+
+<style scoped>
+.custom-list {
+  padding: 20rpx;
+}
+
+.custom-item {
+  display: flex;
+  align-items: center;
+  padding: 20rpx;
+  margin-bottom: 20rpx;
+  background: white;
+  border-radius: 16rpx;
+  box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.1);
+}
+
+.avatar {
+  width: 80rpx;
+  height: 80rpx;
+  border-radius: 50%;
+  margin-right: 20rpx;
+}
+
+.content {
+  flex: 1;
+}
+
+.title {
+  font-size: 32rpx;
+  font-weight: 600;
+  color: #333;
+  margin-bottom: 8rpx;
+}
+
+.desc {
+  font-size: 28rpx;
+  color: #666;
+  line-height: 1.4;
+}
+</style>
+```
+
+### 🔧 仅下拉刷新模式
+
+```vue
+<template>
+  <PullRefresh
+    :enableRefresh="true"
+    :enableInfiniteScroll="false"
+    :refreshLoading="refreshLoading"
+    @refresh="handleRefresh"
+  >
+    <view class="content">
+      <text>这里是静态内容，只需要下拉刷新</text>
+    </view>
+  </PullRefresh>
+</template>
+```
+
+### 🔧 仅无限滚动模式
+
+```vue
+<template>
+  <PullRefresh
+    :enableRefresh="false"
+    :enableInfiniteScroll="true"
+    :loading="loading"
+    :hasMore="hasMore"
+    :error="error"
+    @loadMore="handleLoadMore"
+    @retry="handleRetry"
+  >
+    <view class="feed-list">
+      <view v-for="item in feedList" :key="item.id" class="feed-item">
+        <text>{{ item.content }}</text>
+      </view>
+    </view>
+  </PullRefresh>
+</template>
+```
+
+---
+
+## 🎯 最佳实践
+
+### 📱 场景选择指南
+
+| 使用场景 | 推荐配置 | 说明 |
+|----------|----------|------|
+| **新闻列表** | `enableRefresh: true`, `enableInfiniteScroll: true` | 完整的内容刷新和加载体验 |
+| **聊天记录** | `enableRefresh: true`, `enableInfiniteScroll: false` | 只支持下拉刷新获取最新消息 |
+| **商品列表** | `enableRefresh: false`, `enableInfiniteScroll: true` | 只支持滚动加载更多商品 |
+| **静态内容** | `enableRefresh: true`, `enableRefresh: false` | 纯刷新功能 |
+
+### ⚡ 性能优化建议
+
+1. **合理设置阈值**
+   ```vue
+   <!-- 推荐：移动端合适的阈值 -->
+   <PullRefresh 
+     :refreshThreshold="60" 
+     :threshold="50" 
+   />
+   ```
+
+2. **节流时间优化**
+   ```vue
+   <!-- 推荐：根据内容复杂度调整节流时间 -->
+   <PullRefresh 
+     :throttleTime="100"
+     :enableInfiniteScroll="true" 
+   />
+   ```
+
+3. **懒加载内容**
+   ```vue
+   <!-- 推荐：使用v-if延迟渲染非可见内容 -->
+   <PullRefresh>
+     <div v-for="item in visibleItems" :key="item.id">
+       {{ item.content }}
+     </div>
+   </PullRefresh>
+   ```
+
+### 🛠️ 常见陷阱避免
+
+1. **状态管理**
+   ```vue
+   <!-- 错误：直接在事件中处理复杂逻辑 -->
+   @refresh="() => { loading = true; fetchData(); loading = false; }"
+   
+   <!-- 正确：使用async/await处理异步逻辑 -->
+   @refresh="handleRefresh"
+   ```
+
+2. **内存泄漏预防**
+   ```vue
+   <script setup lang="ts">
+   import { onUnmounted } from 'vue'
+   
+   onUnmounted(() => {
+     // 清理定时器、事件监听器等
+     clearTimeout(timer)
+   })
+   </script>
+   ```
+
+3. **iOS兼容处理**
+   ```vue
+   <!-- 推荐：处理iOS Safari的橡皮筋效果 -->
+   <template>
+     <PullRefresh
+       :useWindowScroll="false"
+       :enableRefresh="true"
+     >
+       <!-- 内容 -->
+     </PullRefresh>
+   </template>
+   ```
+
+---
+
+## ❓ 常见问题
+
+### 🔍 FAQ
+
+**Q: 如何禁用下拉刷新功能？**
+```vue
+<PullRefresh :enableRefresh="false" />
+```
+
+**Q: 如何自定义刷新动画？**
+```vue
+<!-- 通过CSS类名覆盖默认样式 -->
+<PullRefresh class="custom-refresh">
+  <!-- 内容 -->
+</PullRefresh>
+
+<style>
+.custom-refresh .refresh-animation {
+  /* 自定义动画样式 */
+}
+</style>
+```
+
+**Q: 在uni-app小程序中如何使用？**
+```vue
+<!-- 完全兼容，无需特殊配置 -->
+<PullRefresh
+  :loading="loading"
+  :hasMore="hasMore"
+  @loadMore="loadMore"
+>
+  <view class="list">
+    <view v-for="item in list" :key="item.id">
+      {{ item.title }}
+    </view>
+  </view>
+</PullRefresh>
+```
+
+**Q: 如何处理网络错误？**
+```vue
+<script setup>
+const handleRefresh = async () => {
+  try {
+    await fetchData()
+    error.value = false
+  } catch (err) {
+    error.value = true
+    uni.showToast({
+      title: '网络错误，请重试',
+      icon: 'error'
+    })
+  }
+}
+</script>
+```
+
+**Q: 滚动不触发加载更多？**
+- 检查容器高度是否足够（内容需要超过一屏）
+- 确认 `enableInfiniteScroll` 为 `true`
+- 检查 `hasMore` 状态是否正确
+
+### 🐛 问题排查
+
+1. **下拉刷新不生效**
+   - 检查触摸事件是否被其他元素阻止
+   - 确认容器高度和内容高度
+   - 检查阈值设置是否合理
+
+2. **无限滚动不触发**
+   - 确认滚动容器高度
+   - 检查 `hasMore` 和 `loading` 状态
+   - 验证阈值设置
+
+3. **动画效果异常**
+   - 检查CSS冲突
+   - 确认浏览器兼容性
+   - 验证transform属性使用
+
+---
+
+## 📄 更新日志
+
+### v1.0.0 (2024-01-01)
+- ✨ 初始版本发布
+- 🎯 支持下拉刷新和无限滚动
+- 🎨 丰富的状态显示和自定义文本
+- 📱 响应式设计适配
+- ⚡ 性能优化和节流处理
+- 🛠️ 完整的TypeScript类型支持
+
+---
+
+## 📄 许可证
+
+MIT License
+
+---
+
+<div align="center">
+
+**如果这个组件对您有帮助，请给个 ⭐ Star！**
+
+Made with ❤️ by Your Team
+
+</div>

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

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