更新记录

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; 其余几条来自事件流,需要订阅才会打印。

注意事项

  1. 仅支持 Android:插件只实现了 app-android 平台目录,其他平台不可用。
  2. App 前后台切换必须重置:否则后台停留时间会被算成「连续无操作」而误报超时。
  3. 超时回调在主线程执行,回调内不要执行耗时操作。
  4. 每段空闲只回调一次:如需「持续每 N 秒提醒一次」,需要在业务层自行重置计时。
  5. 改插件源码后要强制重编: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。
  6. 插件层不打印日志,排查问题时请在业务层或原生层加日志。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议

暂无用户评论。