下拉刷新组件

refresh 组件是 App 端 nvue 页面中实现下拉刷新功能的核心组件。它为 scroll-view、list、waterfall 等容器提供灵活、高性能的下拉刷新能力。开发者可以自定义下拉刷新的样式和内容，通过简单的事件绑定实现与后端数据的同步。

1. 什么是 refresh 组件？

refresh 组件用于在 scroll-view、list、waterfall 等滚动容器中实现下拉刷新效果。通过监听下拉动作，触发刷新事件，并在刷新完成后更新页面内容。refresh 可以灵活定义下拉显示的内容，并支持结合 loading-indicator 组件展示动画效果。

使用场景

• 数据同步：在页面下拉时触发刷新，通常用于从服务器获取最新数据并更新页面。
• 内容更新提示：结合 loading-indicator 展示加载状态，给用户明确的操作反馈。

2. refresh 组件的常用属性

refresh 组件提供了一个主要的属性用于控制显示状态，开发者可以通过修改此属性来控制下拉刷新的显示和隐藏。

属性名	类型	默认值	说明
display	String	show	控制 <refresh> 组件的显示与隐藏。值为 show 时显示，值为 hide 时隐藏。必须成对使用，即 show 后必须有相应的 hide。

2.1 控制 refresh 组件显示与隐藏

• 说明：通过 display 属性控制 refresh 组件的显示和隐藏状态。用于在数据刷新完成后隐藏刷新组件。
• 类型：String
• 默认值：show

<template>
  <scroll-view>
    <!-- 定义下拉刷新组件 -->
    <refresh :display="isRefreshing ? 'show' : 'hide'" @refresh="onRefresh">
      <text>Refreshing...</text>
      <loading-indicator></loading-indicator>
    </refresh>
    
    <!-- 列表内容 -->
    <view v-for="(item, index) in lists" :key="index">
      <text>{{ item }}</text>
    </view>
  </scroll-view>
</template>

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

// 模拟列表数据
const lists = ref(['A', 'B', 'C', 'D', 'E'])
const isRefreshing = ref(false)

// 模拟刷新操作
const onRefresh = () => {
  setTimeout(() => {
    // 更新数据
    lists.value.push('F', 'G', 'H')
    isRefreshing.value = false
  }, 1000)
}
</script>

3. 事件

refresh 组件提供了两个主要事件，分别用于监听下拉动作和下拉完成时触发的刷新操作。

事件名	说明	返回参数
refresh	当容器被下拉完成时触发。通常用于触发实际的数据刷新逻辑。	无
pullingdown	当容器正在下拉时触发。可以从事件参数中获取当前下拉的距离等数据，用于自定义下拉效果。	dy, pullingDistance, viewHeight, type

3.1 监听 refresh 事件

• 说明：refresh 事件用于在用户完成下拉操作时触发数据刷新。在刷新完成后，可以通过隐藏 refresh 组件来恢复页面状态。

<template>
  <scroll-view>
    <!-- 下拉刷新组件，监听 refresh 事件 -->
    <refresh :display="isRefreshing ? 'show' : 'hide'" @refresh="onRefresh">
      <text>Refreshing...</text>
      <loading-indicator></loading-indicator>
    </refresh>

    <!-- 列表内容 -->
    <view v-for="(item, index) in lists" :key="index">
      <text>{{ item }}</text>
    </view>
  </scroll-view>
</template>

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

// 模拟列表数据
const lists = ref(['A', 'B', 'C', 'D', 'E'])
const isRefreshing = ref(false)

// 刷新操作
const onRefresh = () => {
  isRefreshing.value = true
  setTimeout(() => {
    // 模拟更新数据
    lists.value.push('F', 'G', 'H')
    isRefreshing.value = false
  }, 1000)
}
</script>

3.2 监听 pullingdown 事件

• 说明：pullingdown 事件在下拉过程中触发，可以根据下拉距离自定义下拉显示的效果。

<template>
  <scroll-view>
    <!-- 下拉刷新组件，监听 pullingdown 事件 -->
    <refresh 
      :display="isRefreshing ? 'show' : 'hide'" 
      @refresh="onRefresh" 
      @pullingdown="onPullingDown"
    >
      <text>{{ pullDistance }} px pulled down...</text>
      <loading-indicator></loading-indicator>
    </refresh>

    <!-- 列表内容 -->
    <view v-for="(item, index) in lists" :key="index">
      <text>{{ item }}</text>
    </view>
  </scroll-view>
</template>

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

// 模拟列表数据
const lists = ref(['A', 'B', 'C', 'D', 'E'])
const isRefreshing = ref(false)
const pullDistance = ref(0)

// 监听下拉刷新过程
const onPullingDown = (event) => {
  pullDistance.value = event.pullingDistance
}

// 刷新操作
const onRefresh = () => {
  isRefreshing.value = true
  setTimeout(() => {
    // 模拟更新数据
    lists.value.push('F', 'G', 'H')
    isRefreshing.value = false
  }, 1000)
}
</script>

4. 完整的下拉刷新功能

以下案例展示了如何结合 refresh 组件实现下拉刷新功能，结合 loading-indicator 提示用户当前的刷新状态，并在下拉过程中自定义下拉显示的内容。

<template>
  <scroll-view>
    <!-- 下拉刷新组件，结合 pullingdown 和 refresh 事件 -->
    <refresh 
      :display="isRefreshing ? 'show' : 'hide'" 
      @refresh="onRefresh" 
      @pullingdown="onPullingDown"
    >
      <text>{{ pullDistance }} px pulled down...</text>
      <loading-indicator></loading-indicator>
    </refresh>

    <!-- 列表内容 -->
    <view v-for="(item, index) in lists" :key="index">
      <text>{{ item }}</text>
    </view>
  </scroll-view>
</template>

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

// 模拟列表数据
const lists = ref(['A', 'B', 'C', 'D', 'E'])
const isRefreshing = ref(false)
const pullDistance = ref(0)

// 监听下拉刷新过程
const onPullingDown = (event) => {
  pullDistance.value = event.pullingDistance
}

// 刷新操作
const onRefresh = () => {
  isRefreshing.value = true
  setTimeout(() => {
    // 模拟更新数据
    lists.value.push('F', 'G', 'H')
    isRefreshing.value = false
  }, 1000)
}
</script>