onPageScroll 不触发的主因是未在 pages.json 中配置 "navigationStyle": "custom"；H5 需容器有高度和 overflow，App/小程序端需避免 scroll-view 拦截原生滚动。
uni-app 中 onPageScroll 捕获滚动却没触发？
多数人卡在这一步：在页面里写了 onPageScroll，但滚动时函数完全不执行。根本原因是——onPageScroll 只在启用了「自定义导航栏」的页面中生效，且必须配合 pageStyle 或 navigationBarBackgroundColor 的动态修改才起作用。
检查你的 pages.json 对应页面配置：
"navigationStyle": "custom"
缺了这句，onPageScroll 就是摆设。另外注意：H5 端需确保容器有明确高度和 overflow，App 和小程序端则依赖原生滚动容器（如 <scroll-view> 会拦截原生滚动，导致 onPageScroll 失效）。
用 setNavigationBarColor 动态改背景色但无效？
setNavigationBarColor 是微信小程序专属 API，在 H5 和 App 端不生效。uni-app 跨端统一方案是：用 uni.setNavigationBarColor（注意是 uni. 开头），但它只在微信/支付宝/百度等支持该能力的小程序平台可用；App 端要用 uni.setNavigationBarColor + 原生插件或直接操作状态栏组件；H5 则只能靠自定义导航栏 DOM 控制。
更稳妥的做法是放弃原生导航栏，全程使用自定义导航栏（view + text），然后通过 onPageScroll 计算透明度：
- 监听
scrollTop，比如阈值设为 100px - 用
Math.min(scrollTop / 100, 1)得到 0～1 的渐变系数 - 将系数用于
rgba(255,255,255,${alpha})设置背景色
自定义标题栏在不同平台渲染错位？
常见现象：iOS 上标题栏被状态栏顶高、Android 上文字偏下、H5 上固定定位失效。根源在于各端对 statusBar 高度和安全区处理不一致。
解决方案是统一用 uni.getSystemInfoSync().statusBarHeight 获取状态栏高度，并在自定义导航栏样式中显式预留：
.nav-bar { padding-top: <code>statusBarHeight</code>px; }
同时加一行兼容性声明：
padding-top: env(safe-area-inset-top);
注意：H5 端无法读取 env()，所以得用条件编译区分：
#ifdef H5<br> padding-top: 0;<br>#endif
滑动过程中标题栏闪烁或卡顿？
这是高频性能陷阱：在 onPageScroll 里直接调用 this.setData（Vue）或 this.$forceUpdate()，导致每帧都触发重绘。小程序端尤其敏感，onPageScroll 触发频率可达 60fps，频繁 setData 会明显掉帧。
优化手段有三个：
- 节流：用
setTimeout+ 标志位，控制每 16ms 最多更新一次 - 避免响应式数据：把渐变值存进
data以外的变量，用uni.createSelectorQuery()直接修改 DOM 样式（仅 H5） - 用
transform: translateZ(0)强制 GPU 加速自定义导航栏容器
最简单有效的写法是：只在 scrollTop 跨越关键阈值（如 0→10、10→50、50→100）时才更新数据，而不是每次滚动都算。
真正麻烦的不是怎么写渐变，而是跨端时每个平台都在悄悄改规则：小程序的导航栏 API 不互通，App 的 status bar 需要原生桥接，H5 的 fixed 定位在 iOS Safari 下有 bounce 回弹干扰。动手前先确认你到底要覆盖几个端，再决定是用纯 CSS 方案，还是引入原生插件兜底。
