work_manager - 定时与任务

该模块用于管理任务，用于在某些时间或某些事件、处理文件时自动运行脚本。正如CloudControl Pro内置的定时任务功能一样，打包的脚本也可以使用这些函数来创建定时任务。

添加任务时建议加上申请忽略电池优化的代码，防止被Android限制在后台运行。

"nodejs";
const power_manager = require("power_manager");
if (!power_manager.isIgnoringBatteryOptimizations()) {
  console.log("未开启忽略电池优化");
  power_manager.requestIgnoreBatteryOptimizations();
}

由于各系统的限制，定时任务不能一定保证准时运行，请尽量将CloudControl Pro加入各种白名单和允许自启动权限。

目录

接口

• IntentTaskConfig
• IntentTaskQuery
• TaskConfig
• TimedTaskConfig
• TimedTaskQuery

类型别名

• DateTime
• DaysOfWeek
• TaskType

函数

• addActivityIntentTask
• addBroadcastIntentTask
• addDailyTask
• addIntentTask
• addOneTimeTask
• addWeeklyTask
• getIntentTask
• getTimedTask
• queryIntentTasks
• queryTimedTasks
• removeIntentTask
• removeTimedTask

类型别名

DateTime

Ƭ DateTime: number | string | Date

日期时间类型，可以是number，表示毫秒时间戳；可以是string，表示标准时间格式；可以是Date对象，表示日期对象。

---

DaysOfWeek

Ƭ DaysOfWeek: "Sunday" | "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "一" | "二" | "三" | "四" | "五" | "六" | "日"

---

TaskType

Ƭ TaskType: "TimedTask" | "IntentTask"

函数

addActivityIntentTask

▸ addActivityIntentTask(task): Promise<Task>

添加在外部应用处理文件时运行的任意图务。比如文件管理中请求打开文件、其他应用中分享文件或文本时，若选择由CloudControl处理，则触发相应任务运行。

首要参数是action，决定了什么动作会触发任务运行。比如：

• android.intent.action.VIEW：外部应用打开文件时触发，比如文件管理器中打开mp3、apk等文件
• android.intent.action.SEND：其他应用分享文件时触发
• 更多Action参见Intent: Action

其次是dataType，决定了什么类型的文件会触发任务运行。比如：

• /：所有文件
• application/vnd.android.package-archive: apk文件
• text/plain: 文本文件
• video/*: 视频文件
• image/*: 图片文件

以下代码执行后将添加一个可以在外部应用查看文本文件的任务：

const { addActivityIntentTask } = require("work_manager");

addActivityIntentTask({
  path: "/sdcard/脚本/handle_text.js",
  action: 'android.intent.action.VIEW',
  dataType: "text/plain"
}).then(task => console.log(`Task ${task} added`));

以下代码是handle_text.js的内容，他会执行时读取要处理的文件内容并打印：

// handle_text.js
"nodejs";
const { myEngine } = require('engines');
const { getPathFromUri } = require('app');
const { readFileSync } = require('fs');
const intent = myEngine().execArgv.intent;
if (!intent) {
    process.exit();
}
const uri = intent.getUri();
const file = getPathFromUri(uri);
console.log(file);
console.log(readFileSync(file, 'utf8'));

参数

名称	类型	描述
task	IntentTaskConfig	意图任务配置

返回值

Promise<Task>

添加的任务的Promise

---

addBroadcastIntentTask

▸ addBroadcastIntentTask(task): Promise<Task>

新增一个广播任务，会在特定事件(广播)时运行。

最关键的参数是广播事件的Action。系统在发生特定事件（比如电量变化）时会发出特定Action的广播。

例如创建一个在电量发生变化时运行脚本的定时任务：

"nodejs";
const { android } = require('rhino').Packages;
const Intent = android.content.Intent;
const { addBroadcastIntentTask } = require("work_manager");
addBroadcastIntentTask({
    path: "/path/to/script.js",
    action: Intent.ACTION_BATTERY_CHANGED,
}).then(task => console.log(`Task ${task} added`));

可以在Android文档Intent: Action中找到大多数Android系统自带的Intent Action；一些系统组件也会自定义自己的Action，比如网络连接变化时触发的Action是ConnectivityManager.CONNECTIVITY_ACTION（使用时需要导入ConnectivityManager)。

以下列出一些常见的广播Action：

• org.autojs.autojs.action.startup : CloudControl启动时，可给CloudControl加上自启动后使任务在开机时运行
• 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 : 每分钟一次

在广播任务运行时，通过require('engines').myEngine().execArgv.intent获取广播的Intent对象，通过Intent对象获取对应的参数。

以下是电量变化时触发的任务脚本，获取当前电量。

"nodejs";
const { myEngine } = require('engines');
const { android } = require('rhino').Packages;

const intent = myEngine().execArgv.intent;
if (!intent) {
   process.exit();
}
const BatteryManager = android.os.BatteryManager;
const level = intent.getIntExtra(BatteryManager.EXTRA_LEVEL, -1);
console.log("Battery:", level);

参数

名称	类型	描述
task	IntentTaskConfig	意图任务配置

返回值

Promise<Task>

添加的任务的Promise

---

addDailyTask

▸ addDailyTask(task): Promise<Task>

新增一个每日运行一次的定时任务。其中时间参数会只保留每天的时间，忽略年月日。 例如创建一个每日下午1点14分运行的定时任务。

示例

"nodejs";
const { addDailyTask } = require("work_manager");
addDailyTask({
    path: "/path/to/script.js",
    time: new Date(0, 0, 0, 13, 14, 0),
})).then(task => console.log(task));

参数

名称	类型	描述
task	TimedTaskConfig	用于描述此定时任务的配置

返回值

Promise<Task>

---

addIntentTask

▸ addIntentTask(task): Promise<Task>

新增一个意图任务，分为两种类型：

• 广播意图任务：会在特定事件(广播)时运行。
• 活动意图任务：在外部应用处理文件时运行。比如文件管理中请求打开文件、其他应用中分享文件或文本时，若选择由CloudControl处理，则触发相应任务运行。

推荐使用addBroadcastIntentTask和addActivityIntentTask，而非直接使用本函数添加任务。

参数

名称	类型
task	IntentTaskConfig

返回值

Promise<Task>

---

addOneTimeTask

▸ addOneTimeTask(task): Promise<Task>

此函数会新增一个一次性的定时任务，任务在执行一次后将在定时任务中自动删除。

例如创建一个2021年5月21日13点14分运行的定时任务。

示例

"nodejs";
const { addOneTimeTask } = require("work_manager");
addOneTimeTask({
    path: "/sdcard/to/script.js",
    time: new Date(2021, 5, 21, 13, 14, 0),
}).then(task => console.log(task));

参数

名称	类型
task	TimedTaskConfig

返回值

Promise<Task>

---

addWeeklyTask

▸ addWeeklyTask(task): Promise<Task>

新增一个按星期运行的定时任务。

例如创建一个每周一周二下午1点14分的定时任务

示例

"nodejs";
const { addWeeklyTask } = require("work_manager");
addWeeklyTask({
    path: "/sdcard/脚本/test.js",
    // Mon Jun 21 2021 13:14:00 GMT+0800 
    time: 1624252440000,
    daysOfWeek: ['Monday', 'Tuesday'],
}).then(task => console.log(task));

参数

名称	类型	描述
task	WeeklyTaskConfig	用于描述此定时任务的配置

返回值

Promise<Task>

---

getIntentTask

▸ getIntentTask(id): Promise<Task | null>

根据任务id获取意图任务。

参见

Task.id

参数

名称	类型	描述
id	number	任务ID

返回值

Promise<Task | null>

查询的任务的Promise，如果没有找到则resolve null

---

getTimedTask

▸ getTimedTask(id): Promise<Task | null>

根据任务id获取定时任务。

参见

Task.id

参数

名称	类型	描述
id	number	任务ID

返回值

Promise<Task | null>

查询的任务的Promise，如果没有找到则resolve null

---

queryIntentTasks

▸ queryIntentTasks(query?): Promise<Task[]>

通过脚本路径或Intent Action等条件查询意图任务。

示例

"nodejs";
const { queryIntentTasks, addBroadcastIntentTask } = require("work_manager");
async function main() {
    const task = await addBroadcastIntentTask({
        path: "/sdcard/to/script.js",
        action: Intent.ACTION_BATTERY_CHANGED,
    });
    // Query all intent tasks
    const tasks = await queryIntentTasks();
    console.log(tasks);
}
main();

参数

名称	类型	描述
query?	IntentTaskQuery	intent任务查询条件，为空则查询所有任务

返回值

Promise<Task[]>

---

queryTimedTasks

▸ queryTimedTasks(query?): Promise<Task[]>

通过脚本路径等条件查询定时任务。

示例

"nodejs";
const work_manager = require('work-manager');

const file = "/path/to/script.js";
async function main() {
const task = await work_manager.addWeeklyTask({
    path: file,
    time: 1624252440000,
    daysOfWeek: ['Sunday'],
});
const tasks = await work_manager.queryTimedTasks({
    path: file
});
tasks.forEach(t => {
    console.log("delete:", t);
    console.log(await work_manager.removeTimedTask(t.id));
});
}

#### 参数

| 名称 | 类型 | 描述 |
| :------ | :------ | :------ |
| `query?` | [`TimedTaskQuery`](../interfaces/work_manager.TimedTaskQuery.md) | 定时任务查询条件，为空则查询所有任务 |

#### 返回值

`Promise`<`Task`[]\>

___

### removeIntentTask

▸ **removeIntentTask**(`id`): `Promise`<`boolean`\>

通过任务id删除一个意图任务。

**`参见`**

Task.id

#### 参数

| 名称 | 类型 | 描述 |
| :------ | :------ | :------ |
| `id` | `number` | 任务id |

#### 返回值

`Promise`<`boolean`\>

Promise，表示是否删除成功，若对应的任务不存在，则resolve false，否则resolve true

___

### removeTimedTask

▸ **removeTimedTask**(`id`): `Promise`<`boolean`\>

通过任务id删除一个定时任务。

**`参见`**

Task.id

#### 参数

| 名称 | 类型 | 描述 |
| :------ | :------ | :------ |
| `id` | `number` | 任务id |

#### 返回值

`Promise`<`boolean`\>

Promise，表示是否删除成功，若对应的任务不存在，则resolve false，否则resolve true