定时任务 - TimedTasks

# 定时任务 该模块用于管理定时任务,用于在某些时间或某些事件触发时自动运行脚本。正如Auto.js Pro内置的定时任务功能一样,打包的脚本也可以使用这些函数来创建定时任务。 添加定时任务时建议加上申请忽略电池优化的代码,防止被Android限制在后台运行。参见[电池管理 - PowerManager](/zh-cn/powerManager)。 ```javascript if (!$power_manager.isIgnoringBatteryOptimizations()) { console.log("未开启忽略电池优化"); $power_manager.requestIgnoreBatteryOptimizations(); } ``` > 由于各系统的限制,定时任务不能一定保证准时运行,请尽量将Auto.js Pro加入各种白名单和允许自启动权限。 ## $timers.addDailyTask(task) * `task` {Object} 用于描述此定时任务的配置,包括: * `path` {string} 需要运行的脚本的绝对路径 * `time` {number} | {string} | {Date} 此定时任务每天运行的时间,支持时间戳、字符串和Date对象 * `delay` {number} 任务开始前的延迟,单位毫秒,默认为0;如果延时较长,则此参数并不可靠,建议勿用此参数控制大于30s的延迟 * `loopTimes` {number} 任务循环次数,默认为1 * `interval` {number} 任务循环间隔,单位毫秒,默认为0;如果间隔较长,则此参数并不可靠,建议勿用此参数控制大于30s的间隔 * 返回 {[TimedTask](#timedtask)} 新增一个每日运行一次的定时任务。其中时间参数会只保留每天的时间,忽略年月日。 例如创建一个每日下午1点14分运行的定时任务: ```javascript console.log($timers.addDailyTask({ path: "/sdcard/脚本/test.js", time: new Date(0, 0, 0, 13, 14, 0), delay: 0, loopTimes: 1, interval: 0, })); ``` ## $timers.addWeeklyTask(task) * `task` {Object} * `path` {string} 需要运行的脚本的绝对路径 * `time` {number} | {string} | {Date} 此定时任务每天运行的时间,支持时间戳、字符串和Date对象 * `daysOfWeek` {Array} 每周几运行,参数包括:`['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday']` 或 `['一', '二', '三', '四', '五', '六', '日']` * `delay` {number} 任务开始前的延迟,单位毫秒,默认为0;如果延时较长,则此参数并不可靠,建议勿用此参数控制大于30s的延迟 * `loopTimes` {number} 任务循环次数,默认为1 * `interval` {number} 任务循环间隔,单位毫秒,默认为0;如果间隔较长,则此参数并不可靠,建议勿用此参数控制大于30s的间隔 * 返回 {[TimedTask](#timedtask)} 新增一个按星期运行的定时任务。 例如创建一个每周一周二下午1点14分运行5次的定时任务 ```javascript log($timers.addWeeklyTask({ path: "/sdcard/脚本/test.js", // 时间戳为Mon Jun 21 2021 13:14:00 GMT+0800 (中国标准时间),事实上只有13:14:00的参数起作用 time: 1624252440000, daysOfWeek: ['一', '二'], delay: 0, loopTimes: 5, interval: 10 })); ``` ## $timers.addDisposableTask(task) * `task` {Object} * `path` {string} 需要运行的脚本的绝对路径 * `time` {number} | {string} | {Date} 此定时任务开始运行的时间,支持时间戳、字符串和Date对象 * `delay` {number} 任务开始前的延迟,单位毫秒,默认为0;如果延时较长,则此参数并不可靠,建议勿用此参数控制大于30s的延迟 * `loopTimes` {number} 任务循环次数,默认为1 * `interval` {number} 任务循环间隔,单位毫秒,默认为0;如果间隔较长,则此参数并不可靠,建议勿用此参数控制大于30s的间隔 * 返回 {[TimedTask](#timedtask)} 此函数会新增一个一次性的定时任务,任务在执行一次后将在定时任务中自动删除。 例如创建一个2021年5月21日13点14分运行的定时任务。 ```javascript log($timers.addDisposableTask({ path: "/sdcard/脚本/test.js", date: new Date(2021, 5, 21, 13, 14, 0), })); ``` ## $timers.addIntentTask(task) * `task` {Object} * `path` {string} 需要运行的脚本的绝对路径 * `action` {string} 需要监听的事件的广播的Action名称 * `delay` {number} 任务开始前的延迟,单位毫秒,默认为0;如果延时较长,则此参数并不可靠,建议勿用此参数控制大于30s的延迟 * `loopTimes` {number} 任务循环次数,默认为1 * `interval` {number} 任务循环间隔,单位毫秒,默认为0;如果间隔较长,则此参数并不可靠,建议勿用此参数控制大于30s的间隔 * 返回 {[TimedTask](#timedtask)} 新增一个广播定时任务,会在特定事件(广播)发生时运行。 其中最关键的参数是广播事件的Action。系统在发生特定事件(比如电量变化)时会发出特定Action的广播,参见[广播Action](#广播Action)。 例如创建一个在电量发生变化时运行脚本的定时任务: ```javascript log($timers.addIntentTask({ path: "/sdcard/脚本/test.js", action: Intent.ACTION_BATTERY_CHANGED, })); ``` ## $timers.removeTimedTask(id) * `id` {number} 定时任务的id * 返回 {boolean} 是否删除成功 通过id删除按时间运行的定时任务。 ## $timers.removeIntentTask(id) * `id` {number} 定时任务的id * 返回 {boolean} 是否删除成功 通过id删除按事件运行的定时任务。 ## $timers.getTimedTask(id) * `id` {number} 定时任务的id * 返回 {[TimedTask](#timedtask)} 通过id获取按时间运行的定时任务。 ## $timers.getIntentTask(id) * `id` {number}定时任务的id * 返回 {[TimedTask](#timedtask)} 通过id获取按事件运行的定时任务。 例如: ```javascript // 添加一个手机电量变化就触发的定时任务 let id = $timers.addIntentTask({ path: "/sdcard/脚本/test.js", action: Intent.ACTION_BATTERY_CHANGED, delay: 0, loopTimes: 1, interval: 0 }); // 通过id找到该定时任务 let task = $timers.getIntentTask(id.id); // 打印该定时任务所运行脚本的路径 log(task.scriptPath); ``` ## $timers.queryTimedTasks([options]) * `options` {Object} 查询参数,可选。不填时,查询到所有按时间运行的定时任务 * `path` {string} 定时任务脚本的路径 * 返回 {Array<[TimedTask](#timedtask)>} 查找到的定时任务数组 通过脚本路径查找按时间运行的定时任务,或者查询所有按时间运行的定时任务。 例如: ```javascript let jsPath = "/sdcard/脚本/test.js"; // 添加一个每周日下午1点13分运行的定时任务,循环运行5次脚本,间隔5000毫秒 let task = $timers.addWeeklyTask({ path: jsPath, time: 1624252440000, daysOfWeek: ['sunday'], delay: 0, loopTimes: 5, interval: 5000 }); // 按脚本路径查找定时任务 let tasks = $timers.queryTimedTasks({ path: jsPath }); // 删除查找到的所有定时任务 tasks.forEach(t => { console.log("删除: ", t); log($timers.removeTimedTask(t.id)); }); ``` ## $timers.queryIntentTasks([options]) * `options` {Object} 查询参数,可选;不填时,查询到所有按事件运行的定时任务 * `path` {string} 定时任务脚本的路径 * `action` {string} 广播名称 * 返回 {Array<[TimedTask](#timedtask)>} 查找到的定时任务数组 通过脚本路径或监听广播查找按广播运行的定时任务,或者查询所有按广播运行的定时任务。 例如: ```javascript //添加一个手机电量变化就触发的定时任务 let task = $timers.addIntentTask({ path: "/sdcard/脚本/test.js", action: Intent.ACTION_BATTERY_CHANGED, delay: 0, loopTimes: 1, interval: 0 }); // 查找所有的触发事件定时任务 let tasks = $timers.queryIntentTasks(); // 打印所有查找到的定时任务的触发事件 tasks.forEach(t => { console.log(t.action); }); ``` # TimedTask 表示一个定时任务对象,包含了此定时任务的基本信息。 ## TimedTask.id * {number} 此定时任务的唯一id,用于查找定时任务。 ## TimedTask.scriptPath * {string} 此定时任务的所执行脚本的路径。 ## TimedTask.millis * {number} 此定时任务的执行时间的时间戳,单位为毫秒。 ## TimedTask.delay * {number} 此定时任务所设置的延迟, ## TimedTask.interval * {number} 此定时任务循环的间隔。 ## TimedTask.loopTimes * {number} 此定时任务循环的次数。 ## TimedTask.action * {string} 此定时任务的触发事件(只有广播定时任务才有该参数)。 # 广播Action 可以在Android文档[Intent: Action](https://developer.android.google.cn/reference/android/content/Intent#constants_1)中找到大多数Android系统自带的Intent Action;一些系统组件也会自定义自己的Action,比如网络连接变化时触发的Action是`ConnectivityManager.CONNECTIVITY_ACTION`(使用时需要导入ConnectivityManager)。这些Action通常附带一些额外参数,可以通过`$engines.myEngine().execArgv.intent`获取广播的参数,参见[广播参数](#广播参数)。 以下列出一些常见的广播Action: | 广播名 | 说明 | | :-------------------------------------: | :--------------------------------: | | org.autojs.autojs.action.startup | Auto.js 启动时 | | Intent.ACTION_BOOT_COMPLETED | 开机时 | | Intent.ACTION_SCREEN_OFF | 熄屏时 | | Intent.ACTION_SCREEN_ON | 亮屏时 | | Intent.ACTION_USER_PRESENT | 屏幕解锁时 | | Intent.ACTION_BATTERY_CHANGED | 电量变化时 | | Intent.ACTION_POWER_CONNECTED | 电源连接时 | | Intent.ACTION_POWER_DISCONNECTED | 电源断开时 | | ConnectivityManager.CONNECTIVITY_ACTION | 网络连接变化时 | | Intent.ACTION_PACKAGE_ADDED | 新应用安装时 | | Intent.ACTION_PACKAGE_REMOVED | 应用卸载时 | | Intent.ACTION_PACKAGE_REPLACED | 应用更新时 | | Intent.ACTION_HEADSET_PLUG | 耳机拔插时 | | Intent.ACTION_CONFIGURATION_CHANGED | 某些设置(屏幕方向、地区等)更改时 | | Intent.ACTION_TIME_TICK | 每分钟一次 | 示例: ```javascript // 添加一个Auto.js启动时触发的定时任务(在打包中软件也可以使用) console.log($timers.addIntentTask({ path: "/sdcard/脚本/test.js", action: "org.autojs.autojs.action.startup", })); // 添加一个网络状态变化时触发的定时任务 let ConnectivityManager = android.net.ConnectivityManager; console.log($timers.addIntentTask({ path: "/sdcard/脚本/conn_test.js", action: ConnectivityManager.CONNECTIVITY_ACTION, })); ``` # 广播参数 按广播执行的定时任务被执行时,我们可以通过`$engines.myEngine().execArgv.intent`获取到intent对象,再通过Android文档查阅intent对象的参数,从而获取这些参数。 例如电量变化的广播中,查询文档[BatteryManager](https://developer.android.google.cn/reference/android/os/BatteryManager#EXTRA_LEVEL)可以知道通过`EXTRA_LEVEL`参数获取具体电量。 ```javascript // 因电量变化而执行的定时任务脚本 let intent = $engines.myEngine().execArgv.intent; if (!intent) { console.log("请设置定时任务 - 电量变化时来运行此脚本"); exit(); } let BatteryManager = android.os.BatteryManager; let level = intent.getIntExtra(BatteryManager.EXTRA_LEVEL, -1); console.log("电量为", level); ``` # Bug 截止8.7.1版本,Auto.js Pro可能在触发定时任务时执行两次,将在8.7的后续版本中修复。