更新canvas,plugins 文档

Author: aiselp

docs/plugins.md

@@ -0,0 +1,142 @@
+# 插件
+
+auto.js 提供了加载插件的机制，允许用户编写带有 Activity, Service, C/C++库等的 apk，安装到 Android 设备上，并用 Auto.js 加载和调用。
+
+一个插件是一个可独立安装的 apk 文件，用户安装后，再通过 `plugins` 模块加载插件和调用其中的 API。
+
+安装后可以使用以下代码来加载插件
+
+```js
+// packageName 为插件的包名，如果没有安装该插件则会抛出错误
+var plugin = plugins.load(packageName);
+```
+
+:::warning
+由于插件系统的设计缺陷，插件 APP 的目标 SDK 与 Autojs 不一致则可能出现兼容性异常
+:::
+
+## 开发一个插件
+
+:::info
+为了获得最佳兼容性，可将插件 APP 的目标 SDK 与最小 SDK 设置与 Autojs 一致
+:::
+
+### 插件 SDK 集成
+
+1. 新建一个 Android 项目，在项目的 build.gradle 文件中添加：
+
+```groovy
+allprojects {
+    repositories {
+        // ...
+        maven { url 'https://jitpack.io' }
+    }
+}
+```
+
+2. 在具体模块(比如 app)的 build.gradle 文件中添加：
+
+```groovy
+dependencies {
+    // ...
+    implementation 'com.github.hyb1996:Auto.js-Plugin-SDK:0.2'
+}
+```
+
+### 插件配置
+
+1. 新建 PluginHelloWorld 文件，继承于 Plugin.
+
+```java
+public class PluginHelloWorld extends Plugin {
+
+    public PluginHelloWorld(Context context, Context selfContext, Object runtime, Object topLevelScope) {
+        super(context, selfContext, runtime, topLevelScope);
+    }
+
+    // 返回插件的JavaScript胶水层代码的assets目录路径
+    @Override
+    public String getAssetsScriptDir() {
+        return "plugin-helloworld";
+    }
+
+    // 插件public API，可被JavaScript代码调用
+    public String getStringFromJava() {
+        return "Hello, Auto.js!";
+    }
+
+    // 插件public API，可被JavaScript代码调用
+    public void say(String message) {
+        getSelfContext().startActivity(new Intent(getSelfContext(),  HelloWorldActivity.class)
+                .putExtra("message", message)
+                .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
+    }
+}
+```
+
+2. 新增 MyPluginRegistry 文件，继承于 PluginRegistry:
+
+```java
+public class MyPluginRegistry extends PluginRegistry {
+
+    static {
+        // 注册默认插件
+        registerDefaultPlugin(new PluginLoader() {
+            @Override
+            public Plugin load(Context context, Context selfContext, Object runtime, Object topLevelScope) {
+                return new PluginHelloWorld(context, selfContext, runtime, topLevelScope);
+            }
+        });
+    }
+}
+```
+
+在 AndroidManifest.xml 中配置以下 meta-data, name 为"org.autojs.plugin.sdk.registry"，value 为 MyPluginRegistry 的包名。
+
+```xml {4-6}
+  <application
+        ...>
+
+        <meta-data
+            android:name="org.autojs.plugin.sdk.registry"
+            android:value="org.autojs.plugin.sdk.demo.MyPluginRegistry" />
+
+        <activity
+            android:name=".HelloWorldActivity"
+            android:exported="true" />
+
+        <service
+            android:name=".HelloworldPluginService"
+            android:exported="true" />
+    </application>
+```
+
+3. 编写 JavaScript 胶水层
+
+在 assets 的相应目录(由 Plugin.getAssetsScriptDir 返回)中添加 index.js 文件，用于作为胶水层导出插件 API。
+
+```js
+module.exports = function (plugin) {
+  let runtime = plugin.runtime;
+  let scope = plugin.topLevelScope;
+
+  function helloworld() {}
+
+  helloworld.stringFromJava = plugin.getStringFromJava();
+
+  helloworld.say = function (message) {
+    plugin.say(message);
+  };
+
+  return helloworld;
+};
+```
+
+4. 在 Auto.js 中调用
+   编译插件为 apk(assembleDebug/assembleRelease)，安装到设备上。在 Auto.js 中使用以下代码调用：
+
+```js
+let helloworld = $plugins.load("org.autojs.plugin.sdk.demo");
+console.log(helloworld.stringFromJava);
+helloworld.say("Hello, Auto.js Pro Plugin");
+```

