# uni.startPullDownRefresh(options?)

开始下拉刷新

# startPullDownRefresh 兼容性 ?

Web 微信小程序 支付宝小程序 Android iOS HarmonyOS
4.0 4.41 5.31 3.91 4.11 4.61

# 参数

名称 类型 必填
options StartPullDownRefreshOptions 否
名称 类型 必备 描述
success (result: StartPullDownRefreshSuccess) => void 否 接口调用成功的回调函数
fail (result: StartPullDownRefreshFail) => void 否 接口调用失败的回调函数
complete (result: any) => void 否 接口调用结束的回调函数(调用成功、失败都会执行)

# StartPullDownRefreshSuccess 的属性值

名称 类型 必备
errMsg string 是

# StartPullDownRefreshFail 的属性值

名称 类型 必备 描述
errCode number 是 下拉刷新错误码
- 4: 框架内部异常
errSubject string 是 统一错误主题(模块)名称
data any 否 错误信息中包含的数据
cause Error 否 源错误信息,可以包含多个错误,详见SourceError
errMsg string 是

# 返回值

类型 必备
Promise<StartPullDownRefreshSuccess> 否
名称 类型 必备
errMsg string 是

# 参见

# uni.stopPullDownRefresh()

停止当前页面下拉刷新

# stopPullDownRefresh 兼容性 ?

Web 微信小程序 支付宝小程序 Android iOS HarmonyOS
4.0 4.41 5.31 3.91 4.11 4.61

使用:

  1. 首先pages.json里配置了页面可下拉刷新"enablePullDownRefresh": true
  2. 当用户下拉页面时触发页面生命周期onPullDownRefresh,iOS平台触发时机:当下拉到一定阀值就会触发onPullDownRefresh,并不是当手势拖拽结束时触发
  3. 在合适的时机(如联网刷新数据结束),调用本APIuni.stopPullDownRefresh(),结束下拉刷新状态

本API仅负责页面下拉刷新。如使用组件下拉刷新,另见scroll-view、list-view等组件的文档。

# 参见

# 示例

示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验(手机浏览器跳转到App直达页)

示例

<template>
    <!-- 实际开发中,长列表应该使用list-view -->
    <view class="refresh-page uni-padding-wrap uni-common-mt">
      <view class="uni-btn-v">
        <button id="btn-pull-down-refresh-after-hide-loading" type="primary"
          @click="startPullDownRefreshAfterHideLoading">隐藏 loading 后开始并停止下拉刷新</button>
      </view>
      <text class="text" v-for="(num,index) in listData" :key="index">list - {{num}}</text>
      <view v-if="showLoadMore" class="load-more-text">{{loadMoreText}}</view>
    </view>
</template>
<script setup lang="ts">


  type DataType = {
    pulldownRefreshTriggered: boolean,
    startPullDownRefreshStaus: boolean,
    showLoadingSuccess: boolean,
    hideLoadingSuccess: boolean,
    stopPullDownRefreshCalled: boolean,
    loadingAndPullDownRefreshEvents: string[]
  }

  const listData = ref([] as Array<number>)
  const loadMoreText = ref("加载中...")
  const showLoadMore = ref(false)
  const max = ref(0)
  const data = reactive({
    pulldownRefreshTriggered: false,
    startPullDownRefreshStaus: false,
    showLoadingSuccess: false,
    hideLoadingSuccess: false,
    stopPullDownRefreshCalled: false,
    loadingAndPullDownRefreshEvents: [] as Array<string>
  } as DataType)
  let isLoadingBeforeStopPullDownRefresh = false

  function initData() {
    setTimeout(() => {
      max.value = 0;
      listData.value = [];
      let dataArr : Array<number> = [];
      max.value += 20;
      for (let i : number = max.value - 19; i < max.value + 1; i++) {
        dataArr.push(i)
      }
      listData.value = listData.value.concat(dataArr);
      uni.stopPullDownRefresh();
    }, 1000);
  }

  function setListData() {
    let dataArr : Array<number> = [];
    max.value += 10;
    for (let i : number = max.value - 9; i < max.value + 1; i++) {
      dataArr.push(i)
    }
    listData.value = listData.value.concat(dataArr);
  }

  function startPullDownRefreshAfterHideLoading() {
    isLoadingBeforeStopPullDownRefresh = true
    data.pulldownRefreshTriggered = false
    data.startPullDownRefreshStaus = false
    data.showLoadingSuccess = false
    data.hideLoadingSuccess = false
    data.stopPullDownRefreshCalled = false
    data.loadingAndPullDownRefreshEvents = []

    data.loadingAndPullDownRefreshEvents.push('showLoading')
    uni.showLoading({
      title: '加载中...',
      success() {
        data.showLoadingSuccess = true
      }
    })
    setTimeout(() => {
      data.loadingAndPullDownRefreshEvents.push('hideLoading')
      uni.hideLoading({
        success() {
          data.hideLoadingSuccess = true
        },
        complete() {
          data.loadingAndPullDownRefreshEvents.push('startPullDownRefresh')
          uni.startPullDownRefresh({
            success() {
              data.startPullDownRefreshStaus = true
              setTimeout(() => {
                data.loadingAndPullDownRefreshEvents.push('stopPullDownRefresh')
                uni.stopPullDownRefresh()
                data.stopPullDownRefreshCalled = true
                isLoadingBeforeStopPullDownRefresh = false
              }, 1000)
            },
            fail() {
              data.startPullDownRefreshStaus = false
              isLoadingBeforeStopPullDownRefresh = false
            }
          })
        }
      })
    }, 1000)
  }

  onReady(() => {
    let status = false
    uni.startPullDownRefresh({
      success() {
        status = true
      },
      fail() {
        status = false
      },
      complete: () => {
        data.startPullDownRefreshStaus = status
      }
    });
    initData();
  })

  onReachBottom(() => {
    console.log("onReachBottom");
    if (max.value > 40) {
      loadMoreText.value = "没有更多数据了!"
      return;
    }
    showLoadMore.value = true;
    setTimeout(() => {
      setListData();
    }, 300);
  })

  onPullDownRefresh(() => {
    console.log('onPullDownRefresh');
    data.pulldownRefreshTriggered = true
    if (!isLoadingBeforeStopPullDownRefresh) {
      initData();
    }
  })

  defineExpose({
    data,
    startPullDownRefreshAfterHideLoading
  })
</script>

<style>
  .text {
    margin: 6px 0;
    width: 100%;
    background-color: var(--list-background-color, #ffffff);
    height: 52px;
    line-height: 52px;
    text-align: center;
    color: var(--text-color, #555555);
    border-radius: 4px;
  }

  .load-more-text {
    color: var(--text-color, #333333);
  }
</style>

# 通用类型

# GeneralCallbackResult

名称 类型 必备 描述
errMsg string 是 错误信息

# Tips

  • 本API默认处理栈顶页面,而不是代码所在页面。详见
  • iOS 平台蒸汽模式开启下拉刷新会触发页面 onPageScroll 生命周期,此时 scrollTop 为负值。