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

触屏下拉刷新手势：内容区顶部下拉 → 释放越过阈值触发 `refresh`，`v-model` 同步加载中
状态，加载完成后置 `false` 自动展示成功态并收回。滚动容器不在顶部时不拦截手势（页面
可正常上滚）；超过触发距离后 1/3 阻尼跟手，形成「越拉越紧」的手感。状态机：
normal → pulling → loosing → loading → success → normal，全程由 `change` 事件广播。

## 基础用法

```html
<eb-pull-refresh v-model="refreshing" @refresh="onRefresh">
  <NewsList :items="items" />
</eb-pull-refresh>
```

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

要点：

* **手势边界**：滚动容器 `scrollTop > 0` 时下拉不生效（让位给页面滚动）；`touchmove` 以
  非被动模式监听，仅在可下拉时 `preventDefault` 阻断浏览器原生下拉。
* **状态闭环**：`refresh` 触发时组件已置 loading；业务加载完成把 `modelValue` 置 `false`，
  成功态停留 `success-duration` 后自动收回，无需手动清理。

## 自定义头部

`#head` 插槽替换默认提示（参数 `{ status, distance }`），可完全自定义动画；四段文案
也可按需覆盖。

## API