PullRefresh 下拉刷新 - Vant 4

🔄 PullRefresh 下拉刷新

🎯 介绍

PullRefresh 组件用于提供下拉刷新交互，支持刷新回调、成功提示等能力，常用于列表场景的增量数据获取。通过简单的下拉手势，用户可以轻松刷新页面内容，获取最新数据，提升用户体验。

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from 'vue';
import { PullRefresh } from 'vant';

const app = createApp();
app.use(PullRefresh);

🎯 代码演示

🔧 基础用法

下拉刷新时会触发 refresh 事件，在事件的回调函数中可以进行同步或异步操作，操作完成后将 v-model 设置为 false，表示加载完成。这是最常见的使用场景，适用于列表数据的刷新更新。

html

<template>
  <van-pull-refresh v-model="loading" @refresh="onRefresh">
    <div class="content">
      <p>刷新次数: {{ count }}</p>
      <p>下拉试试看 👆</p>
    </div>
  </van-pull-refresh>
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const count = ref(0);
const loading = ref(false);

const onRefresh = () => {
  setTimeout(() => {
    showToast('刷新成功');
    loading.value = false;
    count.value++;
  }, 1000);
};
</script>

<style>
.content {
  padding: 20px;
  text-align: center;
  background: #f7f8fa;
  min-height: 200px;
}
</style>

✅ 成功提示

通过 success-text 可以设置刷新成功后的顶部提示文案。这个功能可以给用户明确的反馈，让用户知道刷新操作已经成功完成。

html

<template>
  <van-pull-refresh 
    v-model="loading" 
    success-text="刷新成功 ✨"
    @refresh="onRefresh"
  >
    <div class="content">
      <p>带成功提示的下拉刷新</p>
      <p>刷新后会显示成功提示</p>
    </div>
  </van-pull-refresh>
</template>

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

const loading = ref(false);

const onRefresh = () => {
  setTimeout(() => {
    loading.value = false;
  }, 1000);
};
</script>

🎨 自定义提示

通过插槽可以自定义下拉刷新过程中的提示内容。这个功能让你可以完全自定义刷新过程中的视觉效果，打造独特的用户体验。

html

<template>
  <van-pull-refresh v-model="loading" @refresh="onRefresh">
    <template #pulling="{ distance }">
      <div class="custom-pulling">
        <van-icon name="arrow-down" />
        <span>下拉距离: {{ distance }}px</span>
      </div>
    </template>
    
    <template #loosing>
      <div class="custom-loosing">
        <van-icon name="success" color="#07c160" />
        <span>释放即可刷新</span>
      </div>
    </template>
    
    <template #loading>
      <div class="custom-loading">
        <van-loading size="16" />
        <span>正在刷新数据...</span>
      </div>
    </template>
    
    <div class="content">
      <p>自定义提示内容</p>
      <p>每个状态都有不同的提示</p>
    </div>
  </van-pull-refresh>
</template>

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

const loading = ref(false);

const onRefresh = () => {
  setTimeout(() => {
    loading.value = false;
  }, 2000);
};
</script>

<style>
.custom-pulling,
.custom-loosing,
.custom-loading {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 50px;
  font-size: 14px;
  color: #969799;
}

.custom-pulling span,
.custom-loosing span,
.custom-loading span {
  margin-left: 8px;
}
</style>

🎛️ 自定义配置

可以通过各种属性来自定义下拉刷新的行为和外观，包括触发距离、动画时长、头部高度等。

html

<template>
  <van-pull-refresh 
    v-model="loading"
    pulling-text="用力下拉 💪"
    loosing-text="快松手吧 🚀"
    loading-text="拼命加载中 ⚡"
    success-text="搞定啦 🎉"
    :success-duration="2000"
    :animation-duration="500"
    :head-height="80"
    :pull-distance="100"
    @refresh="onRefresh"
  >
    <div class="content">
      <p>自定义配置的下拉刷新</p>
      <p>更高的头部，更长的触发距离</p>
      <p>个性化的提示文案</p>
    </div>
  </van-pull-refresh>
</template>

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

const loading = ref(false);

const onRefresh = () => {
  setTimeout(() => {
    loading.value = false;
  }, 1500);
};
</script>

📋 API

🎛️ Props

