AutoJs6

- Overview - 综述
- About - 关于文档
- Progress - 文档部署进度
- Changelog - 文档更新日志

- Manual - AutoJs6 使用手册
- Q & A - 疑难解答

- Global - 全局对象
- Automator - 自动化
- AutoJs6 - 本体应用
- App - 通用应用
- Color - 颜色
- Image - 图像
- OCR - 光学字符识别
- Barcode - 条码
- QR Code - 二维码
- Keys - 按键
- Device - 设备
- Storage - 储存
- File - 文件
- Engine - 引擎
- Task - 任务
- Module - 模块
- Plugins - 插件
- Toast - 消息浮动框
- Notice - 消息通知
- Console - 控制台
- Shell
- Shizuku
- Media - 多媒体
- Sensor - 传感器
- Recorder - 记录器
- Timer - 定时器
- Thread - 线程
- Continuation - 协程
- Event - 事件监听
- Dialog - 对话框
- Floaty - 悬浮窗
- Canvas - 画布
- UI - 用户界面
- Web - 万维网
- HTTP
- Base64
- Crypto - 密文
- OpenCC - 中文转换
- Internationalization - 国际化
- Standardization - 标准化
- E4X

- UiSelector - 选择器
- UiObject - 控件节点
- UiObjectCollection - 控件集合
- UiObjectActions - 控件节点行为
- WebSocket
- EventEmitter - 事件发射器
- ImageWrapper - 包装图像类
- App - 应用枚举类
- Color - 颜色类
- Version - 版本工具类
- Polyfill - 代码填泥
- Arrayx - Array 扩展
- Numberx - Number 扩展
- Mathx - Math 扩展

- Exceptions - 异常
- Intent - 意图
- Runtime - 运行时
- Context - 上下文
- Activity - 活动

- Scripting Java - 脚本化 Java
- Android API Level - 安卓 API 级别
- Color Table - 颜色列表

- Glossaries - 术语
- HttpHeader - HTTP 标头
- HttpRequestMethods - HTTP 请求方法
- MimeType - MIME 类型
- NotificationChannel - 通知渠道

- Data Types - 数据类型
- Omnipotent Types - 全能类型
- Storage - 存储类
- AndroidBundle
- AndroidRect
- CryptoCipherOptions
- CryptoKey
- CryptoKeyPair
- ConsoleBuildOptions
- HttpRequestBuilderOptions
- HttpRequestHeaders
- HttpResponseBody
- HttpResponseHeaders
- HttpResponse
- InjectableWebClient
- InjectableWebView
- NoticeOptions
- NoticeChannelOptions
- NoticePresetConfiguration
- NoticeBuilder
- Okhttp3HttpUrl
- OcrOptions
- Okhttp3Request
- OpenCVPoint
- OpenCVRect
- OpenCVSize
- OpenCCConversion

- GitHub - 应用项目地址
- GitHub - 文档项目地址

# 关于文档 (About)#

AutoJs6 文档, 包含模块 API 使用方法及用例.
项目复刻 (Fork) 自 hyb1996/AutoJs-Docs (GitHub).
项目地址: SuperMonster003/AutoJs6-Documentation (GitHub).

## 文档阅读示例#

### 基础#

#### device.height#

device 表示全局对象 (这里同时也是一个模块).
".height" 表示访问 device 对象的 height 成员变量.
如 console.log(device.height) 表示在控制台打印当前设备的高度数值.

#### colors.rgb(red, green, blue)#

colors 与 device 类似, 表示全局对象.
"rgb" 表示方法名称, ".rgb()" 表示调用 colors 的 rgb 方法, 括号内的 red 等表示方法参数.
如 console.log(colors.rgb(255, 128, 64)) 表示在控制台打印一个 RGB 分别为 255, 128 和 64 的颜色数值.

> 注: 绝大多数情况, 文档不对 "函数" 与 "方法" 做明确区分.

### 临时作用域对象#

通常每个章节都以某个对象作为主题.

例如上述 `colors.rgb(red, green, blue)` 位于 Color - 颜色 这个章节.
其中 colors 称为此章节的 "临时作用域对象",
它可能是一个对象, 函数, 甚至 "类", 在文档中使用 `橙色粗体` 表示.

列举其后续的相关方法及属性时, 将不再重复书写对象本身:

colors

[m] rgb

rgb(red, green, blue)

... ...

上述 `rgb` 表示 `colors.rgb`.

### 参数类型#

#### colors.rgb(red, green, blue)#

- red { number }
- green { number }
- blue { number }

