定时任务 - 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<string>} 每周几运行，参数包括：`['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的后续版本中修复。