idledetection api 仅在 chrome 84+/edge 90+ 中可用，需同时满足 https（localhost/127.0.0.1 除外）、用户手势触发、顶级上下文或带 allow="idle-detection" 的 iframe 三条件；权限须先 requestpermission() 再初始化实例，threshold 不低于 60000ms；userstate 与 screenstate 含义不同，状态变更才触发 change 事件；后台 tab 易失效，需结合 visibilitystate 管理启停，并始终校验 permissions.query 结果，关键业务必须叠加服务端心跳验证。
IdleDetection API 目前仅在 Chrome 84+（含 Edge 90+）中可用，且必须满足 HTTPS、用户手势授权、顶级浏览上下文三个硬性条件。不满足任一条件时调用 requestPermission() 会直接抛出 NotAllowedError 或静默失败。
检查浏览器支持与运行环境是否合规
不是所有现代浏览器都实现了该 API，且它对上下文极其敏感：
-
'IdleDetector' in window必须为true，否则整个流程无法启动 - 页面必须通过 HTTPS 提供服务；
http://localhost和http://127.0.0.1是唯一被允许的非 HTTPS 例外 - 首次调用
new IdleDetector()前，必须由用户点击、键盘输入等明确手势触发（不能在DOMContentLoaded或load中自动执行） - 不能在 iframe 中使用，除非该 iframe 具有
allow="idle-detection"属性且其父文档也满足上述条件
正确申请权限并初始化检测器
权限请求不是一次性弹窗确认，而是分两步：先调用 requestPermission() 获取许可状态，再用该状态初始化实例。跳过这一步或顺序颠倒会导致 TypeError: Illegal constructor：
if ('IdleDetector' in window) {
try {
const permission = await IdleDetector.requestPermission();
if (permission === 'granted') {
const detector = new IdleDetector();
detector.addEventListener('change', () => {
console.log('user state:', detector.userState, 'screen state:', detector.screenState);
});
await detector.start({
threshold: 60_000 // 单位毫秒，最小值为 60_000
});
}
} catch (err) {
console.error('Idle detection setup failed:', err.name, err.message);
}
}
注意：threshold 参数不可低于 60 秒，传入 30000 会被自动提升为 60000；低于该值将抛出 RangeError。
监听 change 事件并区分 userState / screenState
change 事件只在状态切换时触发（如从 active → idle），不会轮询。两个关键属性含义不同，容易混淆：
-
detector.userState表示用户是否与设备交互：值为'active'、'idle'或'locked'（后者仅当系统锁屏时返回，桌面端常见，移动端极少） -
detector.screenState表示屏幕是否亮起：值为'locked'或'unlocked'，和系统屏幕开关强相关，与用户操作无直接关系 - 常见误判场景：用户开着页面但去泡咖啡（
userState === 'idle'），但屏幕仍亮着（screenState === 'unlocked'）；此时应以userState为准做业务标记
避免后台 tab 失效与权限丢失问题
该 API 在页面被切换到后台后行为不稳定——Chrome 会暂停检测器，且部分版本在 tab 恢复时不会自动恢复状态。更关键的是：用户手动在设置中撤销权限后，detector 实例不会自动失效，后续读取 userState 可能返回过期值：
- 务必在每次需要判断前检查
navigator.permissions.query({name: 'idle-detection'})的state是否仍为'granted' - 不要依赖单次
start()后长期存活的实例；建议在页面可见时（document.visibilityState === 'visible'）重新start()，隐藏时stop() - 若发现
userState长时间未更新（比如超过threshold + 5000ms），应主动调用detector.stop()并尝试重建
真正难处理的不是“怎么写”，而是“什么时候不该信它”——userState 切换存在最多 2 秒延迟，且在低功耗模式、远程桌面、某些企业策略（如 idledetectionblockedforurls）下会完全禁用。业务逻辑中凡涉及自动登出、会话冻结等关键操作，必须叠加心跳上报或服务端活跃判定，不能只靠前端 idle 状态。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