docs/rhino/advanced/canvas.md

@@ -36,4 +36,49 @@ canvas.drawRect(0, 0, 100, 100, paint);
 
 ## canvas.drawARGB(a, r, g, b)
 
-## canvas.draw
+绘制 argb 颜色到画布，每个参数为`0~255`的整数，例如
+
+```js
+canvas.drawARGB(255, 255, 0, 0);
+```
+
+## 在 ui 中使用画布
+
+我们可以使用如下代码来创建一个带有 canvas 的界面
+
+```js
+"ui";
+ui.layout(
+  <frame>
+    <canvas id="board" w="*" h="*" />
+  </frame>
+);
+ui.board.on("draw", function (canvas) {
+  canvas.drawARGB(0xff, 0xff, 0xff, 0xff);
+});
+```
+
+然后在`draw`事件中可以进行绘制图像  
+需要注意的是`ui.board`并不是`canvas`，而是一个`TextureView`,由于历史设计此名称为 canvas 很容易造成混浊，在 v7.1.7 版本后可使用别名`texture`,为兼容性考虑`canvas`名称任然保留。  
+**`draw`事件会在 ui 创建后会有后台线程频繁触发以更新 canvas**，请勿在该含回调函数中做任何与绘制 canvas 无关的事，**在 v7.1.6 版本取消了这一行为**，`draw`事件默认仅会触发一次，如果需要更新`canvas`则使用`ui.board.updateCanvas()`来手动触发`draw`事件，如果需要回到以前的行为只需添加以下代码
+
+```js
+"ui";
+ui.layout(
+  <frame>
+    <canvas id="board" w="*" h="*" />
+  </frame>
+);
+ui.board.on("draw", function (canvas) {
+  canvas.drawARGB(0xff, 0xff, 0xff, 0xff);
+});
+
+threads.start(() => {
+  let board = ui.board;
+  setInterval(() => {
+    board.updateCanvas();
+  }, 1000 / 60);
+});
+```
+
+在 'app 示例/画布' 中可查看更多例子

docs/rhino/advanced/engines.md

@@ -22,7 +22,7 @@ toast(engines.myEngine().cwd());
   - `interval` \{number} 循环运行时两次运行之间的时间间隔，默认为 0
   - `path` \{Array} | \{string} 指定脚本运行的目录。这些路径会用于 require 时寻找模块文件。
 