参数后的 "{}" 内包含其类型.
上述示例表示需要传入三个 number 类型的参数.
如 colors.rgb(255, 128, 64) 合法, 而 colors.rgb("abc", 128, 64) 将可能导致非预期结果或出现异常.

> 注: 点击类型对应的超链接 (如有) 可跳转至类型详情页面.

### 返回值类型#

#### colors.rgb(red, green, blue)#

- red { number }
- green { number }
- blue { number }
- returns { number }

returns 后的 "{}" 内包含返回值类型.
上述示例表示 colors.rgb 方法调用后将返回 number 类型数据.

### 属性类型#

#### colors.RED#

- { number }

属性类型包裹在一对花括号中.
上述示例表示 colors 的 RED 属性是 number 类型数据.

对象字面量形式的类型则用一对双花括号表示:

- properties { { name: string; age: number }}

多行形式:

- properties {{
  - name: string;
  - age: number;
  - laugh(decibel?: number);
- }}

一个符合上述示例期望的变量:

    let o = { name: "David", age: 13 };

可存取的属性在读取时如果有非 undefined 默认值, 则以一对方括号表示:

- [ `1200` ] { number }

上述示例表示一个默认值为 1200 的可存取属性.

以一对双方括号表示常量:

- [[ 0.5 ]] { number }

上述示例表示一个值为 0.5 的常量属性.

### 方法签名#

形如上述 返回值类型 小节的示例,
包含 [ 方法名称 + 参数类型 + 返回值类型 ] 的标志符, 称为 "方法签名".

> 注: 上述 "方法签名" 定义只用于辅助读者对文档的理解, 并不保证名词解释的合理性.

### 方法描述#

#### colors.rgb(red, green, blue)#

- red - R (红色) 通道数值 [ A ]
- green - G (绿色) 通道数值 [ A ]
- blue - B (蓝色) 通道数值 [ A ]
- @return - 颜色数值 [ B ]

获取 R/G/B 通道组合后的颜色数值. [ C ]

    [ D ]
    colors.rgb(255, 128, 64); // -32704
    colors.rgb(255, 128, 64) === 0xFFFF8040 - Math.pow(2, 32); // true
    colors.rgb(255, 128, 64) === colors.toInt("#FFFF8040"); // true
    colors.rgb(255, 128, 64) === colors.toInt("#FF8040"); // true

上述示例包含的字母标注含义:

- [ A ] - 参数描述
- [ B ] - 方法返回值描述
- [ C ] - 方法描述
- [ D ] - 方法使用示例

### 可变参数#

#### files.join(parent, ...child)#

上述示例的 child 参数是 "可变参数", 也称为 "可变长参数" 或 "变长参数".
可变参数可传入任意个 (包括 0 个) 参数:

    let p = files.getSdcardPath();
    files.join(p); /* 0 个可变参数 */
    files.join(p, 'a'); /* 1 个可变参数 */
    files.join(p, 'a', 'b', 'c', 'd'); /* 4 个可变参数 */

文档采用 JSDoc 标准标注可变参数, 需额外注意 JSDoc 的尾数组标识代表容器, 用于容纳展开后的参数:

    /**
     * @param {number} x
     * @param {number} y
     * @param {...number[]} others
     */
    function sum(x, y, others) {
        /* ... */
    }

上述示例 others 参数为可变参数, 其中 "...number[]" 代表 others 期望的参数类型为 number, 而非 number[], 最后的 "[]" 代表 "..." 的容器, "..." 与 "[]" 是配对出现的.

    /**
     * @param {number} x
     * @param {number} y
     * @param {...number[][]} others
     */
    function sum(x, y, others) {
        /* ... */
    }

上述示例 others 期望的参数类型为 number[], 而非 number[][], 同样最后的 "[]" 代表 "..." 的容器.

    /**
     * @param {number} x
     * @param {number} y
     * @param {...number} others
     */
    function sum(x, y, others) {
        /* ... */
    }

上述示例 others 的参数类型标识方法 "...number" 也是合法的, 它其实是 "...number[]" 的省略形式.
文档为了避免歧义, 将全部采用完整写法.

作为强调, "...(SomeType)[]" 这样的可变参数表示方法, 需要把 "..." 和 "[]" 视为一个整体, 中间部分才是期望的参数类型.

### 可选参数#

#### device.vibrate(text, delay?)#

上述示例的 delay 参数是可选的 (以 "?" 标注).
因此以下调用方式均被支持:

    device.vibrate("hello", 2e3); /* 两秒钟延迟. */
    device.vibrate("hello"); /* 无延迟. */

可选参数描述时会以 "[]" 标注:

- [ delay ] { number }

如果可选参数包含默认值, 则会以 "=" 标注:

