更新记录

1.0.0（2025-10-31）

平台兼容性

uni-app(3.6.12)

其他

fgi-refresh 优雅的下拉刷新插件

一个优雅的 UniApp 下拉刷新插件，提供流畅的动画效果和简洁的 API
只需一行代码，即可为您的页面添加专业的下拉刷新功能！

✨ 特性

• 🎨 精美动画 - 流畅的旋转脉冲动画，位于页面中间
• 🚀 极简使用 - 一行代码启用下拉刷新，告别繁琐配置
• 🔄 自动管理 - 自动显示/隐藏动画，无需手动控制
• 💪 统一管理 - 所有页面使用相同逻辑，易于维护
• 🎯 智能处理 - 自动停止刷新，内置错误处理
• 🌈 高度可定制 - 支持自定义 Logo、回调等
• 📱 全平台支持 - App(iOS/Android)、H5、各平台小程序
• ⚡️ Vue3 组合式API - 基于 Composition API，性能优异
• 🌓 暗黑模式 - 自动适配系统暗黑模式
• 📦 零依赖 - 不依赖任何第三方库

📦 安装

方式一：通过 DCloud 插件市场（推荐）

1. 打开 [插件详情页]()
2. 点击「使用 HBuilderX 导入插件」
3. 在 HBuilderX 中确认导入

方式二：手动导入

1. 下载插件包
2. 解压到项目的 uni_modules 目录
3. 重启 HBuilderX（如需要）

🚀 快速开始

1. 配置 pages.json

在需要下拉刷新的页面配置中启用：

{
  "path": "pages/home/index",
  "style": {
    "navigationBarTitleText": "首页",
    "enablePullDownRefresh": true
  }
}

2. 在页面中使用

只需 3 行代码！

<template>
  <view class="page">
    <!-- 1. 添加组件 -->
    <fgi-refresh ref="customRefreshRef" :isRefreshing="isRefreshing" />

    <!-- 你的页面内容 -->
  </view>
</template>

<script setup>
import { useRefresh } from '@/uni_modules/fgi-refresh/composables/useRefresh'

// 2. 使用 composable
const { customRefreshRef, isRefreshing } = useRefresh(async () => {
  // 3. 在这里加载数据
  await loadData()
})

const loadData = async () => {
  // 你的数据加载逻辑
  const res = await uni.request({ url: '...' })
  // ...
}
</script>

就这么简单！✅ 下拉刷新已经配置完成。

📖 详细使用

基础示例

<template>
  <view class="page">
    <fgi-refresh ref="customRefreshRef" :isRefreshing="isRefreshing" />

    <view v-for="item in list" :key="item.id">
      {{ item.name }}
    </view>
  </view>
</template>

<script setup>
import { ref } from 'vue'
import { useRefresh } from '@/uni_modules/fgi-refresh/composables/useRefresh'

const list = ref([])

const { customRefreshRef, isRefreshing } = useRefresh(async () => {
  const res = await uni.request({
    url: 'https://api.example.com/data'
  })
  list.value = res.data.list
})
</script>

多个数据源

<script setup>
import { useRefresh } from '@/uni_modules/fgi-refresh/composables/useRefresh'

const { customRefreshRef, isRefreshing } = useRefresh(async () => {
  // 依次加载多个数据源
  await loadBanners()
  await loadProducts()
  await loadRecommends()
})
</script>

重置分页数据

<script setup>
import { ref } from 'vue'
import { useRefresh } from '@/uni_modules/fgi-refresh/composables/useRefresh'

const list = ref([])
const pageNum = ref(1)

const { customRefreshRef, isRefreshing } = useRefresh(async () => {
  // 重置分页
  pageNum.value = 1
  list.value = []

  // 加载第一页数据
  await loadList()
})
</script>

错误处理

<script setup>
import { useRefresh } from '@/uni_modules/fgi-refresh/composables/useRefresh'

