快速上手
## 阅读须知
本文档为Auto.js (Pro) 的文档，解释了Auto.js各个模块的API的使用方法、作用和例子。
文档借助Node.js的文档构建工具生成，并在github上开源(https://github.com/hyb1996/AutoJs-Docs )，目前由开发者维护。
## API稳定性
由于Auto.js处于活跃的更新和开发状态，API可能随时有变动，我们用Stability来标记模块、函数的稳定性。这些标记包括：
Stability: 0 - Deprecated 弃用的函数、模块或特性，在未来的更新中将很快会被移除或更改。应该在脚本中移除对这些函数的使用，以免后续出现意料之外的问题。
Stability: 1 - Experimental 实验性的函数、模块或特性，在未来的更新中可能会更改或移除。应该谨慎使用这些函数或模块，或者仅用作临时或试验用途。
Stability: 2 - Stable 稳定的函数、模块或特性，在未来的更新中这些模块已有的函数一般不会被更改，会保证后向兼容性。
## 如何阅读本文档
## 打包为应用
当我们完成代码后，可以将代码打包为独立apk。打包可以分为单文件打包、项目打包，其中单文件打包只能打包一个js文件，如果这个js文件依赖了其他的资源、代码文件，无法被打包进apk中，此时需要用项目打包。有关项目的功能请参考下一节“项目与打包”，这里我们重点介绍打包功能。
在文件列表中，点击需要打包的文件右边的更多图标（三个点），选择“打包单文件”。
进入打包界面。打包界面包含多个配置，你可以自定义权限、包名、应用名称等。调整后这些配置后，点击右下角的完成（√）图标，即可进行打包。
这里我们依次介绍关键的打包配置。
### 应用配置
- 应用名称：打包后应用安装后显示在桌面的名称
- 包名：应用的唯一标识符，相同包名和签名的安装包可以覆盖安装。包名只能包含字母、数字、下划线、英文点等，并且至少包含一个英文点，比如"com.example"。不合法的包名打包后无法安装，可能提示“安装包解析失败”。
- 版本名称：显示给用户的版本名称，比如"1.10.2"。
- 版本号：一个整数，代表内部版本号。每次更新版本时，需要增加这个整数。
- 图标：应用安装后显示在桌面的图标
- 权限：配置应用权限清单中的权限，默认为126个权限。你可以按需要配置权限，不同功能需要不同的权限：
1. 读写文件：需要READ\_EXTERNAL\_STORAGE，WRITE\_EXTERNAL\_STORAGE权限
2. 前台服务：需要FOREGROUND\_SERVICE权限
3. 访问网络：需要INTERNET权限
4. 任务：需要WAKE\_LOCK权限
5. 开机启动：需要RECEIVE\_BOOT\_COMPLETED权限
6. 悬浮窗：需要SYSTEM\_ALERT\_WINDOW权限
7. 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而决定
2. 禁用：一律禁用Node.js引擎
3. 启用：一律启用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：
// 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 |
| build | 自动生成的构建信息，无需修改，参见build | Object |
| assets | 保留字段，暂时没有作用 | string[] |
| encryptLevel | 加密级别 0-不加密, 1-本地加密, 2-在线加密(仅在8.7以上版本支持) | number |
| icon | 桌面图标 | string |
| ignore | 从VSCode中同步项目时的忽略文件，在Pro9.3以上版本被.autojs.sync.ignore文件代替 | string[] |
| launchConfig | 启动配置，参见launchConfig | Object |
| main | 入口文件 | string |
| name | app名字 | string |
| optimization | 优化配置，参见optimization | Object |
| packageName | 包名，必须符合Android包名规范，另外上传商店时包名必须唯一 | string |
| permissionConfig | 权限配置，参见permissionConfig | Object |
| publish | 发布/上传商店配置，参见publish | Object |
| scripts | 构建等时机自动触发运行的脚本配置，参见scripts | Object |
| useFeatures | 特性 continuation - 是否使用协程特性，参见示例->协程 | string[] |
| versionCode | 版本号 | number |
| versionName | 给用户看的版本名称 | string |
完整配置实例：
{ "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 |
| manifest | AndroidManifest.xml的文件路径 | string |
### build
自动生成的构建信息，包含构建时间、构建号等，请勿修改。
打包软件中，将根据这里的信息判断是否需要解压覆盖安装包的文件到数据路径。（每次打包后这里的信心会更新，因此安装后可以自动更新本地数据中的项目文件）
| 参数名称 | 意义 | 类型 |
| --- | --- | --- |
| build\_id | 自动生成的构建id | string |
| build\_number | 构建号，每次构建自增1 | number |
| build\_time | 上次构建时间 | number |
| release | 是否为打包后项目，为自动生成的字段，不需要修改 | boolean |
### launchConfig
打包后的相关启动配置。
| 参数名称 | 意义 | 类型 |
| --- | --- | --- |
| displaySplash | 打包后是否显示启动图（即使设置为false，打包后第一次也仍然会显示启动图） | boolean |
| hideLogs | 打包后是否隐藏日志界面 | boolean |
| splashIcon | 打包后启动界面图标 | string |
| splashLayoutXml | 启动图xml，用于打包后自定义启动图，参见示例->项目与打包->自定义启动图 (8.5以上版本) | string |
| splashText | 打包后启动界面文本 | string |
| stableMode | 打包后是否以稳定模式运行 | boolean |
### permissionConfig
Pro 8.8.1新增
自定义权限配置，包括应用打包后声明的权限列表和启动时自动申请的权限列表。
也可以在打包界面中使用权限配置修改。
| 参数名称 | 意义 | 类型 |
| --- | --- | --- |
| manifestPermissions | 打包后应用声明的权限列表。为了兼容旧版本配置，如果该字段为null则默认为122个自带权限。 | string[] |
| requestListOnStartup | 应用启动时自动申请的权限列表，权限务必包含在manifestPermissions中，否则会无法申请 | string[] |
全部权限列表参见Android官方文档：Manifest.permissionopen in new window
### publish
上传商店发布项目的相关配置。
| 参数名称 | 意义 | 类型 |
| --- | --- | --- |
| maxAutoJsVersion | 支持的最大autojs版本号 | number |
| maxProVersion | 支持的最大autojspro版本号 | number |
| minAutoJsVersion | 支持的最小autojs版本号 | number |
| minProVersion | 支持的最大autojspro版本号 | number |
| minSdkVersion | 支持的最小安卓版本 | number |
| category | 项目类别，用于发布在商店时作为分类 | string |
| details | 项目详细描述，用于发布在商店时作为项目详情 | string |
| permissions | 权限列表，比如"root"，暂时没有作用 | string[] |
| summary | 脚本功能简介 | string |
| tags | 脚本标签，由于商店还没有标签过滤功能，暂时没有作用 | string[] |
### optimization
优化配置。目前用于打包时缩小体积。
| 参数名称 | 意义 | 类型 |
| --- | --- | --- |
| removeOpenCv | 不需要图色模块 | boolean |
| unusedResources | 不需要内置图标 | boolean |
### 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: 打包阶段后触发