UviewUltra 4.0

Appearance

PullRefresh 下拉刷新 4.4.0 ​

pull-refresh下拉刷新组件，支持自定义下拉刷新状态、结合虚拟列表和上拉加载等功能，适用于各种需要下拉刷新的场景。

平台差异说明 ​

|App（vue）|App（uvue/uni-app-x）|App（nvue）|H5|小程序| |:-😐:-😐:-😐:-😐:-😐:-😐 |√|x|√|√|

基本参数 ​

  • 通过 refreshing 控制刷新状态
  • 通过 threshold 设置触发刷新的阈值
  • 通过监听 refresh 事件处理刷新逻辑

用法示例 ​

1. 自定义下拉动画 ​

通过插槽可以自定义下拉过程中的不同状态：下拉状态、释放状态和刷新中状态

vue
<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>
js
<script setup>
import { ref } from 'vue';

const refreshing = ref(false);
const listData = ref([]);

const onRefresh = () => {
  refreshing.value = true;
  // 模拟网络请求
  setTimeout(() => {
    loadData();
    refreshing.value = false;
  }, 2000);
};

const loadData = () => {
  // 模拟加载数据
  listData.value = Array.from({ length: 20 }, (_, i) => ({
    id: i,
    name: `Item ${i}`
  }));
};
</script>

2. 结合虚拟列表 ​

与虚拟列表组件up-virtual-list结合使用，优化长列表性能

html
<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 setup>
import { ref } from 'vue';

const refreshing = ref(false);
const listData = ref([]);

const onRefresh = () => {
  refreshing.value = true;
  // 模拟网络请求
  setTimeout(() => {
    loadData();
    refreshing.value = false;
  }, 2000);
};

const onScroll = () => {};
</script>

3. 结合上拉加载 ​

通过 showLoadmore 和 loadmoreProps 属性开启上拉加载功能

html
<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>
js
<script setup>
import { ref } from 'vue';

const refreshing = ref(false);
const listData = ref([]);

const loadmoreConfig = ref({
  status: 'loadmore', // loadmore, loading, nomore
  loadmoreText: '上拉加载更多',
  loadingText: '努力加载中...',
  nomoreText: '我们是有底线的',
  iconSize: 18
});

const onRefresh = () => {
  refreshing.value = true;
  // 模拟网络请求
  setTimeout(() => {
    loadData();
    refreshing.value = false;
  }, 2000);
};

const onLoadmore = () => {};

const onScrollToLower = () => {
  loadmoreConfig.value.status = 'loading';
  setTimeout(() => {
    listData.value.push({
      id: listData.value.length,
      name: 'Item ' + listData.value.length
    });
    loadmoreConfig.value.status = 'loadmore';
  }, 2000);
};

const loadData = () => {
  // 模拟加载数据
  listData.value = Array.from({ length: 20 }, (_, i) => ({
    id: i,
    name: `Item ${i}`
  }));
};
</script>

自定义内容 ​

通过三个插槽可以完全自定义下拉刷新的各个状态：

html
<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>
js
<script setup>
import { ref } from 'vue';

const refreshing = ref(false);

const onRefresh = () => {
  refreshing.value = true;
  // 模拟网络请求
  setTimeout(() => {
    refreshing.value = false;
  }, 2000);
};
</script>

演示页面源代码地址 ​

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


 github  gitee

API ​

Props ​

参数说明类型默认值可选值
refreshing是否正在刷新Booleanfalsetrue/false
threshold下拉刷新阈值Number80
damping阻尼系数Number0.4
maxDistance最大下拉距离Number120
showLoadmore是否显示加载更多Booleanfalsetrue/false
loadmorePropsu-loadmore 组件的 props 配置Object

Events ​

事件名说明回调参数
refresh下拉刷新时触发-
loadmore上拉加载时触发-
scroll滚动时触发滚动事件对象

Slot ​

名称说明
pull下拉状态插槽，参数为
release释放状态插槽，参数为
refreshing刷新中状态插槽
default内容区域插槽