const { customRefreshRef, isRefreshing } = useRefresh(
  async () => {
    await loadData()
  },
  {
    // 显示加载失败提示
    showToast: true,

    // 成功回调
    onSuccess: () => {
      console.log('刷新成功')
    },

    // 失败回调
    onError: (error) => {
      console.error('刷新失败', error)
      uni.showToast({
        title: '刷新失败，请重试',
        icon: 'none'
      })
    }
  }
)
</script>

手动触发刷新

<template>
  <view class="page">
    <fgi-refresh ref="customRefreshRef" :isRefreshing="isRefreshing" />

    <button @click="handleRefresh">手动刷新</button>
  </view>
</template>

<script setup>
import { useRefresh } from '@/uni_modules/fgi-refresh/composables/useRefresh'

const { customRefreshRef, isRefreshing, refresh } = useRefresh(async () => {
  await loadData()
})

// 手动触发刷新
const handleRefresh = async () => {
  await refresh()
}
</script>

自定义 Logo

<template>
  <fgi-refresh 
    ref="customRefreshRef" 
    :isRefreshing="isRefreshing"
    logoUrl="https://your-domain.com/custom-logo.png"
  />
</template>

支持：

• 🌐 网络图片：https://...
• 📁 本地图片：/static/logo.png
• 📝 Base64：data:image/png;base64,...

🔧 API 文档

useRefresh(loadDataFn, options)

参数

options 配置

返回值

fgi-refresh 组件 Props

💡 最佳实践

1. 数据加载函数要独立

✅ 推荐

const loadData = async () => {
  // 数据加载逻辑
}

const { customRefreshRef, isRefreshing } = useRefresh(loadData)

❌ 不推荐

const { customRefreshRef, isRefreshing } = useRefresh(async () => {
  // 大量内联代码...
})

2. 并行加载独立数据

const { customRefreshRef, isRefreshing } = useRefresh(async () => {
  // 并行加载
  await Promise.all([
    loadBanners(),
    loadProducts(),
    loadRecommends()
  ])
})

3. 避免频繁刷新

插件已内置防重复刷新机制，但仍建议合理设置刷新时机。

⚠️ 注意事项

1. 必须在模板中添加组件

<fgi-refresh ref="customRefreshRef" :isRefreshing="isRefreshing" />

2. 不要再手动写 onPullDownRefresh

❌ 错误

onPullDownRefresh(() => {
  // ...
})

✅ 正确 - useRefresh 已经处理了

const { customRefreshRef, isRefreshing } = useRefresh(async () => {
  await loadData()
})

3. 确保 pages.json 中启用了下拉刷新

{
  "enablePullDownRefresh": true
}

4. 加载函数必须返回 Promise

✅ 正确

useRefresh(async () => {
  await loadData()
})

❌ 错误

useRefresh(() => {
  loadData() // 没有 await
})

🌍 平台兼容性

🐛 常见问题

📊 性能优化

• ✅ 动画使用 CSS3 transform，性能优异
• ✅ 防抖机制，避免重复刷新
• ✅ 自动资源清理，无内存泄漏
• ✅ 支持暗黑模式，自动适配
• ✅ 零依赖，包体积小

📝 更新日志

1.0.0 (2024-01-01)

• 🎉 首次发布
• ✨ 支持自定义动画
• ✨ 统一管理下拉刷新
• ✨ 自动化处理
• ✨ 全平台支持

查看完整更新日志

💖 支持

如果这个插件对您有帮助，欢迎：

• ⭐ Star 收藏
• 🐛 提交 Issue
• 💡 提交 PR
• 📢 分享给朋友
• ☕ 请作者喝咖啡

📄 License

MIT License

Copyright (c) 2024 MichaelNengQiang

👨💻 作者

MichaelNengQiang

• 📧 邮箱: ***@qq.com
• 🐙 GitHub: @silence3838438
• 💬 ***

🙏 鸣谢

感谢所有使用和支持这个插件的开发者！

Made with ❤️ by MichaelNengQiang