快速上手
# 阅读须知
<!-- type=misc -->
本文档为Auto.js (Pro) 的文档，解释了Auto.js各个模块的API的使用方法、作用和例子。
文档借助Node.js的文档构建工具生成，并在github上开源(https://github.com/hyb1996/AutoJs-Docs )，目前由开发者维护。
# API稳定性
由于Auto.js处于活跃的更新和开发状态，API可能随时有变动，我们用Stability来标记模块、函数的稳定性。这些标记包括：
```txt
Stability: 0 - Deprecated
弃用的函数、模块或特性，在未来的更新中将很快会被移除或更改。应该在脚本中移除对这些函数的使用，以免后续出现意料之外的问题。
```
```txt
Stability: 1 - Experimental
实验性的函数、模块或特性，在未来的更新中可能会更改或移除。应该谨慎使用这些函数或模块，或者仅用作临时或试验用途。
```
```txt
Stability: 2 - Stable
稳定的函数、模块或特性，在未来的更新中这些模块已有的函数一般不会被更改，会保证后向兼容性。
```
# 如何阅读本文档
# 打包为应用
当我们完成代码后，可以将代码打包为独立apk。打包可以分为单文件打包、项目打包，其中单文件打包只能打包一个js文件，如果这个js文件依赖了其他的资源、代码文件，无法被打包进apk中，此时需要用项目打包。有关项目的功能请参考下一节“项目与打包”，这里我们重点介绍打包功能。
在文件列表中，点击需要打包的文件右边的更多图标（三个点），选择“打包单文件”。
进入打包界面。打包界面包含多个配置，你可以自定义权限、包名、应用名称等。调整后这些配置后，点击右下角的完成（√）图标，即可进行打包。
这里我们依次介绍关键的打包配置。
## 应用配置
- 应用名称：打包后应用安装后显示在桌面的名称
- 包名：应用的唯一标识符，相同包名和签名的安装包可以覆盖安装。包名只能包含字母、数字、下划线、英文点等，并且至少包含一个英文点，比如"com.example"。不合法的包名打包后无法安装，可能提示“安装包解析失败”。
- 版本名称：显示给用户的版本名称，比如"1.10.2"。
- 版本号：一个整数，代表内部版本号。每次更新版本时，需要增加这个整数。
- 图标：应用安装后显示在桌面的图标
- 权限：配置应用权限清单中的权限，默认为126个权限。你可以按需要配置权限，不同功能需要不同的权限：
1. 读写文件：需要READ_EXTERNAL_STORAGE，WRITE_EXTERNAL_STORAGE权限
1. 前台服务：需要FOREGROUND_SERVICE权限
1. 访问网络：需要INTERNET权限
1. 任务：需要WAKE_LOCK权限
1. 开机启动：需要RECEIVE_BOOT_COMPLETED权限
1. 悬浮窗：需要SYSTEM_ALERT_WINDOW权限
1. adb权限运行shell命令：需要moe.shizuku.manager.permission.API_V23权限
如果使用shizuku授权后，进行滑动，需要使用shell命令，只要把true改成{adb:true}
例如：shell("input swipe 300 500 300 800", { adb: true });
如果用到某些功能，但没有配置相应的权限，运行时可能报错。比如使用到前台服务，但是没有配置FOREGROUND_SERVICE权限，使用到相应功能时会崩溃。
权限还可配置为启动时自动申请，比如自动申请WRITE_EXTERNAL_STORAGE权限，则打包后应用启动后会弹出权限申请框。一些权限不可申请，只能在权限清单中配置。
## 特性
- 内置图标包：使用到内置图标，比如ic_add_black_48dp等，需要勾选此特性。
- 处理外部文件：使用到任务中的IntentTask（打开、编辑文件等），需要勾选此特性。勾选后，在文件管理器中打开一些文件，会提示使用打包的应用打开。
- Node.js引擎：是否使用Node.js引擎（第二代API）。Node.js引擎的体积较大，单架构达到十几MB。
1. 自动：自动根据打包的文件、项目中是否使用第二代API而决定
1. 禁用：一律禁用Node.js引擎
1. 启用：一律启用Node.js引擎
- 插件：当使用到MLKit OCR、FFMpeg等插件时，需要在这里勾选使用到的插件，插件才能被打包到apk中。内置OCR模块则无需在这里勾选插件。
## 构建配置
- 加密：选择加密等级。参考加密与级别说明。
- CPU架构：默认为当前设备的架构。CPU架构将影响软件的体积、兼容性、占用内存、允许速度，arm64-v8a架构速度更快、占用内存更高、且仅适用支持64位的机器，通常来说模拟器不支持arm64-v8a。如果要让软件兼容性更好，可以选择armeabi-v7a或者双架构。
- 混淆组件名称：是否将内置的组件（比如广播、Activity、服务）等名称随机化。勾选此选项后，打包时间将变得很长，并且务必打包时保持在前台，以保持较高的调度优先级。
## 运行配置
- 隐藏日志：打包后应用是否显示日志界面，当脚本有UI界面时此选项不生效。一般来说，建议脚本不要没有任何界面，否则一些依赖界面的功能会出现错误，或者是容易被系统杀死。
- 显示启动界面：是否显示启动界面，默认是软件图标的界面。即使设置为关闭，在首次启动时由于需要初始化，仍然会显示一次。
- 启动界面文本：默认为Powered by Auto.js Pro，可自定义文本内容。
- 启动界面图标：默认为软件图标。此图标不能铺满屏幕，如果你需要自定义，请使用自定义启动图功能。（参见应用内示例 -> 项目与打包 -> 自定义启动图）
## 签名
只有包名相同且签名相同的应用才能覆盖安装和升级。如果你需要持续更新某个应用，建议你使用自定义签名。因为默认签名是每次安装Auto.js Pro时随机生成的，一旦你卸载Auto.js Pro或者清除数据，默认签名将会丢失并且不能找回。签名丢失后，你更新应用重新打包后需要让用户卸载旧版本才能安装新版本。
要创建自定义签名，在签名管理中创建签名，输入密码、别名和别名密码即可创建。一个签名可以用于多个软件，每个软件用不同的别名和别名密码，但是Auto.js Pro自带的签名管理只支持创建一个别名。
签名文件、密码、别名、别名密码需要保存好，一旦丢失或忘记，没有任何途径可以找回。
# 项目与资源
当我们的代码越来越复杂时，我们可能需要编写多个js文件，文件之间互相调用；一些js文件也可能需要读取图片、音乐等资源文件。项目就是用来组织多个文件的文件夹，项目的文件夹中包含一个project.json文件，描述项目的配置，这个配置文件可以让你在打包时无需每次重新填写打包的信息。
通过Auto.js Pro的文件管理界面右下角的菜单，选择项目即可新建项目。创建时可选择不同的项目模板或者自定义模板，首次使用时选择空项目即可。
新建项目后将自动创建一个项目名称的文件夹，在该文件夹下可看到至少两个文件：
main.js：项目的主入口文件，运行项目时将执行该文件
project.json：项目的配置文件，配置项目的名称、包名、打包配置等
在项目中，我们所有使用的资源文件、模块文件都要放在项目的文件夹下，并用相对路径引用，才可以在打包时被打包进apk并正确运行。
例如我们写了一个模块文件sum.js：
```language
// sum.js
function sum(n) {
let result = 0;
for (let i = 0; i < n; i++) {
result += i;
}
return result;
}
module.exports = sum;
```
那么在main.js中，需要用相对路径引用：
```
// main.js
let sum = require('./sum.js');
console.log(sum(100));
```
同样地，资源文件也需要使用相对路径引用。比如我们的项目文件夹下有以下文件：
```
main.js
sum.js
apple.txt
project.json
```
在读取apple文本时，需要使用相对路径，比如let apple = $files.read('./apple.txt')。
## 项目管理与打包
打开项目的文件夹，可以看到上方工具栏有一个圆规图标：
项目管理
点击后弹出的菜单可编辑项目、打包项目、发布项目等。项目的打包和上一节的打包基本一样，这里不再阐述；发布项目将会上传项目到商店中，审核通过后，所有人都可以下载该项目。
# 项目配置文件
在Auto.js Pro中，我们有时不仅需要运行单文件，还有运行项目的需求。所谓项目，就是一个包含配置、代码文件、资源文件（图片等）的文件夹。
在Auto.js Pro中可以在主页新建项目，有多种项目模块可供选择(Pro 8.7以上)。
## project.json
project.json文件用于配置项目的相关参数，比如主文件、启动图、包名等信息。
|参数名称|意义|类型|
| ----------------- | ------ | ---------------------------------------- |
|androidResources|安卓资源，参见androidResources|Object|{"resDir": "res","manifest":"AndroidManifest.xml"}|
|build|自动生成的构建信息，无需修改，参见build|Object|
|assets|保留字段，暂时没有作用|string[]|[]|
|encryptLevel|加密级别 0-不加密, 1-本地加密, 2-在线加密(仅在8.7以上版本支持)|number|0|
|icon|桌面图标|string|"icons/icon.png"|
|ignore|从VSCode中同步项目时的忽略文件，在Pro9.3以上版本被.autojs.sync.ignore文件代替|string[]|["build"]|
|launchConfig|启动配置，参见launchConfig|Object|
|main|入口文件|string|"main.js"|
|name|app名字|string|""|
|optimization|优化配置，参见optimization|Object|
|packageName|包名，必须符合Android包名规范，另外上传商店时包名必须唯一|string|""|
|permissionConfig|权限配置，参见permissionConfig|Object|{"manifestPermissions": [],"requestListOnStartup": []}|
|publish|发布/上传商店配置，参见publish|Object|
|scripts|构建等时机自动触发运行的脚本配置，参见scripts|Object|
|useFeatures|特性 continuation - 是否使用协程特性，参见示例->协程|string[]|[]|
|versionCode|版本号|number|1|
|versionName|给用户看的版本名称|string|"1.0.0"|
完整配置实例：
```
{
"androidResources": {
"resDir": "res",
"manifest": "AndroidManifest.xml"
},
"assets": [],
"build": {
"build_id": "6F47F367-1",
"build_number": 1,
"build_time": 1615553004812,
"release": true
},
"encryptLevel": 0,
"useFeatures": [],
"icon": "res/icon.png",
"ignore": ["build"],
"launchConfig": {
"displaySplash": true,
"hideLogs": false,
"splashIcon": "res/splashIcon.png",
"splashLayoutXml": "splash.xml",
"splashText": "Powered by Auto.js Pro",
"stableMode": false
},
"main": "main.js",
"name": "Shape3.0",
"optimization": {
"removeOpenCv": true,
"unusedResources": true
},
"packageName": "com.suzy.rippledrawable",
"permissionConfig": {
"manifestPermissions": ["android.permission.WRITE_EXTERNAL_STORAGE"],
"requestListOnStartup": ["android.permission.WRITE_EXTERNAL_STORAGE"]
},
"publish": {
"category": "其他",
"details": "控件描边、渐变、水波纹、文字渐变",
"maxAutoJsVersion": -1,
"minAutoJsVersion": -1,
"maxProVersion": 8059999,
"minProVersion": 8050000,
"minSdkVersion": 2,
"permissions": [],
"summary": "控件描边、渐变、水波纹、文字渐变",
"tags": []
},
"scripts": {},
"versionCode": 1,
"versionName": "1.0.0"
}
```
最小配置实例：
```
{
"name": "新建项目",
"main": "main.js",
"ignore": [
"build"
],
"packageName": "com.example",
"versionName": "1.0.0",
"versionCode": 1
}
```
## androidResources
用于配置Android原生界面的参数，参见示例->复杂界面->Android 原生界面。
|参数名称 |意义| 类型|
| ----------------- | ------ | ---------------------------------------- |
|resDir |Android资源文件夹 |string |"res"|
|manifest |AndroidManifest.xml的文件路径 |string |"AndroidManifest.xml"|
## build
自动生成的构建信息，包含构建时间、构建号等，请勿修改。
打包软件中，将根据这里的信息判断是否需要解压覆盖安装包的文件到数据路径。（每次打包后这里的信心会更新，因此安装后可以自动更新本地数据中的项目文件）
|参数名称 |意义| 类型|
| ----------------- | ------ | ---------------------------------------- |
|build_id |自动生成的构建id| string| ""|
|build_number |构建号，每次构建自增1| number| 1|
|build_time| 上次构建时间 |number| 当前13位时间戳|
|release |是否为打包后项目，为自动生成的字段，不需要修改| boolean |false|
## launchConfig
打包后的相关启动配置。
|参数名称 |意义| 类型|
| ----------------- | ------ | ---------------------------------------- |
|displaySplash| 打包后是否显示启动图（即使设置为false，打包后第一次也仍然会显示启动图） |boolean |true|
|hideLogs |打包后是否隐藏日志界面 |boolean |false|
|splashIcon| 打包后启动界面图标 |string |"icons/splashIcon.png"|
|splashLayoutXml| 启动图xml，用于打包后自定义启动图，参见示例->项目与打包->自定义启动图 (8.5以上版本) |string| "splash.xml"|
|splashText |打包后启动界面文本 |string |"Powered by Auto.js Pro"|
|stableMode |打包后是否以稳定模式运行| boolean| false|
## permissionConfig
Pro 8.8.1新增
自定义权限配置，包括应用打包后声明的权限列表和启动时自动申请的权限列表。
也可以在打包界面中使用权限配置修改。
|参数名称 |意义| 类型|
| ----------------- | ------ | ---------------------------------------- |
|manifestPermissions| 打包后应用声明的权限列表。为了兼容旧版本配置，如果该字段为null则默认为122个自带权限。| string[] |null|
|requestListOnStartup |应用启动时自动申请的权限列表，权限务必包含在manifestPermissions中，否则会无法申请 |string[] |["android.permission.WRITE_EXTERNAL_STORAGE"]|
全部权限列表参见Android官方文档：Manifest.permissionopen in new window
## publish
上传商店发布项目的相关配置。
|参数名称 |意义| 类型|
| ----------------- | ------ | ---------------------------------------- |
|maxAutoJsVersion |支持的最大autojs版本号| number| 0|
|maxProVersion |支持的最大autojspro版本号| number |0|
|minAutoJsVersion| 支持的最小autojs版本号| number |0|
|minProVersion| 支持的最大autojspro版本号| number| 0|
|minSdkVersion| 支持的最小安卓版本 |number |0|
|category |项目类别，用于发布在商店时作为分类 |string |"其他"|
|details |项目详细描述，用于发布在商店时作为项目详情 |string |""|
|permissions |权限列表，比如"root"，暂时没有作用 |string[] |[]|
|summary |脚本功能简介 |string| ""|
|tags |脚本标签，由于商店还没有标签过滤功能，暂时没有作用| string[]| []|
## optimization
优化配置。目前用于打包时缩小体积。
|参数名称 |意义| 类型|
| ----------------- | ------ | ---------------------------------------- |
|removeOpenCv| 不需要图色模块| boolean |false|
|unusedResources| 不需要内置图标| boolean |false|
## ignore配置
Pro 8.7.6新增
ignore配置文件类似于.gitignore，用于配置Auto.js Pro处理打包、加密等忽略的文件。
ignore文件的规则和.gitignore相同，比如：
```
# / 表示 当前文件所在的目录
# 忽略public下的所有目录及文件
/public/
#不忽略/public/assets，就是特例的意思，assets文件不忽略
!/public/assets
# 忽略具体的文件
index.js
# 忽略所有的js文件
*.js
# 忽略 a.js b.js
[ab].js
# 匹配规则和linux文件匹配一样
# 以斜杠“/”开头表示目录
# 以星号“*”通配多个字符
# 以问号“?”通配单个字符
# 以方括号“[]”包含单个字符的匹配列表
# 以叹号“!”表示不忽略(跟踪)匹配到的文件或目录
```
# .autojs.source.ignore
文件路径：项目文件夹下.autojs.source.ignore文件。
该文件配置的规则所匹配的文件，将不视为Auto.js Pro的JavaScript源码文件，不参与加密过程。
例如有些js文件是用于Web中加载的，不希望在打包时将其加密，可以配置该文件来忽略。
# .autojs.build.ignore
文件路径：项目文件夹下.autojs.build.ignore文件。
该文件配置的规则所匹配的文件，将不参与Auto.js Pro的打包apk过程，最终生成的apk中，将不包含指定的文件。
例如有时node_modules仅在开发时使用，最终打包时已经通过webpack等工具打包为单文件，则可以配置忽略node_modules文件夹。
# .autojs.sync.ignore
文件路径：项目文件夹下.autojs.sync.ignore文件。
该文件配置的规则所匹配的文件，在VSCode插件运行、同步、保存电脑上的文件时，将被忽略。仅适用于Pro 9.3以上版本。
# scripts
scripts字段用于配置构建等时机自动执行的shell命令。例如：
```
{
// ...
"scripts": {
"build-apk-pre-prepare": "sh build.sh"
},
// ...
}
```
以上配置将在打包apk前自动运行build.sh脚本，从而可以在打包前进行自定义的文件替换、混淆等。在这些shell命令中，你可以用node build.js来执行js文件（纯Node.js环境）；目前暂不支持执行Auto.js环境的js脚本。
目前支持以下时机：
# 构建apk时触发
Auto.js Pro构建apk分为几个阶段：
- 准备阶段：拷贝项目文件、apk文件，处理源文件等
- 构建阶段：执行aapt编译，添加内置图标包，修改并写入Manifest文件、处理插件等
- 优化阶段：移除无用资源、模块、混淆组件等
- 打包阶段：签名、压缩、清理工作空间等
可以在不同阶段自定义要执行的sh脚本。在这些脚本中，可以通过以下环境变量获取信息：
- BUILD_APK_WORKSPACE: 构建的临时工作区，也就是解压apk的临时项目
- BUILD_APK_WORKSPACE_PROJECT: 工作区下的项目文件夹，项目将会被复制到这里
- BUILD_APK_OUTPUT：apk的目标输出路径
可以通过pwd等命令获取当前项目路径。
每个阶段对应的名称有：
- build-apk-pre-prepare: 准备阶段前触发
- build-apk-post-prepare: 准确阶段后触发
- build-apk-pre-build: 构建阶段前触发
- build-apk-post-build: 构建阶段后触发
- build-apk-pre-optimize: 优化阶段前触发
- build-apk-post-optimize: 优化阶段后触发
- build-apk-pre-package: 打包阶段前触发
- build-apk-post-package: 打包阶段后触发