PullRefresh 下拉刷新

高阶全屏/区域下拉刷新与滚动触底加载组件，底层依托 UniApp 原生 <scroll-view> refresher 引擎，全量适配微信小程序、H5 及 App 端高帧率下拉回弹体验。

---

代码示例

1. 基础用法 (Basic Pull-to-Refresh)

使用 v-model:loading 或绑定 @refresh 事件处理下拉异步数据更新。

<template>
  <mu-pull-refresh
    v-model:loading="isRefreshing"
    height="100vh"
    success-text="数据更新成功"
    @refresh="onRefresh"
  >
    <view class="list">
      <view v-for="item in list" :key="item.id" class="item">
        {{ item.title }}
      </view>
    </view>
  </mu-pull-refresh>
</template>

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

const isRefreshing = ref(false)
const list = ref([{ id: 1, title: '数据项 1' }])

function onRefresh() {
  setTimeout(() => {
    list.value = [{ id: Date.now(), title: '最新下拉刷新数据' }]
    isRefreshing.value = false
  }, 1000)
}
</script>

---

2. 下拉刷新与触底加载结合 (Refresh & Loadmore)

配合 @loadmore 事件与 <mu-loadmore> 组件，轻松构建信息流分页加载列表。

<template>
  <mu-pull-refresh
    v-model:loading="isRefreshing"
    height="calc(100vh - 100rpx)"
    @refresh="onRefresh"
    @loadmore="onLoadMore"
  >
    <view class="list">
      <view v-for="item in list" :key="item.id" class="card">
        {{ item.title }}
      </view>

      <!-- 触底加载提示 -->
      <mu-loadmore :loading="isLoadingMore" :finished="isFinished" finished-text="已加载全部" />
    </view>
  </mu-pull-refresh>
</template>

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

const isRefreshing = ref(false)
const isLoadingMore = ref(false)
const isFinished = ref(false)
const list = ref([])

function onRefresh() {
  setTimeout(() => {
    list.value = [{ id: 1, title: '刷新获取项 1' }]
    isRefreshing.value = false
    isFinished.value = false
  }, 1000)
}

function onLoadMore() {
  if (isLoadingMore.value || isFinished.value) return
  isLoadingMore.value = true
  setTimeout(() => {
    list.value.push({ id: list.value.length + 1, title: `追加数据 #${list.value.length + 1}` })
    isLoadingMore.value = false
  }, 800)
}
</script>

---

3. Ref 编程式控制 (Ref Control)

通过 ref 获取组件实例，可以直接调用 startRefresh() 唤醒下拉刷新或 finishRefresh() 手动完成刷新。

<template>
  <view>
    <mu-button type="primary" size="small" @click="pullRef.startRefresh()">手动触发下拉刷新</mu-button>

    <mu-pull-refresh ref="pullRef" @refresh="onRefresh">
      <view>列表内容</view>
    </mu-pull-refresh>
  </view>
</template>

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

const pullRef = ref(null)

function onRefresh() {
  setTimeout(() => {
    pullRef.value.finishRefresh()
  }, 1000)
}
</script>

---

API 属性说明 (Props)

参数名	说明	类型	可选值	默认值
v-model:loading / loading	控制/获取下拉刷新状态	Boolean	true | false	false
height	组件容器高度	String	-	'100%'
disabled	是否禁用下拉刷新	Boolean	true | false	false
pullingText	下拉过程中的提示文案	String	-	'下拉即可刷新'
loosenText	下拉达到临界值释放时的提示文案	String	-	'释放立即刷新'
loadingText	正在刷新加载中的提示文案	String	-	'正在刷新中...'
successText	刷新完成后的 Toast 提示文案	String	-	'刷新成功'
successDuration	成功提示展示时长 (ms)	Number	-	1000
headHeight	顶部刷新指示器区域高度 (px)	Number	-	50
useNativeRefresher	是否强制使用原生 <scroll-view> refresher 刷新	Boolean	true | false	false
refresherDefaultStyle	原生下拉刷新图标样式	String	'black' | 'white' | 'none'	'black'
refresherBackground	原生下拉刷新区域背景色	String	-	'transparent'

---

事件说明 (Events)

事件名	说明	回调参数
refresh	触发下拉刷新时调用	-
loadmore	滚动条触底（到达底部）时触发	(event: Event)
scroll	滚动过程中实时触发	(event: Event)
update:loading	v-model:loading 更新回调	(value: Boolean)

---

插槽说明 (Slots)

插槽名	说明
default	可滚动列表内容区域插槽

---

实例方法 (Expose Methods)

获取组件 ref 实例后可调用：

方法名	说明	参数
startRefresh()	编程式主动唤醒下拉刷新	-
finishRefresh(showToast)	完成刷新并收起刷框	showToast: Boolean (默认 true)