---
url: /mobile/components/pull-refresh.md
---
# PullRefresh 下拉刷新

`EvPullRefresh` 提供对齐原生 App 的下拉刷新手势：内容区顶部下拉 → 释放触发 `refresh`，
`v-model` 同步加载中状态，加载完成后置 `false` 自动展示成功态并收回。滚动容器不在顶部时
不拦截手势（页面可正常上滚）；超过触发距离后 1/3 阻尼跟手，形成「越拉越紧」的手感。

## 基础用法

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

const refreshing = ref(false)

async function onRefresh() {
  await reloadFirstScreen()
  refreshing.value = false // 置 false 后自动展示「刷新成功」并收回
}
</script>

<template>
  <EvPullRefresh v-model="refreshing" @refresh="onRefresh">
    <ArticleList :items="articles" />
  </EvPullRefresh>
</template>
```

## 自定义提示与阈值

`head-height` 调整触发距离（同时是头部高度）；四段文案均可覆盖，头部整体可用
`#head` 插槽替换（插槽参数 `{ status, distance }` 支持完全自定义动画）。

```vue
<EvPullRefresh
  v-model="refreshing"
  :head-height="40"
  pulling-text="继续拉"
  loosing-text="松手"
  loading-text="更新中"
  success-text="已是最新"
  @refresh="onRefresh"
>
  <ArticleList :items="articles" />
</EvPullRefresh>
```

## API

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | boolean | false | 刷新中状态（v-model）；加载完成置 false，自动展示成功态后收回 |
| disabled | boolean | false | 禁用下拉手势 |
| head-height | number | 50 | 触发刷新的下拉距离（px），同时是头部高度 |
| success-duration | number | 500 | 成功态停留时长（ms），0 表示直接收回 |
| animation-duration | number | 300 | 收回/展开动画时长（ms） |
| pulling-text | string | 下拉刷新 | 未到阈值时的提示 |
| loosing-text | string | 释放刷新 | 越过阈值后的提示 |
| loading-text | string | 加载中… | 加载中的提示 |
| success-text | string | 刷新成功 | 完成后的提示 |

### 事件

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| refresh | — | 释放越过阈值时触发，此时进入 loading |
| change | (status, oldStatus) | 状态流转：normal / pulling / loosing / loading / success |
| update:modelValue | (boolean) | v-model 同步 |

### 插槽

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| default | — | 滚动内容 |
| head | { status, distance } | 自定义头部，替换默认提示 |