更新记录
1.0.0(2026-11-19) 下载此版本
- 新增 uni-app x (Android) 用户操作监听能力,用于「长时间无操作」的超时检测
- 新增
startUserActivityWatch:启动监听并开始无操作计时,超时时长单位为秒,默认 300 秒 - 新增
stopUserActivityWatch:停止监听,并取消尚未触发的超时回调 - 新增
resetUserActivityWatch:重置最后一次操作时间(App 回到前台时使用,避免把后台停留算成无操作) - 新增
getUserIdleSeconds:查询当前已连续无操作的时长(秒) - 新增
getUserActivityState:查询当前 Activity 状态,用于确认监听是否真的挂上 - 新增
onUserActivityEvent:统一事件流回调,事件类型 start / interaction / reset / timeout / stop,携带 idleSeconds、timeoutSeconds、wallClock - 新增 超时回调通道
onIdle/onTimeout:倒计时结束单独处理,不依赖事件订阅 - 基于
Activity.onUserInteraction()实现,一次注册即可覆盖触摸 / 点击 / 滑动 / 物理按键 - 原生计时采用单调时钟
SystemClock.elapsedRealtime()+ 主线程Handler防抖排程 + 代次校验,避免误报超时
平台兼容性
uni-app x(5.0)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | √ | - | - | - |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | × | √ |
TH-UserActivity UTS 插件
监听 Android 手持机的用户操作(触摸 / 点击 / 滑动 / 物理按键),并统计「连续无操作时长」,达到阈值后触发一次回调。
用于长时间无操作的超时检测(例如超时后打印日志、弹窗提示、返回登录页等)。
UniActivityCallback / UTSAndroid 这类原生能力只有 UTS 插件(插件的 index.uts 编译为原生 Kotlin)才能用,
所以本能力统一封装成 UTS 插件。
蒸汽(Vapor)模式下应用层的
.uts/.js走uts2js编译到 JS,拿不到这些原生 API; VDOM 模式下应用层.uts本身就编译为原生,也可以直接写在应用层。 两种模式下的 UTS 插件都能用本插件。
环境要求
| 项目 | 要求 |
|---|---|
| HBuilderX | 5.21+ |
| uni-app x | 4.81+ |
| 平台 | Android(uni-app x) |
| 模式 | 蒸汽(Vapor)UTS 插件 5.21+;VDOM UTS 插件 4.18+ |
快速开始
import {
onUserActivityEvent,
startUserActivityWatch,
stopUserActivityWatch,
resetUserActivityWatch,
getUserIdleSeconds
} from '@/uni_modules/th-user-activity'
// 1. 先订阅事件流(所有状态变化都从这里回调,可选)
onUserActivityEvent(function (event) {
console.log(event.type, event.idleSeconds, event.timeoutSeconds)
})
// 2. 再启动监听:超时时长单位是「秒」,不传默认 300 秒
// onTimeout 是独立的超时通道,不依赖上面的事件订阅
startUserActivityWatch({
timeoutSeconds: 60,
onTimeout: function () {
console.log('已 60 秒没有操作')
}
})
// App 回到前台:重新开始计时,避免把后台停留算成无操作
resetUserActivityWatch()
// 停止监听
stopUserActivityWatch()
// 查询当前已连续无操作的时长(秒)
console.log(getUserIdleSeconds())
API 参考
onUserActivityEvent(callback)
订阅事件流。所有状态变化都通过这一个回调上报,带数据。
| 参数 | 类型 | 说明 |
|---|---|---|
callback |
(event: UserActivityEvent) => void |
事件回调 |
UserActivityEvent 结构:
| 字段 | 类型 | 说明 |
|---|---|---|
type |
string |
事件类型,见下表 |
idleSeconds |
number |
事件发生时的「已连续无操作」秒数 |
timeoutSeconds |
number |
当前生效的无操作阈值(秒) |
wallClock |
number |
事件发生的墙上时钟时间戳(毫秒,Date.now()) |
事件类型:
type |
触发时机 | idleSeconds 含义 |
|---|---|---|
start |
监听已启动 | 0 |
interaction |
检测到用户操作(触摸/点击/滑动/物理按键),计时被重置 | 本次被终结的那段空闲时长 |
reset |
计时被重置(App 回到前台等场景) | 重置前的空闲时长 |
timeout |
连续无操作达到阈值 | 实际空闲时长 |
stop |
监听已停止 | 0 |
onUserActivityEvent(function (event) {
console.log(event.type, event.idleSeconds, event.timeoutSeconds, event.wallClock)
})
- 已内置
@UTSJS.keepAlive,回调可以多次触发(见下方「关键实现说明」)。 - 先订阅再启动,否则会漏掉
start事件。
startUserActivityWatch(options)
启动监听并开始计时。
| 字段 | 类型 | 说明 |
|---|---|---|
timeoutSeconds |
number |
无操作超时时长(秒),可选,非法值(<= 0、NaN)回落到 300 秒 |
onIdle |
() => void |
超时回调(原始 API,保留),每段连续无操作只触发一次 |
onTimeout |
() => void |
超时回调(倒计时结束单独处理用),每段连续无操作只触发一次 |
- 同步方法,调用即启动成功。
- 每段「连续无操作」只报一次超时:下一次发生用户操作时自动开启新的空闲窗口。
- 重复调用会覆盖超时时长并重新计时。
onIdle与onTimeout等价,两个都会回调。 两者都不依赖事件订阅:即使没有订阅onUserActivityEvent,超时回调依然会被触发。
stopUserActivityWatch()
停止监听,同时取消尚未触发的超时回调。幂等操作。
resetUserActivityWatch()
重置「最后一次操作时间」,重新开始计时。
- 用途:App 从后台回到前台时调用,避免把停留在后台的时间算成「连续无操作」而误报超时。
- 未启动监听时调用无效果。
getUserIdleSeconds()
查询距离最后一次用户操作已经过去多少秒。
- 同步方法,返回
number(秒)。 - 从未发生过操作时返回
0。
getUserActivityState()
查询当前 Activity 状态,用于确认监听是不是真挂上了。
- 返回 Activity 类名(如
io.dcloud.uniappxv.activity.UniBasicActivity)表示正常。 - 返回
no-activity表示当前拿不到 Activity,onActivityCallback注册的回调收不到任何事件, 表现为「超时能触发,但触摸永远检测不到」。
关键实现说明
1. 一次注册覆盖全部用户操作类型
监听基于 Android Activity.onUserInteraction()。AOSP 源码中:
dispatchTouchEvent()在ACTION_DOWN时调用onUserInteraction();dispatchKeyEvent()在按键事件分发时调用onUserInteraction()。
因此一次注册即可覆盖触摸、点击、滑动起始与物理按键,无需分别监听各类型事件。
2. 计时下沉到原生层
计时与超时判定全部在原生层(ThUserActivityBridge.kt)完成:
- 计时基准使用单调时钟
SystemClock.elapsedRealtime(),不受系统时间被修改(网络对时、手动改时间)影响; - 使用主线程
Handler.postDelayed做防抖排程:每次操作取消旧的延时任务并重排新的,任何时刻只有一个待触发任务; - 排程带代次(generation):延时任务到期时若代次已过期,说明期间发生过新操作,任务直接作废,避免误报;
- 超时回调在主线程(ui 线程)执行,UTS 侧可直接更新响应式状态。
3. 必须加 @UTSJS.keepAlive
HBuilderX 4.25+ 起,UTS 导出方法的回调参数触发一次后就会被自动回收,第二次回调会提示:
callback回调函数已释放,不能再次执行
超时回调是长生命周期的,因此声明了常驻内存:
@UTSJS.keepAlive
export const startUserActivityWatch : StartUserActivityWatch = function (options : UserActivityWatchOptions) { ... }
4. 模块级持有回调实例
let activityCallback : UserActivityCallbackImpl | null = null
模块级持有 UserActivityCallbackImpl 实例,防止实例被 GC 后收不到事件;ensureActivityCallback() 保证只注册一次。
5. 与 th-key-listener 共存
本插件注册的是 UniActivityCallback,与 th-key-listener 注册的 UniActivityKeyEventCallback 是不同的子类,框架侧按类型分发,互不覆盖。
6. 实测环境注意
- 真机(alps PDA / UROVO DT50)实测通过:触摸导航后能收到
onInteraction回调,超时回调也按预期触发。 - MuMu 模拟器(
127.0.0.1:7555)不投递触摸事件:adb shell input tap注入后连InputDispatcher日志都没有,App 也无任何反应。 在这类设备上测试「用户操作检测」会得到误判结论(看起来像回调没触发,实际是事件根本没进 App),请务必换真机验证。
7. 不做日志打印
插件层刻意不打任何日志,超时日志由业务层(项目内 utils/idle.js)统一打印。
目录结构
uni_modules/th-user-activity
├── package.json
├── README.md
└── utssdk
├── interface.uts # 对外 API 类型声明
└── app-android
├── config.json # minSdkVersion 21
├── index.uts # Android 胶水层(注册 Activity 回调)
└── ThUserActivityBridge.kt # 原生计时与超时判定层
interface.uts是插件对外暴露能力的声明入口,与index.uts是「声明与实现」的关系。index.uts中import { ... } from '../interface.uts'的作用是让类型参与平台编译,否则页面侧引用会编译失败。
项目内用法
业务层封装在 utils/idle.js(订阅事件 + 转成业务日志;超时走独立通道 + 弹 toast):
import { subscribeUserActivityEvent, startIdleWatch, stopIdleWatch, resetIdleWatch } from '@/utils/idle.js'
App.uvue 中的接入方式:
// 连续无操作超时时长(秒)
const IDLE_TIMEOUT_SECONDS = 300
onLaunch(() => {
// 先订阅事件流,再启动监听,否则会漏掉「已启动」事件
subscribeUserActivityEvent()
startIdleWatch(IDLE_TIMEOUT_SECONDS)
})
onAppShow(() => {
// 回到前台重新计时
resetIdleWatch()
})
onExit(() => {
stopIdleWatch()
})
跑起来后控制台会依次出现:
[idle] 已启动用户操作监听(无操作阈值 300 秒)
[idle] 当前 Activity:io.dcloud.uniappxv.activity.UniBasicActivity
[idle] 检测到用户操作(本次操作前已无操作 12 秒,计时已重置)
[idle] 计时已重置(重置前已无操作 8 秒)
[idle] 用户已连续 300 秒无操作(阈值 300 秒) ← 同时弹 toast
[idle] 倒计时结束来源:onTimeout 独立通道
[idle] 已停止用户操作监听
超时有两条通道(
onTimeout独立通道 / 事件流的timeout事件), 业务层做了 1 秒内去重,只打印一次、只弹一次 toast, 并用「倒计时结束来源」标明这次超时是被哪条通道触发的。「用户已连续 X 秒无操作」这条来自
onTimeout独立通道, 即使subscribeUserActivityEvent()没执行也会打印并弹 toast; 其余几条来自事件流,需要订阅才会打印。
注意事项
- 仅支持 Android:插件只实现了
app-android平台目录,其他平台不可用。 - App 前后台切换必须重置:否则后台停留时间会被算成「连续无操作」而误报超时。
- 超时回调在主线程执行,回调内不要执行耗时操作。
- 每段空闲只回调一次:如需「持续每 N 秒提醒一次」,需要在业务层自行重置计时。
- 改插件源码后要强制重编:HBuilderX 对 UTS 插件的增量编译有时会误判「文件未发生变化,跳过编译」,
导致改动没生效。原因是编译缓存
unpackage/cache/vapor/<custom|standard>_android/app-android/uts/uni_modules/th-user-activity/manifest.json里记了各源文件的 md5,上次编译失败时缓存照样被更新,之后就一直认为「没变化」。 三种强制重编的办法(任选其一):- 把
package.json里的version加一位(md5 变化,最简单); - 删掉上面那个缓存目录;
cli.exe launch app-android --cleanCache true --compile true。
- 把
- 插件层不打印日志,排查问题时请在业务层或原生层加日志。

收藏人数:
下载插件并导入HBuilder
赞赏(0)
下载 381
赞赏 1
下载 12775000
赞赏 1960
赞赏
京公网安备:11010802035340号