# PullRefresh 下拉刷新
3.4.68
pull-refresh下拉刷新组件,支持自定义下拉刷新状态、结合虚拟列表和上拉加载等功能,适用于各种需要下拉刷新的场景。
# 平台差异说明
App(vue) | App(nvue) | H5 | 小程序 |
---|---|---|---|
√ | x | √ | √ |
# 基本参数
- 通过
refreshing
控制刷新状态 - 通过
threshold
设置触发刷新的阈值 - 通过监听
refresh
事件处理刷新逻辑
# 用法示例
# 1. 自定义下拉动画
通过插槽可以自定义下拉过程中的不同状态:下拉状态、释放状态和刷新中状态
<template>
<up-pull-refresh
:refreshing="refreshing"
:threshold="60"
@refresh="onRefresh"
>
<!-- 自定义下拉状态 -->
<template #pull="{ distance, threshold }">
<view class="custom-refresh-content">
<view class="pull-animation">
<text>👇</text>
</view>
<text class="refresh-text">下拉刷新 ({{ Math.round(distance) }}px)</text>
</view>
</template>
<!-- 自定义释放状态 -->
<template #release="{ distance, threshold }">
<view class="custom-refresh-content">
<view class="release-animation">
<text>👆</text>
</view>
<text class="refresh-text">释放刷新</text>
</view>
</template>
<!-- 自定义刷新中状态 -->
<template #refreshing>
<view class="custom-refresh-content" style="background-color: gray;">
<view class="refreshing-animation">
<up-icon size="100px" name="https://s3.bmp.ovh/imgs/2025/07/25/772bb6ae58cbd2c1.gif"></up-icon>
</view>
</view>
</template>
<!-- 列表内容 -->
<view class="list-content">
<view
v-for="item in listData"
:key="item.id"
class="list-item"
>
<text>{{ item.name }}</text>
</view>
</view>
</up-pull-refresh>
</template>
<script>
export default {
data() {
return {
refreshing: false,
listData: []
};
},
methods: {
onRefresh() {
this.refreshing = true
// 模拟网络请求
setTimeout(() => {
this.loadData()
this.refreshing = false
}, 2000)
}
}
};
</script>
# 2. 结合虚拟列表
与虚拟列表组件up-virtual-list结合使用,优化长列表性能
<template>
<up-pull-refresh
:refreshing="refreshing"
@refresh="onRefresh"
>
<up-virtual-list
:list-data="listData"
:item-height="32"
height="150px"
@scroll="onScroll"
>
<template #default="{ item, index }">
<view class="list-item">
<text>Item {{ item.id }}: {{ item.name }}</text>
</view>
</template>
</up-virtual-list>
</up-pull-refresh>
</template>
<script>
export default {
data() {
return {
refreshing: false,
listData: []
};
},
methods: {
onRefresh() {
this.refreshing = true
// 模拟网络请求
setTimeout(() => {
this.loadData()
this.refreshing = false
}, 2000)
},
onScroll() {}
}
};
</script>
# 3. 结合上拉加载
通过 showLoadmore
和 loadmoreProps
属性开启上拉加载功能
<template>
<up-pull-refresh
:refreshing="refreshing"
:showLoadmore="true"
:loadmoreProps="loadmoreConfig"
@refresh="onRefresh"
@loadmore="onLoadmore"
>
<!-- 使用外部 scroll-view 或其他可滚动组件 -->
<scroll-view
class="scroll-area"
style="height: 100px;"
:scroll-y="true"
@scrolltolower="onScrollToLower"
>
<view class="list-content">
<view
v-for="item in listData"
:key="item.id"
class="list-item"
>
<text>{{ item.name }}</text>
</view>
</view>
</scroll-view>
</up-pull-refresh>
</template>
<script>
export default {
data() {
return {
refreshing: false,
loadmoreConfig: {
status: 'loadmore', // loadmore, loading, nomore
loadmoreText: '上拉加载更多',
loadingText: '努力加载中...',
nomoreText: '我们是有底线的',
iconSize: 18
},
listData: []
};
},
methods: {
onRefresh() {
this.refreshing = true
// 模拟网络请求
setTimeout(() => {
this.loadData()
this.refreshing = false
}, 2000)
},
onScrollToLower() {
this.loadmoreConfig.status = 'loading'
setTimeout(() => {
this.listData.push({
id: this.listData.length,
name: 'Item ' + this.listData.length
})
this.loadmoreConfig.status = 'loadmore'
}, 2000)
}
}
};
</script>
# 自定义内容
通过三个插槽可以完全自定义下拉刷新的各个状态:
<template>
<up-pull-refresh
:refreshing="refreshing"
@refresh="onRefresh"
>
<!-- 下拉状态 -->
<template #pull="{ distance, threshold }">
<view>下拉状态,当前下拉距离: {{ distance }}</view>
</template>
<!-- 释放状态 -->
<template #release="{ distance, threshold }">
<view>释放状态,达到阈值: {{ threshold }}</view>
</template>
<!-- 刷新中状态 -->
<template #refreshing>
<view>正在刷新中...</view>
</template>
<!-- 内容区域 -->
<view>内容区域</view>
</up-pull-refresh>
</template>
# 演示页面源代码地址
# API
# Props
参数 | 说明 | 类型 | 默认值 | 可选值 |
---|---|---|---|---|
refreshing | 是否正在刷新 | Boolean | false | true/false |
threshold | 下拉刷新阈值 | Number | 80 | |
damping | 阻尼系数 | Number | 0.4 | |
maxDistance | 最大下拉距离 | Number | 120 | |
showLoadmore | 是否显示加载更多 | Boolean | false | true/false |
loadmoreProps | u-loadmore 组件的 props 配置 | Object | { status: 'loadmore', loadmoreText: '加载更多', loadingText: '正在加载...', nomoreText: '没有更多了' } |
# Events
事件名 | 说明 | 回调参数 |
---|---|---|
refresh | 下拉刷新时触发 | - |
loadmore | 上拉加载时触发 | - |
scroll | 滚动时触发 | 滚动事件对象 |
# Slot
名称 | 说明 |
---|---|
pull | 下拉状态插槽,参数为 { distance, threshold } |
release | 释放状态插槽,参数为 { distance, threshold } |
refreshing | 刷新中状态插槽 |
default | 内容区域插槽 |