js_engine

AutoGo JavaScript Engine

AutoGo JavaScript Engine 是一个高性能的 JavaScript 脚本引擎，为 AutoGo 框架提供了完整的 JavaScript 脚本支持。

特性

• 完整的 API 注入: 将 AutoGo 的所有功能模块注入到 JavaScript 引擎中
• 模块化设计: 支持按需加载模块
• 线程安全: 所有操作都是线程安全的
• 文件系统支持: 支持真实文件系统和虚拟文件系统 (embed.FS)
• 模块导入: 支持 CommonJS 风格的 require 功能

快速开始

初始化引擎

import "github.com/ZingYao/autogo_scriptengine/js_engine"

func main() {
    // 使用默认配置创建引擎（自动注入所有方法）
    engine := js_engine.NewEngine(&js_engine.DefaultConfig())
    defer engine.Close()
    
    // 使用引擎...
}

引擎配置选项

import (
    "embed"
    "os"
    "github.com/ZingYao/autogo_scriptengine/js_engine"
)

//go:embed scripts/*
var scriptsFS embed.FS

func main() {
    // 使用自定义配置
    config := js_engine.DefaultConfig()
    config.AutoInjectMethods = false  // 禁用自动注入
    config.FileSystem = scriptsFS      // 设置虚拟文件系统
    
    engine := js_engine.NewEngine(&config)
    defer engine.Close()
    
    // 按需注入模块
    engine.InjectModule("app")
    engine.InjectModule("device")
}

执行 JavaScript 代码

// 执行 JavaScript 字符串
err := engine.ExecuteString(`
    console.log("Hello, JavaScript!");
    const packageName = app.currentPackage();
    console.log("当前应用包名: " + packageName);
`)

// 执行 JavaScript 文件（从真实文件系统）
err = engine.ExecuteFile("/sdcard/script.js")

// 执行 JavaScript 文件（从虚拟文件系统）
err = engine.ExecuteFile("scripts/script.js")

模块列表

DemoCode

1. 加载网络的脚本并执行

package main

import (
    "fmt"
    "io"
    "net/http"
    "github.com/ZingYao/autogo_scriptengine/js_engine"
    "github.com/ZingYao/autogo_scriptengine/js_engine/define/safe_models"
)

func main() {
    // 注册 JavaScript 引擎模块
    js_engine.RegisterModule(safe_models.SafeModules...)
    
    // 创建引擎
    engine := js_engine.NewEngine(&js_engine.DefaultConfig())
    defer engine.Close()
    
    // 从网络下载脚本
    resp, err := http.Get("https://example.com/script.js")
    if err != nil {
        fmt.Printf("下载脚本失败: %v\n", err)
        return
    }
    defer resp.Body.Close()
    
    // 读取脚本内容
    script, err := io.ReadAll(resp.Body)
    if err != nil {
        fmt.Printf("读取脚本失败: %v\n", err)
        return
    }
    
    // 执行脚本
    err = engine.ExecuteString(string(script))
    if err != nil {
        fmt.Printf("执行脚本失败: %v\n", err)
    } else {
        fmt.Println("脚本执行成功")
    }
}

2. 加载真实文件系统的脚本并执行

package main

import (
    "fmt"
    "os"
    "github.com/ZingYao/autogo_scriptengine/js_engine"
    "github.com/ZingYao/autogo_scriptengine/js_engine/define/safe_models"
)

func main() {
    // 注册 JavaScript 引擎模块
    js_engine.RegisterModule(safe_models.SafeModules...)
    
    // 创建引擎，配置真实文件系统
    config := js_engine.DefaultConfig()
    config.FileSystem = os.DirFS("/sdcard/script")  // 设置真实文件系统目录
    engine := js_engine.NewEngine(&config)
    defer engine.Close()
    
    // 执行脚本文件
    err := engine.ExecuteFile("main.js")
    if err != nil {
        fmt.Printf("执行脚本失败: %v\n", err)
    } else {
        fmt.Println("脚本执行成功")
    }
}

3. 加载虚拟文件系统的脚本并运行

package main

import (
    "embed"
    "fmt"
    "github.com/ZingYao/autogo_scriptengine/js_engine"
    "github.com/ZingYao/autogo_scriptengine/js_engine/define/safe_models"
)

//go:embed scripts/*
var scriptsFS embed.FS

func main() {
    // 注册 JavaScript 引擎模块
    js_engine.RegisterModule(safe_models.SafeModules...)
    
    // 创建引擎，配置虚拟文件系统
    config := js_engine.DefaultConfig()
    config.FileSystem = scriptsFS      // 设置虚拟文件系统
    engine := js_engine.NewEngine(&config)
    defer engine.Close()
    
    // 执行脚本文件
    err := engine.ExecuteFile("scripts/main.js")
    if err != nil {
        fmt.Printf("执行脚本失败: %v\n", err)
    } else {
        fmt.Println("脚本执行成功")
    }
}

4. Main 脚本加载 Model 脚本并运行

main.js (主脚本)

// main.js - 主脚本，加载并调用 model 脚本

console.log("=== 主脚本开始执行 ===");

// 导入 model 脚本
const model = require("./model");