-在新的脚本环境中运行脚本 script。返回一个[ScriptExectuion](#ScriptExecution)对象。
+在新的脚本环境中运行脚本 script。返回一个[ScriptExectuion](#scriptexecution)对象。
 
 所谓新的脚本环境，指定是，脚本中的变量和原脚本的变量是不共享的，并且，脚本会在新的线程中运行。
 
@@ -81,7 +81,7 @@ exec(add, { a: 1, b: 2 });
   - `interval` \{number} 循环运行时两次运行之间的时间间隔，默认为 0
   - `path` \{Array} | \{string} 指定脚本运行的目录。这些路径会用于 require 时寻找模块文件。
 
-在新的脚本环境中运行脚本文件 path。返回一个[ScriptExecution](#ScriptExecution)对象。
+在新的脚本环境中运行脚本文件 path。返回一个[ScriptExecution](#scriptexecution)对象。
 
 ```js
 engines.execScriptFile("/sdcard/脚本/1.js");
@@ -96,7 +96,7 @@ engines.execScriptFile("/sdcard/脚本/1.js");
   - `interval` \{number} 循环运行时两次运行之间的时间间隔，默认为 0
   - `path` \{Array} | \{string} 指定脚本运行的目录。这些路径会用于 require 时寻找模块文件。
 
-在新的脚本环境中运行录制文件 path。返回一个[ScriptExecution](#ScriptExecution)对象。
+在新的脚本环境中运行录制文件 path。返回一个[ScriptExecution](#scriptexecution)对象。
 
 ```js
 engines.execAutoFile("/sdcard/脚本/1.auto");
@@ -112,7 +112,7 @@ engines.execAutoFile("/sdcard/脚本/1.auto");
 
 ## engines.myEngine()
 
-返回当前脚本的脚本引擎对象([ScriptEngine](#ScriptEngine))
+返回当前脚本的脚本引擎对象([ScriptEngine](#scriptengine))
 
 **[v4.1.0 新增]**
 特别的，该对象可以通过`execArgv`来获取他的运行参数，包括外部参数、intent 等。例如：
@@ -127,31 +127,31 @@ log(engines.myEngine().execArgv);
 
 - 返回 \{Array}
 
-返回当前所有正在运行的脚本的脚本引擎[ScriptEngine](#ScriptEngine)的数组。
+返回当前所有正在运行的脚本的脚本引擎[ScriptEngine](#scriptengine)的数组。
 
 ```js
 log(engines.all());
 ```
 
-# ScriptExecution
+## ScriptExecution
 
 执行脚本时返回的对象，可以通过他获取执行的引擎、配置等，也可以停止这个执行。
 
 要停止这个脚本的执行，使用`exectuion.getEngine().forceStop()`.
 
-## ScriptExecution.getEngine()
+### ScriptExecution.getEngine()
 
-返回执行该脚本的脚本引擎对象([ScriptEngine](#ScriptEngine))
+返回执行该脚本的脚本引擎对象([ScriptEngine](#scriptengine))
 
-## ScriptExecution.getConfig()
+### ScriptExecution.getConfig()
 
-返回该脚本的运行配置([ScriptConfig](#ScriptConfig))
+返回该脚本的运行配置([ScriptConfig](#scriptconfig))
 
-# ScriptEngine
+## ScriptEngine
 
 脚本引擎对象。
 
-## ScriptEngine.isDestroyed()
+### ScriptEngine.isDestroyed()
 
 - 返回 \{Boolean}
 
@@ -163,17 +163,17 @@ sleep(2000);
 log(e.getEngine().isDestroyed())
 ```
 
-## ScriptEngine.forceStop()
+### ScriptEngine.forceStop()
 
 停止脚本引擎的执行。
 
-## ScriptEngine.cwd()
+### ScriptEngine.cwd()
 
 - 返回 \{string}
 
 返回脚本执行的路径。对于一个脚本文件而言为这个脚本所在的文件夹；对于其他脚本，例如字符串脚本，则为`null`或者执行时的设置值。
 
-## ScriptEngine.getSource()
+### ScriptEngine.getSource()
 
 - 返回 [ScriptSource](#scriptsource)
 
@@ -183,7 +183,7 @@ log(e.getEngine().isDestroyed())
 log(engines.myEngine().getSource());
 ```
 
-## ScriptEngine.emit(eventName[, ...args])
+### ScriptEngine.emit(eventName[, ...args])
 
 - `eventName` \{string} 事件名称
 - `...args` \{any} 事件参数
@@ -212,29 +212,29 @@ sleep(2000);
 e.getEngine().emit("say", "你好");
 ```
 
-# ScriptConfig
+## ScriptConfig
 
 脚本执行时的配置。
 
-## delay
+### delay
 
 - \{number}
 
 延迟执行的毫秒数
 
-## interval
+### interval
 
 - \{number}
 
 循环运行时两次运行之间的时间间隔
 
-## loopTimes
+### loopTimes
 
 - \{number}
 
 循环运行次数
 
-## getPath()
+### getPath()
 
 - 返回 \{Array}
 

docusaurus.config.ts

@@ -69,10 +69,15 @@ const config: Config = {
           docId: 'overview',
           label: '综述',
         },
+        {
+          type: 'doc',
+          docId: 'plugins',
+          label: '插件',
+        },
         {
           type: 'doc',
           docId: 'external_support',
-          label: '从外部运行 Autox 脚本',
+          label: '从外部运行脚本',
         },
         {
           type: 'docSidebar',