- [ delay = 0 ] { number }

详见下述 参数默认值

### 参数默认值#

#### device.vibrate(text, delay?)#

- text { string } - 需转换为摩斯码的文本
- [ delay = 0 ] { number } - 振动延迟
- returns { void }

上述示例的 delay 参数是可选的 (以 "?" 标注) 且包含默认值 (以 "=" 标注).
因此以下两种调用方式等效:

    device.vibrate("hello");
    device.vibrate("hello", 0);

> 注: 上述示例的方法签名 (含默认值标注) 在 TypeScript 中并不合法, 此类签名仅限在文档中使用.

> 注: 以 "=" 标注的参数一定是可选的, 此时参数的 "?" 标注可能被省略, 尤其在重载签名拆写的情况下.
> 详情参阅下文的 "方法重载".

### 方法重载#

`Overload 1/17`

#### pickup(selector, compass, resultType)#

`Overload 2/17`

#### pickup(selector, compass)#

`Overload 3/17`

#### pickup(selector, resultType)#

... ...

`Overload 16/17`

#### pickup(root, selector)#

`Overload 17/17`

#### pickup()#

包含 "Overload m/n" 标签的方法, 表示重载方法的序数及总量.
如 "Overload 2/3" 表示当前方法签名描述第 2 个重载方法, 总计 3 个,
而 "Overload 5-6/17" 表示当前方法签名涵盖第 5 及 第 6 个重载方法, 总计 17 个.

重载方法可被简化:

    /* 拆写. */
    device.vibrate(text)
    device.vibrate(text, delay)

    /* 合写 (简化). */
    device.vibrate(text, delay?)

    /* 可选参数通常会标注默认值. */
    device.vibrate(text, delay?)
    · [ delay = 0 ] { number }

    /* 即使没有 "?" 标注 (针对拆写). */
    device.vibrate(text, delay)
    · [ delay = 0 ] { number }

多数情况下, 文档采用拆写的方式描述重载方法.

### 方法全局化#

`Global`

#### images.requestScreenCapture(landscape)#

包含 "Global" 标签的方法, 表示支持全局化使用, 可省略模块对象调用.
因此以下两种调用方式等效:

    images.requestScreenCapture(false);
    requestScreenCapture(false);

### 方法标签#

用于简便表示方法的特性:

- `Global`: 方法全局化 (可省略模块对象直接调用).
- `Overload 2/3`: 方法重载 [ 第 2 个, 共 3 个 ].
- `Non-UI`: 方法不能在 UI 模式下调用.
- `6.2.0`: 方法对 AutoJs6 的版本要求 [ 不低于 6.2.0 ].
- `[6.2.0]`: 与原同名方法相比, 方法的功能, 结果, 签名或使用方式发生变更的起始版本.
- `API>=29`: 方法对 API 级别 的要求 [ 不低于 29 ], 当不满足时不抛出异常.
- `API>=29!`: 方法对 API 级别 的要求 [ 不低于 29 ], 当不满足时将抛出异常.
- `A11Y`: 方法依赖无障碍服务.
- `A11Y?`: 方法可能会依赖无障碍服务.
- `Async`: 异步执行的方法.
- `Async?`: 可能异步执行的方法 (通过参数控制).
- `Getter`: 仅取值属性, 即使用 Getter 定义的对象属性.
- `Setter`: 仅存值属性, 即使用 Setter 定义的对象属性.
- `Getter/Setter`: 可存值且可取值属性, 即同时使用 Setter 及 Getter 定义的对象属性.
- `Enum`: 枚举类.
- `CONSTANT`: 常量.
- `READONLY`: 只读属性或方法.
- `DEPRECATED`: 已弃用的属性或方法. 表示不推荐使用, 通常会有替代属性或替代方法.
- `ABANDONED`: 已废弃的属性或方法. 表示不再提供功能支持, 使用后功能将无效.
- `xProto`: 针对原型的内置对象扩展.
- `xObject`: 针对对象的内置对象扩展.
- `xAlias`: 内置对象扩展时使用不同的方法或属性名称 (别名).

### 对象标签#

用于简便表示对象的属性:

- [m]: 普通对象方法或类静态成员方法.
  - 例如在 `images` 作为 临时作用域对象 时:
  - `[m] captureScreen` 代表 `images.captureScreen` 方法.
- [m+]: 具有扩展属性的对象方法.
  - 如 auto 本身是一个方法 (或称函数), waitFor 是 auto 的一个扩展方法.
  - 以下两种调用方式均可用: `auto()` 及 `auto.waitFor()`.
