必须在 pages.json 对应页面 style 中配置 enablePullDownRefresh: true（布尔值），否则 onPullDownRefresh 不触发；需手动调用 uni.stopPullDownRefresh() 收尾，且重启项目才生效。
必须在 pages.json 里显式配 enablepulldownrefresh: true，否则 onpulldownrefresh 函数写了也完全不触发——这是 90% 的人卡住的第一步。
pages.json 配置必须写对位置和值
下拉刷新不是“写了函数就生效”的功能，它依赖原生容器的开关控制。配置错位置、写错大小写、或被覆盖，都会导致静默失效。
-
enablePullDownRefresh必须放在对应页面的style对象内，不能写在globalStyle或subNVue配置里 - 值必须是布尔型
true，写成字符串"true"或数字1都无效 - 如果该页面用了自定义导航栏（
navigationStyle: "custom"），下拉区域可能被遮挡，需配合pullDownRefresh节点调高offset或设backgroundColor确保可见 - H5 端不支持原生下拉，此配置仅对 App 和小程序起作用；H5 想实现类似效果，得用
scroll-view自建
onPullDownRefresh 里必须手动 stop
uni-app 不会自动收尾。用户松手回弹后，动画图标会一直转，直到你调 uni.stopPullDownRefresh() ——哪怕请求失败，也得调，否则后续下拉全部失灵。
- 无论接口成功还是报错，
uni.stopPullDownRefresh()都必须执行一次 - H5 端调这个 API 无反应，但不报错，可以安全调用
- 别在
onPullDownRefresh里再调uni.startPullDownRefresh()，会套娃崩溃 - 如果你用了
uni.showToast提示，建议加duration: 1000，避免和下拉动画冲突
数据重置逻辑不能直接赋值 list
直接 this.list = [] 或 this.list = newData 在长列表场景下极易引发响应式性能问题，甚至白屏。尤其当列表用了虚拟滚动或图片懒加载时，DOM 计算会错位。
- 下拉刷新时清空：用
this.$nextTick(() => { this.list = []; })包一层，避免 setData 冲突 - 重置分页参数：必须同步设
this.pageNum = 1，且要校验新数据长度来判断是否还有下一页 - 避免在
onPullDownRefresh中操作 DOM 或调用uni.createSelectorQuery，真机上异步延迟高、误差大 - Vue 3
setup中仍需按 Options 风格写onPullDownRefresh() { ... }，挂到返回对象上，别试图用 Composition API 替代
最容易被忽略的是：改完 pages.json 后，H5 和小程序都必须**重启项目**才生效，热更新不识别这个配置变更。另外，App 端若用了 nvue 页面，onPullDownRefresh 本身就不触发——得换 scroll-view + @scrolltoupper 方案。
