uni-app 之 下拉刷新

下拉刷新是移动端常见的交互方式，用户通过下拉手势触发页面数据更新。uni-app 提供了完整的下拉刷新功能支持。

启用下拉刷新

在页面的配置中启用下拉刷新功能：

pages.json 配置方式

{
"pages": [
{
"path": "pages/index/index",
"style": {
"enablePullDownRefresh": true,
"backgroundTextStyle": "dark"
}
}
]
}

页面级配置（Vue 文件中）

export default {
onPullDownRefresh() {
// 下拉刷新触发时执行
this.refreshData();
},
};

相关 API

1. uni.startPullDownRefresh()

主动触发下拉刷新

参数说明：

示例代码：

// 主动触发下拉刷新
uni.startPullDownRefresh({
success: function () {
console.log("开始下拉刷新");
},
});

2. uni.stopPullDownRefresh()

停止当前页面的下拉刷新

参数说明：

示例代码：

// 停止下拉刷新
uni.stopPullDownRefresh();

完整实现示例

方法一：通过页面生命周期函数实现

export default {
data() {
return {
list: [],
};
},
onPullDownRefresh() {
// 下拉刷新触发
this.refreshData();
},
methods: {
refreshData() {
// 模拟请求数据
setTimeout(() => {
this.list = this.getNewData();
// 数据加载完成后停止下拉刷新
uni.stopPullDownRefresh();
}, 2000);
},
getNewData() {
// 获取新数据的逻辑
return ["新数据1", "新数据2", "新数据3"];
},
},
};

方法二：主动触发下拉刷新

export default {
data() {
return {
list: [],
};
},
methods: {
handleRefresh() {
// 主动触发下拉刷新
uni.startPullDownRefresh();
},
refreshData() {
// 获取最新数据
this.fetchData()
.then((data) => {
this.list = data;
// 停止下拉刷新
uni.stopPullDownRefresh();
})
.catch(() => {
uni.stopPullDownRefresh();
});
},
fetchData() {
return new Promise((resolve) => {
setTimeout(() => {
resolve(["数据1", "数据2", "数据3"]);
}, 2000);
});
},
},
};

配置项说明

pages.json 中的相关配置

{
"pages": [
{
"path": "pages/index/index",
"style": {
// 是否启用下拉刷新
"enablePullDownRefresh": true,
// 窗口的背景色
"backgroundColor": "#ffffff",
// 下拉 loading 的样式
"backgroundTextStyle": "dark",
// 下拉刷新控件的颜色（仅微信小程序）
"backgroundColorTop": "#ffffff"
}
}
]
}

注意事项

最佳实践

export default {
data() {
return {
list: [],
loading: false,
};
},
onPullDownRefresh() {
this.loadData(true);
},
methods: {
async loadData(isRefresh = false) {
if (!isRefresh && this.loading) return;

this.loading = true;

try {
const data = await this.fetchDataFromServer();

if (isRefresh) {
this.list = data; // 刷新时替换数据
uni.stopPullDownRefresh(); // 停止下拉刷新
} else {
this.list = […this.list, …data]; // 加载更多时追加数据
}
} catch (error) {
console.error("数据加载失败:", error);
if (isRefresh) {
uni.stopPullDownRefresh();
}
} finally {
this.loading = false;
}
},

fetchDataFromServer() {
return new Promise((resolve, reject) => {
uni.request({
url: "https://api.example.com/data",
success: (res) => {
resolve(res.data);
},
fail: (err) => {
reject(err);
},
});
});
},
},
};