PullRefresh 下拉刷新

介绍

用于提供下拉刷新的交互操作。

引入

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

  1. import { createApp } from 'vue';
  2. import { PullRefresh } from 'vant';
  3. const app = createApp();
  4. app.use(PullRefresh);

代码演示

基础用法

下拉刷新时会触发 refresh 事件,在事件的回调函数中可以进行同步或异步操作,操作完成后将 v-model 设置为 false,表示加载完成。

  1. <van-pull-refresh v-model="loading" @refresh="onRefresh">
  2. <p>刷新次数: {{ count }}</p>
  3. </van-pull-refresh>
  1. import { ref } from 'vue';
  2. import { showToast } from 'vant';
  3. export default {
  4. setup() {
  5. const count = ref(0);
  6. const loading = ref(false);
  7. const onRefresh = () => {
  8. setTimeout(() => {
  9. showToast('刷新成功');
  10. loading.value = false;
  11. count.value++;
  12. }, 1000);
  13. };
  14. return {
  15. count,
  16. loading,
  17. onRefresh,
  18. };
  19. },
  20. };

成功提示

通过 success-text 可以设置刷新成功后的顶部提示文案。

  1. <van-pull-refresh
  2. v-model="isLoading"
  3. success-text="刷新成功"
  4. @refresh="onRefresh"
  5. >
  6. <p>刷新次数: {{ count }}</p>
  7. </van-pull-refresh>

自定义提示

通过插槽可以自定义下拉刷新过程中的提示内容。

  1. <van-pull-refresh v-model="isLoading" :head-height="80" @refresh="onRefresh">
  2. <!-- 下拉提示,通过 scale 实现一个缩放效果 -->
  3. <template #pulling="props">
  4. <img
  5. class="doge"
  6. src="https://fastly.jsdelivr.net/npm/@vant/assets/doge.png"
  7. :style="{ transform: `scale(${props.distance / 80})` }"
  8. />
  9. </template>
  10. <!-- 释放提示 -->
  11. <template #loosing>
  12. <img
  13. class="doge"
  14. src="https://fastly.jsdelivr.net/npm/@vant/assets/doge.png"
  15. />
  16. </template>
  17. <!-- 加载提示 -->
  18. <template #loading>
  19. <img
  20. class="doge"
  21. src="https://fastly.jsdelivr.net/npm/@vant/assets/doge-fire.jpeg"
  22. />
  23. </template>
  24. <p>刷新次数: {{ count }}</p>
  25. </van-pull-refresh>
  26. <style>
  27. .doge {
  28. width: 140px;
  29. height: 72px;
  30. margin-top: 8px;
  31. border-radius: 4px;
  32. }
  33. </style>

API

Props

参数说明类型默认值
v-model是否处于加载中状态boolean-
pulling-text下拉过程提示文案string下拉即可刷新…
loosing-text释放过程提示文案string释放即可刷新…
loading-text加载过程提示文案string加载中…
success-text刷新成功提示文案string-
success-duration刷新成功提示展示时长(ms)number | string500
animation-duration动画时长number | string300
head-height顶部内容高度number | string50
pull-distance v3.0.8触发下拉刷新的距离number | stringhead-height 一致
disabled是否禁用下拉刷新booleanfalse

Events

事件名说明回调参数
refresh下拉刷新时触发-
change v3.5.1拖动时或状态改变时触发{ status: string, distance: number }

Slots

名称说明参数
default自定义内容-
normal非下拉状态时顶部内容-
pulling下拉过程中顶部内容{ distance: number }
loosing释放过程中顶部内容{ distance: number }
loading加载过程中顶部内容{ distance: number }
success刷新成功提示内容-

类型定义

组件导出以下类型定义:

  1. import type { PullRefreshProps } from 'vant';

主题定制

样式变量

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

名称默认值描述
—van-pull-refresh-head-height50px-
—van-pull-refresh-head-font-sizevar(—van-font-size-md)-
—van-pull-refresh-head-text-colorvar(—van-text-color-2)-
—van-pull-refresh-loading-icon-size16px-

常见问题

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

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

  1. <van-pull-refresh style="min-height: 100vh;" />

PullRefresh 的触发条件是?

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

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

在桌面端无法操作组件?

参见桌面端适配

PullRefresh 下拉刷新 - 图1