参数	说明	类型	默认值
v-model	是否处于加载中状态，控制刷新动画的显示 🔄	boolean	-
pulling-text	下拉过程提示文案，引导用户继续下拉 👇	string	`下拉即可刷新...`
loosing-text	释放过程提示文案，提示用户可以松手刷新 🚀	string	`释放即可刷新...`
loading-text	加载过程提示文案，显示数据加载状态 ⏳	string	`加载中...`
success-text	刷新成功提示文案，给用户成功反馈 ✅	string	-
success-duration	刷新成功提示展示时长(ms)，控制成功提示的显示时间 ⏰	number \| string	`500`
animation-duration	动画时长，控制下拉刷新动画的流畅度 🎬	number \| string	`300`
head-height	顶部内容高度，设置刷新区域的高度 📏	number \| string	`50`
pull-distance	触发下拉刷新的距离，控制触发刷新的敏感度 📐	number \| string	与 `head-height` 一致
disabled	是否禁用下拉刷新，可用于特定场景下禁止刷新 🚫	boolean	`false`

🎪 Events

事件名	说明	回调参数
refresh	下拉刷新时触发，执行数据刷新逻辑 🔄	-
change	拖动时或状态改变时触发，监听刷新状态变化 📊	{ status: string, distance: number }

🎭 Slots

名称	说明	参数
default	自定义内容，放置需要刷新的主要内容 📄	-
normal	非下拉状态时顶部内容，默认状态的提示区域 😌	-
pulling	下拉过程中顶部内容，用户下拉时的动态提示 👇	{ distance: number }
loosing	释放过程中顶部内容，即将触发刷新时的提示 🚀	{ distance: number }
loading	加载过程中顶部内容，数据加载时的状态显示 ⏳	{ distance: number }
success	刷新成功提示内容，成功完成刷新后的反馈 ✨	-

📝 类型定义

组件导出以下类型定义：

import type { PullRefreshProps } from 'vant';

🎨 主题定制

🎭 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-pull-refresh-head-height	50px	刷新头部高度，控制下拉区域的视觉空间 📏
--van-pull-refresh-head-font-size	var(--van-font-size-md)	头部文字大小，影响提示文案的可读性 📝
--van-pull-refresh-head-text-color	var(--van-text-color-2)	头部文字颜色，设置提示文案的显示色彩 🎨
--van-pull-refresh-loading-icon-size	16px	加载图标大小，控制加载动画的视觉尺寸 ⚙️

❓ 常见问题

PullRefresh 的内容未填满屏幕时，只有一部分区域可以下拉？

默认情况下，下拉区域的高度是和内容高度保持一致的，如果需要让下拉区域始终为全屏，可以给 PullRefresh 设置一个与屏幕大小相等的最小高度：

html

<van-pull-refresh style="min-height: 100vh;">
  <!-- 内容 -->
</van-pull-refresh>

PullRefresh 的触发条件是？

PullRefresh 的触发条件是「父级滚动元素的滚动条在顶部位置」。

如果最近一个可滚动的父级元素是 window，则要求 window.pageYOffset === 0。
如果最近一个可滚动的父级元素是 Element，则要求 Element.scrollTop === 0。

在桌面端无法操作组件？

参见桌面端适配。

📚 相关文档

🔗 相关组件

List 列表 - 列表组件，常与下拉刷新配合使用展示数据 📋
Search 搜索 - 搜索组件，搜索结果页面的刷新更新 🔍
Toast 轻提示 - 轻量级提示，用于刷新成功的用户反馈 🍞
Loading 加载 - 加载状态指示器，展示数据加载过程 ⏳
Swipe 轮播 - 轮播组件，支持手势操作的内容展示 📱
Grid 宫格 - 宫格布局，网格内容的批量刷新 🔲

🔄 PullRefresh 下拉刷新 ​

🎯 介绍 ​

📦 引入 ​

🎯 代码演示 ​

🔧 基础用法 ​

✅ 成功提示 ​

🎨 自定义提示 ​

🎛️ 自定义配置 ​

📋 API ​

🎛️ Props ​

🎪 Events ​

🎭 Slots ​

📝 类型定义 ​

🎨 主题定制 ​

🎭 样式变量 ​

❓ 常见问题 ​

PullRefresh 的内容未填满屏幕时，只有一部分区域可以下拉？ ​

PullRefresh 的触发条件是？ ​

在桌面端无法操作组件？ ​

📚 相关文档 ​

🔗 相关组件 ​

🔄 PullRefresh 下拉刷新

🎯 介绍

📦 引入

🎯 代码演示

🔧 基础用法

✅ 成功提示

🎨 自定义提示

🎛️ 自定义配置

📋 API

🎛️ Props

🎪 Events

🎭 Slots

📝 类型定义

🎨 主题定制

🎭 样式变量

❓ 常见问题

PullRefresh 的内容未填满屏幕时，只有一部分区域可以下拉？

PullRefresh 的触发条件是？

在桌面端无法操作组件？

📚 相关文档

🔗 相关组件