uni-app 页面内局部下拉刷新不能用 onPullDownRefresh，因其仅支持页面级下拉；需改用 scroll-view 的 refresher-enabled 和 refresher-triggered 属性组合实现，且刷新后必须手动将 isRefreshing 设为 false，否则动画卡住。
uni-app 页面内局部下拉刷新为什么不能用 onPullDownRefresh
因为 onPullDownRefresh 是页面级生命周期钩子，只响应整个页面的下拉（基于原生导航栏或页面容器），无法绑定到某个 scroll-view 区域内部。想在列表区域单独下拉刷新，必须放弃这个 API，改用 scroll-view 的 refresher-enabled 和 refresher-triggered 属性组合实现。
scroll-view 局部下拉刷新的关键配置项
核心是启用 refresher 系统，并监听触发状态变化。注意：该功能仅在微信小程序、App（nvue）、H5（部分浏览器）支持，支付宝小程序和部分旧版 uni-app 不兼容。
-
refresher-enabled必须为true，否则 refresher 不显示 -
refresher-triggered控制 refresher 是否处于“已触发但未结束”状态，需用v-model或:refresher-triggered+@refresherrefresh配合使用 -
refresher-default-style可选值："black"/"white"/"none"，影响下拉图标颜色 -
refresher-background设置下拉区域背景色，例如"#f8f8f8" - 必须设置
height或max-height，否则scroll-view无法触发滚动和 refresher
完整可运行的 scroll-view 下拉刷新示例
<template><scroll-view class="list-container" scroll-y :refresher-enabled="true" :refresher-triggered="isRefreshing" refresher-default-style="black" refresher-background="#f0f0f0"><view v-for="item in list" :key="item.id">{{ item.text }}</view></scroll-view></template><script>
export default {
data() {
return {
list: [],
isRefreshing: false
}
},
methods: {
onRefresh() {
this.isRefreshing = true
// 模拟请求
setTimeout(() => {
this.list = [{ id: 1, text: 'new item' }, ...this.list]
this.isRefreshing = false // 必须手动设为 false，否则 refresher 卡住
}, 1200)
},
onRestore() {
// refresher 回弹完成时触发，可用于清理 loading 状态（如果用了额外 UI）
}
}
}
</script>
重点：每次刷新完成后，必须显式将 isRefreshing 设为 false，否则下拉动画不会收起，后续无法再次触发 —— 这是最常被忽略的一步。
常见问题与绕过限制的技巧
遇到 refresher 不显示、下拉无反应、多次触发等问题，优先检查以下几点：
-
scroll-view外层不能有overflow: hidden或高度塌陷，建议加style="height: 300px;"显式限定 - H5 端 refresher 行为不稳定，建议用
uni.getSystemInfoSync().platform === 'h5'做降级处理（比如改用顶部按钮手动刷新） - 微信小程序中，若父容器用了
position: fixed，可能导致 refresher 偏移，可尝试给scroll-view加position: relative - 需要自定义 refresher 图标？目前不支持直接替换，只能通过
refresher-default-style="none"隐藏原生图标，再用绝对定位盖一层自己的动画元素（需监听refreshertriggered动态控制显隐）
refresher 是个“半受控”组件：触发靠用户下拉，收起却依赖你手动重置 refresher-triggered，这个不对称性容易被低估。写完别忘了测「快速连续下拉」和「下拉中途取消」两种边界场景。
