# 下拉刷新 PullToRefresh

- 页面: https://jiguang132.com/zh/resources/ant-design-mobile/docs/pull-to-refresh
- 资源: Ant Design Mobile (https://jiguang132.com/zh/resources/ant-design-mobile.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design-mobile/docs.md

在列表中通过手指下拉刷新加载新内容的交互操作。

## 安装

```bash
npm install antd-mobile@5.43.0
```

antd-mobile 是移动网页组件库，不是 React Native 或小程序组件。React 19 项目需在入口用 `unstableSetRender` 注册 `createRoot`，否则 Toast、Dialog 等命令式 API 无法渲染；深色模式通过 `<html data-prefers-color-scheme="dark">` 切换。

示例来自 Ant Design Mobile 官方仓库（MIT），固定在 npm 5.43.0 对应的提交；示例中的 `DemoBlock` 等展示辅助组件由 JGuang 重写，不属于 antd-mobile 的 API。

在列表中通过手指下拉刷新加载新内容的交互操作。

## 何时使用

适用于对当前页面进行内容更新。

## 示例

### 基础用法

### 自定义提示文案

### 处理刷新失败的情况

### 内容区域存在多层嵌套

## PullToRefresh

### 属性

```ts | pure
type PullStatus = 'pulling' | 'canRelease' | 'refreshing' | 'complete'
```

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| canReleaseText | 释放的提示文案 | `ReactNode` | `'释放立即刷新'` |
| completeDelay | 完成后延迟消失的时间，单位为 ms | `number` | `500` |
| completeText | 完成时的提示文案 | `ReactNode` | `'刷新成功'` |
| disabled | 是否禁用下拉刷新 | `boolean` | `false` |
| headHeight | 头部提示内容区的高度，单位为 px | `number` | `40` |
| onRefresh | 触发刷新时的处理函数 | `() => Promise<any>` | - |
| pullingText | 下拉的提示文案 | `ReactNode` | `'下拉刷新'` |
| refreshingText | 刷新时的提示文案 | `ReactNode` | `'加载中……'` |
| renderText | 根据下拉状态，自定义下拉提示文案 | `(status: PullStatus) => ReactNode` | - |
| threshold | 触发刷新需要下拉多少距离，单位为 px | `number` | `60` |

## 常见问题

### 是否支持上拉加载更多？

上拉加载更多是另一个组件：[InfiniteScroll](/zh/components/infinite-scroll)。

### 关于浏览器的默认下拉行为

一些浏览器或者 webview 容器本身会有弹性效果或下拉刷新的逻辑，我们不太建议在这种环境中使用 PullToRefresh 组件，如果你一定要用的话，请禁用掉外层浏览器默认的下拉和弹性效果，不然可能会出现 PullToRefresh 和浏览器的默认行为同时被触发的情况，从而导致用户体验比较差。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt