系统模块（system）

system.launchApp - 启动应用

typescript

function system.launchApp(
 bundleId: string, // 应用 Bundle ID
): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
bundleId	string	是	-	要启动的应用 Bundle ID（按 Bundle ID 启动目标应用）

返回值：

类型	描述
`Promise<boolean>`	成功 `true`；失败 `false`

示例：

javascript

let launchOk = system.launchApp('com.apple.Preferences');
if (launchOk) {
 logger.debug('启动应用 system.launchApp 成功：', launchOk);
}else{
 logger.debug('启动应用 system.launchApp 失败：', launchOk);
}

system.stopApp - 停止应用

typescript

function system.stopApp(
 bundleId: string,
): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
bundleId	string	是	-	要停止的应用 Bundle ID（按 Bundle ID 停止目标应用）

返回值：

类型	描述
`Promise<boolean>`	成功 `true`；失败 `false`

示例：

javascript

let stopOk = system.stopApp('com.example.app');
if (stopOk) {
 logger.debug('停止应用 system.stopApp 成功：', stopOk);
}else{
 logger.debug('停止应用 system.stopApp 失败：', stopOk);
}

system.bringAppToForeground - 切到前台

typescript

function system.bringAppToForeground(
 bundleId: string,
): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
bundleId	string	是	-	目标应用 Bundle ID（将指定应用切换到前台）

返回值：

类型	描述
`Promise<boolean>`	成功 `true`；失败 `false`

示例：

javascript

let fgOk = system.bringAppToForeground('com.apple.mobilesafari');
if (fgOk) {
 logger.debug('切到前台 system.bringAppToForeground 成功：', fgOk);
}else{
 logger.debug('切到前台 system.bringAppToForeground 失败：', fgOk);
}

system.getForegroundApp - 当前前台应用

typescript

function system.getForegroundApp(): Promise<{
 bundleId: string;
 name: string;
 pid: number;
} | null>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数

返回值：

类型	描述
`Promise<SystemForegroundApp	null>`

返回字段（非 null 时）：

字段名	类型	是否必填	默认值	描述
bundleId	string	是	-	应用 Bundle ID / 包名
name	string	是	-	应用显示名（iOS 可能回退自 label）
pid	number	是	-	进程 ID；未知时可能为 `0`

示例：

javascript

let app = system.getForegroundApp();
if (app) {
 logger.debug('当前前台 system.getForegroundApp：', app.bundleId, app.name, app.pid);
}else{
 logger.debug('当前前台 system.getForegroundApp：null');
}

system.isLocked - 是否锁屏

typescript

function system.isLocked(): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数（查询设备是否处于锁屏状态）

返回值：

类型	描述
`Promise<boolean>`	`true` 已锁屏；`false` 未锁屏

示例：

javascript

let locked = system.isLocked();
if (locked) {
 logger.debug('是否锁屏 system.isLocked：已锁屏', locked);
}else{
 logger.debug('是否锁屏 system.isLocked：未锁屏', locked);
}

system.lockScreen - 锁屏

typescript

function system.lockScreen(): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数

返回值：

类型	描述
`Promise<boolean>`	成功 `true`；失败 `false`

示例：

javascript

let lockOk = system.lockScreen();
if (lockOk) {
 logger.debug('锁屏 system.lockScreen 成功：', lockOk);
}else{
 logger.debug('锁屏 system.lockScreen 失败：', lockOk);
}

system.unlockScreen - 解锁

typescript

function system.unlockScreen(): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数

返回值：

类型	描述
`Promise<boolean>`	成功 `true`；失败 `false`

示例：

javascript

let unlockOk = system.unlockScreen();
if (unlockOk) {
 logger.debug('解锁 system.unlockScreen 成功：', unlockOk);
}else{
 logger.debug('解锁 system.unlockScreen 失败：', unlockOk);
}

system.setClipboardText - 写入剪贴板

typescript

function system.setClipboardText(
 text: string,
): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
text	string	是	-	要写入的文本（常需相关应用在前台或具备剪贴板权限）

返回值：

类型	描述
`Promise<boolean>`	成功 `true`；失败 `false`

示例：

javascript

let clipWriteOk = system.setClipboardText('hello');
if (clipWriteOk) {
 logger.debug('写入剪贴板 system.setClipboardText 成功：', clipWriteOk);
}else{
 logger.debug('写入剪贴板 system.setClipboardText 失败：', clipWriteOk);
}

system.getClipboardText - 读取剪贴板

typescript

function system.getClipboardText(): Promise<string | null>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数（无文本或不可读时返回 `null`）

返回值：

类型	描述
`Promise<string	null>`

示例：

javascript

let clip = system.getClipboardText();
if (clip !== null) {
 logger.debug('读取剪贴板 system.getClipboardText：', clip);
}else{
 logger.debug('读取剪贴板 system.getClipboardText：null');
}

system.openUrl - 打开链接或 Scheme

typescript

function system.openUrl(
 url: string,
): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
url	string	是	-	完整 URL 或 Scheme（支持 `http(s)` 与自定义 Scheme）

返回值：

类型	描述
`Promise<boolean>`	成功调起 `true`；失败 `false`

示例：

javascript

let urlOk = system.openUrl('https://www.apple.com');
if (urlOk) {
 logger.debug('打开链接 system.openUrl 成功：', urlOk);
}else{
 logger.debug('打开链接 system.openUrl 失败：', urlOk);
}

system.postNotification - 系统通知

typescript

function system.postNotification(
 message: string,
 title?: string,
 notificationId?: string,
): Promise<void>;

参数说明：

参数名	类型	是否必填	默认值	描述
message	string	是	-	通知正文
title	string	否	-	通知标题
notificationId	string	否	-	通知标识；相同 id 可用于更新同一条通知

返回值：

类型	描述
`Promise<void>`	发送完成后 resolve（无业务返回值）

示例：

javascript

system.postNotification('完成', '任务', 'task_done');

system.getMemoryUsage - 内存概览

typescript

function system.getMemoryUsage(): Promise<{
 used: number;
 available: number;
 total: number;
 usagePercentage: number;
}>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数

返回值：

类型	描述
`Promise<SystemMemoryUsage>`	内存概览对象（字段见下表）

返回字段：

字段名	类型	是否必填	默认值	描述
used	number	是	-	已用内存（MB）
available	number	是	-	可用内存（MB）
total	number	是	-	总内存（MB）
usagePercentage	number	是	-	使用百分比，范围约 0～100

示例：

javascript

let m = system.getMemoryUsage();
logger.debug('内存 system.getMemoryUsage used/mb', m.used, 'pct', m.usagePercentage);

system.getUsedMemoryMb - 已用内存（MB）

typescript

function system.getUsedMemoryMb(): Promise<number>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数

返回值：

类型	描述
`Promise<number>`	当前已使用内存（MB）

示例：

javascript

let u = system.getUsedMemoryMb();
logger.debug('已用内存 system.getUsedMemoryMb：', u);

system.getAvailableMemoryMb - 可用内存（MB）

typescript

function system.getAvailableMemoryMb(): Promise<number>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数

返回值：

类型	描述
`Promise<number>`	当前可用内存（MB）

示例：

javascript

let a = system.getAvailableMemoryMb();
logger.debug('可用内存 system.getAvailableMemoryMb：', a);

system.getTotalSystemMemoryMb - 总内存（MB）

typescript

function system.getTotalSystemMemoryMb(): Promise<number>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数

返回值：

类型	描述
`Promise<number>`	设备总内存（MB）

示例：

javascript

let t = system.getTotalSystemMemoryMb();
logger.debug('总内存 system.getTotalSystemMemoryMb：', t);

system.startAgentService - 启动自动化服务

typescript

function system.startAgentService(): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数（启动宿主侧自动化 / Agent 类服务，若宿主提供）

返回值：

类型	描述
`Promise<boolean>`	成功 `true`；失败 `false`

示例：

javascript

let startAgentOk = system.startAgentService();
if (startAgentOk) {
 logger.debug('启动自动化服务 system.startAgentService 成功：', startAgentOk);
}else{
 logger.debug('启动自动化服务 system.startAgentService 失败：', startAgentOk);
}

system.stopAgentService - 停止自动化服务

typescript

function system.stopAgentService(): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数（停止宿主侧自动化服务，若宿主提供）

返回值：

类型	描述
`Promise<boolean>`	成功 `true`；失败 `false`

示例：

javascript

let stopAgentOk = system.stopAgentService();
if (stopAgentOk) {
 logger.debug('停止自动化服务 system.stopAgentService 成功：', stopAgentOk);
}else{
 logger.debug('停止自动化服务 system.stopAgentService 失败：', stopAgentOk);
}

system.getAgentRunning - 自动化服务是否在运行

typescript

function system.getAgentRunning(): Promise<boolean>;

参数说明：

参数名	类型	是否必填	默认值	描述
（无）	-	-	-	无参数（查询由 `startAgentService` / `stopAgentService` 管理的服务是否运行）

返回值：

类型	描述
`Promise<boolean>`	`true` 运行中；`false` 未运行

示例：

javascript

let agentOn = system.getAgentRunning();
if (agentOn) {
 logger.debug('自动化服务 system.getAgentRunning：运行中', agentOn);
}else{
 logger.debug('自动化服务 system.getAgentRunning：未运行', agentOn);
}

（补充）system.* 的编辑器类型补全

typescript

// 扩展根据设置同步声明，非设备运行时 API

参数说明：

参数名	类型	是否必填	默认值	描述
wda.script.autoInstallTypings	boolean	-	默认开启	开启时通过 TypeScript 插件注入扩展内 `script-typings` 补全（不再写入工作区 `typings/autoclick-bridge/`）；关闭则不注入；若存在旧版生成目录会自动清理
wda.script.verboseBridgeLog	boolean	-	默认关闭	输出「Auto Click E」显示详细桥接过程（成功 ack、执行完成、模板缓存跳过、`__CIT_JSON__`）。关闭时脚本运行仅保留一行摘要、脚本 logger 与错误
关闭自动安装	-	-	-	可在脚本顶部手写 `/// <reference path="…/systemModule.d.ts" />`

返回值：

类型	描述
—	无（编辑器配置说明）

示例：

javascript

let ok = system.launchApp('com.apple.Preferences');
if (ok) {
 logger.debug('launch', ok);
}else{
 logger.debug('launch fail', ok);
}
const app = system.getForegroundApp();
logger.debug('foreground', app);
system.postNotification('完成', '任务', 'task_done');

系统模块（system） ​

system.launchApp - 启动应用 ​

system.stopApp - 停止应用 ​

system.bringAppToForeground - 切到前台 ​

system.getForegroundApp - 当前前台应用 ​

system.isLocked - 是否锁屏 ​

system.lockScreen - 锁屏 ​

system.unlockScreen - 解锁 ​

system.setClipboardText - 写入剪贴板 ​

system.getClipboardText - 读取剪贴板 ​

system.openUrl - 打开链接或 Scheme ​

system.postNotification - 系统通知 ​

system.getMemoryUsage - 内存概览 ​

system.getUsedMemoryMb - 已用内存（MB） ​

system.getAvailableMemoryMb - 可用内存（MB） ​

system.getTotalSystemMemoryMb - 总内存（MB） ​

system.startAgentService - 启动自动化服务 ​

system.stopAgentService - 停止自动化服务 ​

system.getAgentRunning - 自动化服务是否在运行 ​

（补充）system.* 的编辑器类型补全 ​

系统模块（system）

system.launchApp - 启动应用

system.stopApp - 停止应用

system.bringAppToForeground - 切到前台

system.getForegroundApp - 当前前台应用

system.isLocked - 是否锁屏

system.lockScreen - 锁屏

system.unlockScreen - 解锁

system.setClipboardText - 写入剪贴板

system.getClipboardText - 读取剪贴板

system.openUrl - 打开链接或 Scheme

system.postNotification - 系统通知

system.getMemoryUsage - 内存概览

system.getUsedMemoryMb - 已用内存（MB）

system.getAvailableMemoryMb - 可用内存（MB）

system.getTotalSystemMemoryMb - 总内存（MB）

system.startAgentService - 启动自动化服务

system.stopAgentService - 停止自动化服务

system.getAgentRunning - 自动化服务是否在运行

（补充）system.* 的编辑器类型补全