必须在 pages.json 对应页面 style 中配置 enablePullDownRefresh: true 才能触发 onPullDownRefresh；需手动调用 uni.stopPullDownRefresh() 收尾，且重启项目才生效。
pages.json 里必须加 enablePullDownRefresh: true
没配这行，onPullDownRefresh 根本不会触发——不是 bug，是 uni-app 的硬性开关。它只认 pages.json（或 subNVue 页面的 json 配置），manifest.json 或 vue 文件里写都不算数。
常见错误现象：console.log("下拉了") 完全不执行；下拉时页面无反应、无动画、无文字提示。
- 必须在对应页面的
style对象里配置，不是全局globalStyle（除非你真想所有页都支持） - 建议同时加
backgroundTextStyle: "dark"或"light"，否则某些平台（如微信小程序）刷新文字可能看不见 - 改完
pages.json后，H5 和小程序都需**重启项目**才生效，热更新不识别这个配置变更
onPullDownRefresh 是唯一入口，但必须手动收尾
uni-app 不会自动停掉下拉动画，哪怕你数据加载完了，图标还在转——这是新手最常卡住的地方。
使用场景：用户手指松开、页面开始回弹时，onPullDownRefresh 才被调用；它只负责“开始干活”，不负责“干完收工”。
- 每次进入该函数后，必须调用
uni.stopPullDownRefresh()，否则刷新状态一直挂着 - 即使请求失败也要调一次，否则用户再下拉也没反应（动画卡死）
- 不要在
onLoad或onShow里调uni.stopPullDownRefresh()，它只对当前正在发生的下拉有效
主动触发要用 uni.startPullDownRefresh()，但有平台限制
想点按钮就刷新？可以，但得先确认当前页面已启用下拉（即 pages.json 已配 enablePullDownRefresh: true），否则 H5 和部分 App 会直接报错。
参数差异：success 回调只在动画真正启动后触发，不是接口请求成功；fail 常见于未配置或当前平台不支持（如支付宝小程序不支持主动触发）。
- 微信小程序、App（v3 编译）、H5 支持主动触发；快应用、百度/支付宝小程序暂不支持
- 别在
onPullDownRefresh里再调startPullDownRefresh，会套娃导致异常 - 如果只是想“模拟刷新”，更稳妥的做法是直接调你的
refreshData()方法，而非强依赖 API
Vue 3 setup 里怎么写？生命周期名不变
很多人以为 Vue 3 要用 onPullDownRefresh 组合式 API，其实不用——uni-app 的页面生命周期函数仍是 Options 风格，setup 里照样写 onPullDownRefresh 函数，挂到返回对象上就行。
容易踩的坑：在 setup() 里用 onMounted 或 onActivated 去监听下拉，完全无效；uni-app 不把下拉事件映射到 Composition API 生命周期里。
- 正确写法：在
setup()返回的对象中，直接写onPullDownRefresh() { ... } - 涉及响应式数据更新时，确保用
ref或reactive声明，并在stopPullDownRefresh后再更新，避免视图未同步 - 别试图用
watch监听某个变量来代替onPullDownRefresh，它和用户手势强绑定，绕不开
页面配置和生命周期函数这两头缺一不可，漏一个，下拉就静音；多写一个无用调用，反而让逻辑变脆。最麻烦的其实是调试时看不到错误——它不报错，只是沉默。
