如何精准探测用户离开与返回TimeMe.js 的 callWhenUserLeaves 与 callWhenUserReturns 回调机制深度解析【免费下载链接】TimeMe.jsA JavaScript library to accurately time how long a user views a web page, disregarding idle time and time when the tab or window is minimized.项目地址: https://gitcode.com/gh_mirrors/ti/TimeMe.jsTimeMe.js 是一款专注于网页计时准确性的 JavaScript 库它只统计用户真正停留在页面上的有效时长自动忽略闲置idle时间和标签页/窗口被最小化的时间。本文带你从零理解它的两大核心回调callWhenUserLeaves用户离开时触发与callWhenUserReturns用户返回时触发何时触发、参数怎么用、源码里是怎么实现的。TimeMe.js 网页计时解决什么问题传统页面停留时长统计有个通病只要标签页没关时间就一直累加数据严重虚高。TimeMe.js 会自动在以下情况暂停计时 ⏸️用户切换了浏览器标签页或把窗口最小化用户长时间没有鼠标移动、键盘输入默认 30 秒可自定义在这套有效时长模型之上TimeMe.js 提供了两个业务钩子回调 API触发时机典型用途callWhenUserLeaves用户切走、失焦或闲置超时上报停留时长、暂停视频、记录离开事件callWhenUserReturns用户切回、重新聚焦或恢复操作播放欢迎回来提示、续播内容、恢复埋点项目核心文件一览建议先浏览一遍 文件作用timeme.js库主源码两个回调的全部实现都在此timeme.min.js压缩版生产环境直接用README.md官方文档与完整 API 说明demo/index.html可交互的演示页能直观看到离开/返回状态tests/tests.js单元测试覆盖回调执行次数的各种场景用户离开由哪些事件触发注册回调之前先搞清楚 TimeMe.js 在什么时刻判定用户离开了。所有监听都在initialize()初始化时自动挂上无需手动配置标签页切换 / 窗口最小化—— 监听浏览器的visibilitychange事件并自动适配各浏览器不同的隐藏属性名hidden、webkitHidden、mozHidden、msHidden详见 timeme.js窗口失去焦点blur—— 用户点击了其他应用同样判定为离开见 timeme.js闲置超时—— 连续一段时间无鼠标/键盘操作默认 30 秒也走离开链路见 timeme.js与之对应返回则由窗口重新获得焦点focus、标签页重新可见、或用户恢复操作鼠标移动、按键、触摸、滚动触发。三步注册 callWhenUserLeaves 离开回调接口签名非常简洁TimeMe.callWhenUserLeaves(callback, numberOfTimesToInvoke);callback用户离开页面时要执行的函数numberOfTimesToInvoke可选该回调最多执行的次数不传则每次离开都会触发官方示例见 README.md// 用户前 5 次离开页面时都会执行 TimeMe.callWhenUserLeaves(function () { console.log(The user is not currently viewing the page!); }, 5);实现层面只做了一件事把回调函数 剩余执行次数这个组合压入userLeftCallbacks队列等待触发时机源码见 timeme.js。设置回调最大执行次数numberOfTimesToInvoke 参数这个可选参数是控制打扰频率的关键 ⚡不传每次用户离开都会执行回调适合上报数据这类幂等操作传 N只执行前 N 次之后该回调静默失效适合一次性提示、只统计一次离开行为等场景触发时的判断逻辑在 timeme.js只有当剩余次数未定义或大于 0 时回调才会被执行随后计数减一。callWhenUserReturns 返回回调自动续上计时注册方式与离开回调完全对称// 每次用户返回页面时都会执行 TimeMe.callWhenUserReturns(function () { console.log(The user has come back!); });源码同样是将回调压入userReturnCallbacks队列见 timeme.js。一个容易忽略的细节返回回调触发后库内部会自动调用startTimer()重新开始计时计时器无需你手动恢复见 timeme.js。这保证了离开→返回往返之后停留时长的统计依然连续准确。源码走读两条触发链背后的状态机两个回调共用一个布尔标志isUserCurrentlyOnPage作为状态机核心离开链triggerUserHasLeftPageOrGoneIdle()先确认标志为 true再置为 false然后遍历userLeftCallbacks队列逐个执行遵守剩余次数限制最后调用stopAllTimers()暂停所有计时器见 timeme.js返回链triggerUserHasReturned()反过来把标志从 false 翻转为 true、重置闲置倒计时、执行userReturnCallbacks队列再startTimer()恢复计时见 timeme.js闲置检测库每 250 毫秒轮询一次闲置状态超时就并入离开链而任何鼠标/键盘/触摸/滚动活动都会调用userActivityDetected()重置倒计时并触发返回见 timeme.js 注意源码中留有 TODO 注释说明用户离开页面与用户闲置两个概念目前共用同一条触发链后续计划拆分为独立函数见 timeme.js。现阶段可以简单理解为闲置超时也视同离开。单元测试验证用 tests.js 看懂回调行为单元测试是最快的 API 行为说明书四个测试用例覆盖了限次与不限次两种语义测试用例验证点代码位置leaves 限次执行numberOfTimesToInvoke1时只执行一次tests/tests.jsleaves 不限次不传次数时每次都执行tests/tests.jsreturns 限次执行返回回调同样只执行一次tests/tests.jsreturns 不限次返回回调不限次时多次执行tests/tests.js快速上手两步完成克隆、初始化与回调注册第 1 步获取代码或直接用npm install timeme.js --save安装git clone https://gitcode.com/gh_mirrors/ti/TimeMe.js第 2 步在页面中引入并初始化。官方演示页 demo/index.html 就是一个最小完整示例核心只有几行TimeMe.initialize({ currentPageName: my-home-page, // 当前页面名 idleTimeoutInSeconds: 30 // 闲置判定阈值秒 }); TimeMe.callWhenUserLeaves(function () { // 例如把已停留时长上报到服务端 }, 5); TimeMe.callWhenUserReturns(function () { // 例如播放欢迎回来提示 });初始化时还可通过trackWhenUserLeavesPage/trackWhenUserGoesIdle两个选项分别关闭离开页面或闲置的监听两者默认均为开启。实战建议与常见场景场景推荐做法停留时长上报在callWhenUserLeaves中调用getTimeOnCurrentPageInSeconds()读取时长后发送避免页面中途丢失数据只提示一次的弹窗callWhenUserReturns搭配numberOfTimesToInvoke 1避免反复打扰用户实时展示在线/离开状态读取内部标志isUserCurrentlyOnPage官方演示页正是这样做的见 demo/index.htmlSPA 单页应用切页按stopTimer()→setCurrentPageName()→startTimer()三步切换见 README.md调整闲置阈值用setIdleDurationInSeconds()动态修改官方文档提到可设-1关闭闲置超时见 README.md关闭闲置检测初始化时传trackWhenUserGoesIdle: false只保留切走/失焦的离开判定小结callWhenUserLeaves与callWhenUserReturns是 TimeMe.js 把有效停留时长转化为业务动作的两大支点前者让你精准捕捉用户离开的瞬间切标签、失焦、闲置超时三条链路都会触发后者在用户回归时自动续上计时并执行回调。配合可选的执行次数限制既能做数据上报也能做体验优化。打开 timeme.js 走读一遍两条触发链再用 tests/tests.js 对照测试断言基本就能完全掌握这套回调机制了 ✅【免费下载链接】TimeMe.jsA JavaScript library to accurately time how long a user views a web page, disregarding idle time and time when the tab or window is minimized.项目地址: https://gitcode.com/gh_mirrors/ti/TimeMe.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考