uview-plus

# 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>

# 演示页面源代码地址

点击以下链接以查看演示页面的源码


 github  gitee

# 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 内容区域插槽

← VirtualList 虚拟列表 →