// 调用 model 中的函数
model.init();
model.process("测试数据");

console.log("=== 主脚本执行完成 ===");

model.js (模型脚本)

// model.js - 模型脚本

function init() {
    console.log("模型初始化完成");
}

function process(data) {
    console.log("处理数据: " + data);
    // 在这里添加具体的处理逻辑
}

// 导出函数
module.exports = {
    init,
    process
};

Go 代码

package main

import (
    "embed"
    "fmt"
    "github.com/ZingYao/autogo_scriptengine/js_engine"
    "github.com/ZingYao/autogo_scriptengine/js_engine/define/safe_models"
)

//go:embed scripts/*
var scriptsFS embed.FS

func main() {
    // 注册 JavaScript 引擎模块
    js_engine.RegisterModule(safe_models.SafeModules...)
    
    // 创建引擎，配置虚拟文件系统
    config := js_engine.DefaultConfig()
    config.FileSystem = scriptsFS
    engine := js_engine.NewEngine(&config)
    defer engine.Close()
    
    // 执行主脚本，主脚本会自动加载 model 脚本
    err := engine.ExecuteFile("scripts/main.js")
    if err != nil {
        fmt.Printf("执行脚本失败: %v\n", err)
    } else {
        fmt.Println("脚本执行成功")
    }
}

API 参考

引擎方法

方法详细说明

NewEngine

创建新的 JavaScript 引擎实例。

config := js_engine.DefaultConfig()
engine := js_engine.NewEngine(&config)

GetVM

获取 JavaScript 运行时对象，用于直接操作 JavaScript 虚拟机。

vm := engine.GetVM()

InjectModule

注入指定模块的方法到引擎中。

engine.InjectModule("app")
engine.InjectModule("device")

支持的模块：app, device, motion, files, images, storages, system, http, media, opencv, ppocr, console, coroutine, dotocr, hud, ime, plugin, rhino, uiacc, utils, vdisplay, yolo, imgui

InjectModules

注入多个模块的方法到引擎中。

engine.InjectModules([]string{"app", "device", "motion"})

GetAvailableModules

获取所有可用模块列表。

modules := engine.GetAvailableModules()
fmt.Println(modules)
// 输出: [app device motion files images storages system http media opencv ppocr console coroutine dotocr hud ime plugin rhino uiacc utils vdisplay yolo imgui]

InjectAllMethods

注入所有模块的方法到引擎中。

engine.InjectAllMethods()

RegisterMethod

注册自定义方法到引擎中。

engine.RegisterMethod("myFunction", "我的自定义函数", func(call goja.FunctionCall) goja.Value {
    // 实现自定义逻辑
    return nil
}, true)

参数：

• name: 方法名称
• description: 方法描述
• goFunc: Go 函数
• overridable: 是否允许被 JavaScript 函数重写

ExecuteString

执行 JavaScript 代码字符串。

// 基本用法
err := engine.ExecuteString(`
    console.log("Hello, JavaScript!");
`)

// 指定目录（用于 require）
err = engine.ExecuteString(`
    const model = require("./model");
    model.init();
`, "scripts")

参数：

• script: 要执行的 JavaScript 代码
• dir: 可选参数，指定工作目录（用于 require）

ExecuteFile

执行 JavaScript 文件。

// 从真实文件系统执行
err := engine.ExecuteFile("/sdcard/script.js")

// 从虚拟文件系统执行
err = engine.ExecuteFile("scripts/script.js")

参数：

• path: 文件路径

Close

关闭引擎，释放资源。

defer engine.Close()

GetRegistry

获取方法注册表，用于管理已注册的方法。

registry := engine.GetRegistry()

配置选项

兼容性说明

Android 版本兼容性

某些依赖包在特定的 Android 版本下可能会出现内存引用错误（Memory Reference Error）。如果遇到此类问题，可以尝试以下解决方案：

1. 修改引入的包：根据您的 Android 版本，可以修改项目中引入的相关包
2. 禁用问题模块：在引擎配置中使用黑名单禁用导致问题的特定模块
3. 使用替代方案：某些功能可能有多种实现方式，可以尝试使用替代方案

示例：禁用可能导致问题的模块

config := js_engine.DefaultConfig()
config.BlackList = []string{"opencv", "ppocr"}  // 禁用可能导致内存问题的模块
engine := js_engine.NewEngine(&config)

Windows 开发环境

在 Windows 环境下开发时，如果引入了某些使用 C 语言的包，可能会遇到以下错误：

The command line is too long.

这是 Windows 命令行长度限制导致的。解决方案：

1. 避免引入问题包：尽量减少使用包含 C 代码的依赖包
2. 使用 WSL：在 Windows Subsystem for Linux (WSL) 环境中开发
3. 调整项目结构：将项目拆分为多个子项目，减少单个项目的依赖复杂度

常见问题处理

如果遇到兼容性问题，建议：

1. 检查您的 Android 设备版本和 SDK 版本
2. 查看项目的 GitHub Issues，了解已知的兼容性问题
3. 根据错误信息调整配置或代码
4. 如有必要，可以 Fork 项目并根据您的环境进行修改

License

MIT License