- [p]: 普通对象属性或类静态成员属性或接口变量属性.
  - 例如在 `device` 作为 临时作用域对象 时:
  - `[p] height` 代表 `device.height` 属性, 而非方法.
  - 此标签对 [ Getter / Setter / "类" 属性 / 对象属性 / 方法扩展属性 ] 等不作区分.
- [p+]: 具有扩展属性的对象属性.
  - 如 autojs 是一个对象, version 是 autojs 的扩展属性,
  - 支持 `autojs.version.xxx` 这样的访问方式,
  - 因此 version 属性将被标记为 `[p+]`.
- [I]: Java 接口.
- [C]: Java 类或 JavaScript 构造函数.
- [c]: Java 类的构造方法.
- [m!]: 抽象方法 (针对接口及抽象类).
- [m=]: 包含默认实现的抽象方法 (针对接口).
- [m#]: 类的实例成员方法.
  - 类的静态成员方法用 [m] 标签标记.
  - 例如对于类 `B`, 它有一个实例 `b` (可能通过 `new B()` 等方式获得),
  - `[m#] foo` 和 `[m] bar` 的调用方式分别为
  - `b.foo()` 和 `B.bar()`.
- [p#]: 类的实例成员属性.
  - 类的静态成员属性依然用 [p] 标签标记.
  - 例如对于类 `F`, 它有一个实例 `f` (可能通过 `new F()` 等方式获得),
  - `[p#] foo` 和 `[p] bar` 的调用方式分别为
  - `f.foo` 和 `F.bar`.
- [@]: 代表 临时作用域对象 自身.
  - 例如在同一个章节中
    - `[@] apple` [1]
    - `apple(c)` [2]
    - `[m] getColor` [3]
    - `getColor()` [4]
    - `[@] banana` [5]
    - `[m] banana` [6]
    - `banana(x)` [7]
    - `banana(x, y)` [8]
  - 这个章节有两个 临时作用域对象, apple 和 banana, 对应 `[1]` 和 `[5]`.
  - `[2]` 代表 apple 自身可被调用, 且调用方式为 `apple(c)`, 其中 "c" 为参数.
  - `[3]` 代表 apple 的一个方法, 名称为 "getColor",
  - 由 `[4]` 得知, 其调用方式为 `apple.getColor()`.
  - 注意 `[6]` 与 `[2]` 不同:
  - `[6]` 代表 banana 的一个方法, 名称为 "banana",
  - 由 `[7]` 和 `[8]` 得知, 其调用方式有两种,
  - `banana.banana(x)` 和 `banana.banana(x, y)`.

### 成员访问#

成员访问用 "." 表示调用关系, 包括 "类" 静态成员访问, 对象成员访问等.
而实例成员访问则需要 "类" 的实例才能访问, 用 "#" 表示调用关系.
例如 JavaScript 的 Number 本身是一个 "类", 可用的成员访问方式如下:

    Number(2); /* 作为普通函数使用, 无成员访问. */
    Number.EPSILON; /* "类" 静态成员访问, 用 "Number.EPSILON" 标识, 标签为 "[p]". */
    new Number(2); /* 创建 "类" 实例, 无成员访问. */
    new Number(2).toFixed(0); /* 实例成员访问, 用 "Number#toFixed(number)" 标识, 标签为 "[m#]". */

实例成员访问示例:

UiObject

[m#] bounds()

    /* 正确访问示例 */

    let w = pickup(/.+/); /* w 是 UiObject 的实例. */
    if (w !== null) {
        console.log(w.bounds()); /* 访问 UiObject 实例的 bounds 方法. */
    }

    /* 错误访问示例 */

    importClass(org.autojs.autojs.core.automator.UiObject);
    console.log(UiObject.bounds()); /* 访问的是类 UiObject 的静态方法 bounds. */

### 模板参数#

#### foo.bar(a, b)#

- a { T }
- b { number }
- returns { T }
- template { T }

template 标签指示了一个模板参数 `T`, 这个参数可以代表任意一个类型, 如 `string`.

示例 `foo.bar(a, b)` 中, 返回值与参数 `a` 的类型均为 `T`, 因此两者的类型相同.

例如当参数 `a` 传入 `string` 类型时, 返回值也为 `string` 类型:

    typeof foo.bar('hello', 3); // string

> 参阅: 泛型

## 声明#

当前项目 (文档) 及 AutoJs6 (App) 均为二次开发.
相对于 原始 App, 二次开发的 App 中会增加或修改部分模块功能.
相对于 原始文档, 二次开发的文档将进行部分增删或重新编写.
开发者无法保证对 API 的完全理解及文档的无纰漏撰写.
如有任何不当之处, 欢迎提交 Issue 或 PR.