# JS浏览器 - 脚本开发 API 文档

## 目录

- [.zdjs 脚本 API（JavaScript）](#zdjs-脚本-apijavascript)
- [.zdp 脚本 API（BeanShell）](#zdp-脚本-apibeanshell)
- [全局对象/变量速查](#全局对象变量速查)

---

## .zdjs 脚本 API（JavaScript）

> 运行在 WebView 中，通过 `ZDJSApi` 桥接调用 Java 方法。

### 架构说明

```
run_plug.html 加载 → 定义 zd 对象 + ZDJSApi 桥
    ↓
用户代码 eval() 执行
    ↓
调用 zd.xxx() 或 ZDJSApi.xxx()
    ↓
Java 层执行 → 通过 peakMessageResult() 获取异步结果
```

### ZDJSApi 原生方法（@JavascriptInterface）

通过 `ZDJSApi` 对象直接调用：

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `getHtml()` | — | `String` | 获取当前页面 HTML |
| `setHtml(str)` | `String` | `void` | 设置当前页面 HTML |
| `getUrl()` | — | `String` | 获取当前页面 URL |
| `getTitle()` | — | `String` | 获取当前页面标题 |
| `getWindowName()` | — | `String` | 获取当前窗口名称 |
| `getWindowId()` | — | `String` | 获取窗口 hashCode |
| `getScriptListId()` | — | `String` | 获取脚本管理器 hashCode |
| `getScriptId()` | — | `String` | 获取当前脚本 hashCode |
| `getTmpValue(key, scope)` | `String, String` | `String` | 获取临时变量（scope: `"script"` / `"scriptList"` / `""` 全局） |
| `setTmpValue(key, value, scope)` | `String, String, String` | `void` | 设置临时变量 |
| `removeTmpValue(key, scope)` | `String, String` | `String` | 删除并返回临时变量 |
| `getPlugCode()` | — | `String` | 获取当前插件源码 |
| `getRunArgsJSON()` | — | `String` | 获取运行参数（JSON 数组字符串） |
| `reqGet(callbackId, url, charset)` | `long, String, String` | `void` | 异步 GET 请求（charset 填 `"base64"` 返回二进制） |
| `reqApi(callbackId, jsonOption)` | `long, String` | `void` | 异步 HTTP 请求（选项: `{method, url, data, contentType}`） |
| `finish(str)` | `String` | `void` | 结束插件执行 |
| `setPlugState(state)` | `String` | `void` | 更新插件状态显示 |
| `peakMessageResult(callbackId)` | `long` | `String` | 获取异步请求结果（一次性） |
| `runScript(callbackId, scriptJson)` | `long, String` | `void` | 运行一个脚本（结果通过 callbackId 返回） |
| `getWindowCount()` | — | `int` | 获取窗口总数 |
| `getCurrentWindowIndex()` | — | `int` | 获取当前窗口索引 |
| `getShowingWindowIndex()` | — | `int` | 获取可见窗口索引 |
| `getWindowName(index)` | `int` | `String` | 根据索引获取窗口名称 |
| `setWindowName(index, name)` | `int, String` | `void` | 设置窗口名称 |
| `getWindowUA(index)` | `int` | `String` | 获取窗口 User-Agent |
| `setWindowUA(index, ua)` | `int, String` | `void` | 设置窗口 User-Agent |
| `setWindowProxy(index, ip, port, user, pass)` | `int, String, int, String, String` | `void` | 设置窗口代理 |
| `closeWindow(index)` | `int` | `void` | 关闭指定窗口 |
| `exitApp()` | — | `void` | 退出应用 |

### zd 对象方法（JS 封装，返回 Promise）

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `zd.getDoc()` | — | `Promise<HTMLElement>` | 获取页面 DOM |
| `zd.setDoc(doc)` | `HTMLElement` | `void` | 替换页面 HTML |
| `zd.getUrl()` | — | `Promise<String>` | 获取当前 URL |
| `zd.getTitle()` | — | `Promise<String>` | 获取页面标题 |
| `zd.getWindowName()` | — | `Promise<String>` | 获取窗口名称 |
| `zd.getTmpValue(key, scope)` | `String, String?` | `Promise<String>` | 获取临时变量 |
| `zd.setTmpValue(key, value, scope)` | `String, String, String?` | `void` | 设置临时变量 |
| `zd.removeTmpValue(key, scope)` | `String, String?` | `void` | 删除临时变量 |
| `zd.setPlugState(state)` | `String` | `void` | 更新状态文本 |
| `zd.goto(url)` | `String` | `Promise` | 导航到 URL |
| `zd.clickText(text)` | `String` | `Promise` | 点击页面文字 |
| `zd.runScript(script)` | `Object` | `Promise` | 运行一个脚本 |
| `zd.reqBase64(url)` | `String` | `Promise<String>` | GET 请求返回 Base64 |
| `zd.reqGet(url)` | `String` | `Promise<String>` | GET 请求返回文本 |
| `zd.reqApi(option)` | `Object` | `Promise` | HTTP 请求（自动解析 JSON） |
| `zd.getCurrentWindow()` | — | `WindowHandler` | 获取当前窗口句柄 |
| `zd.getShowingWindow()` | — | `WindowHandler` | 获取可见窗口句柄 |
| `zd.getWindows()` | — | `WindowHandler[]` | 获取所有窗口句柄 |
| `zd.exitApp()` | — | `void` | 退出应用 |

### WindowHandler 对象（窗口操作）

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `getName()` | — | `String` | 获取窗口名称 |
| `setName(name)` | `String` | `void` | 设置窗口名称 |
| `getUA()` | — | `String` | 获取 User-Agent |
| `setUA(ua)` | `String` | `void` | 设置 User-Agent |
| `setProxy(ip, port, user, pass)` | `String, int, String?, String?` | `void` | 设置代理 |
| `close()` | — | `void` | 关闭窗口 |
| `.index` | — | `int` | 窗口索引（属性） |

### .zdjs 脚本模板

```javascript
// 获取运行参数
var args = ZDJSApi.getRunArgsJSON();
args = JSON.parse(args);

// 主函数（必须定义）
function main(args) {
    // 获取页面信息
    var url = ZDJSApi.getUrl();
    var html = ZDJSApi.getHtml();
    
    // HTTP 请求（异步）
    var callbackId = Date.now();
    ZDJSApi.reqGet(callbackId, "https://example.com/api", "UTF-8");
    var result = ZDJSApi.peakMessageResult(callbackId);
    
    // 运行另一个脚本
    var scriptId = Date.now();
    ZDJSApi.runScript(scriptId, '{"type":"click","text":"登录"}');
    var scriptResult = ZDJSApi.peakMessageResult(scriptId);
    
    // 结束执行
    ZDJSApi.finish("执行完毕");
}

// 调用主函数（必须）
main(args);
```

---

## .zdp 脚本 API（BeanShell）

> 运行在 BeanShell 解释器中，使用 Java 语法。

### 预置变量

| 变量名 | 类型 | 说明 |
|--------|------|------|
| `zdWindow` | `BrowserWindow` | 浏览器窗口实例 |
| `scriptManager` | `ScriptManagerBridge` | 脚本管理器桥接 |
| `runningScript` | `RunPlugScript` | 当前运行的插件脚本 |
| `nextListerner` | `WebCore.LoadListener` | 加载监听器（拼写错误保留） |
| `nextListener` | `WebCore.LoadListener` | 加载监听器 |

### 自动导入的包

```java
import com.js.jscom.script.*;
import com.js.jscom.window.*;
import com.js.jscom.utils.*;
import com.js.jscom.*;
import com.js.jscom.plug.*;
import com.js.jscom.window.WebCore.LoadListener;
import java.io.*;
import java.util.*;
import org.json.*;
import org.jsoup.nodes.*;
import org.jsoup.nodes.Node;
import bsh.*;
```

### scriptManager 方法（脚本管理）

| 方法 | 返回值 | 说明 |
|------|--------|------|
| `isInPackage()` | `boolean` | 是否在包内 |
| `getPackageFile()` | `File` | 获取包文件 |
| `getPkInfoForShow()` | `String` | 获取包信息 |
| `getNowRunningScriptIndex()` | `int` | 获取当前脚本索引（1-based） |
| `isRunningScript()` | `boolean` | 是否有脚本在运行 |
| `isRunningAndPlaying()` | `boolean` | 是否正在运行且未暂停 |
| `isPause()` | `boolean` | 是否暂停 |
| `pause()` | `void` | 暂停执行 |
| `resume()` | `void` | 恢复执行 |
| `getScriptFile()` | `File` | 获取脚本文件 |
| `getScriptFileDir()` | `File` | 获取脚本目录 |
| `getBaseParam()` | `BaseParam` | 获取基础参数 |
| `getBrowserWindow()` | `BrowserWindow` | 获取浏览器窗口 |
| `add(int index, RunnableScript script)` | `void` | 在指定位置添加脚本（UI 线程） |
| `addAtNextIndex(RunnableScript script)` | `void` | 在当前脚本后添加 |
| `add(RunnableScript script)` | `void` | 追加脚本（UI 线程） |
| `size()` | `int` | 获取脚本数量 |
| `set(int index, RunnableScript script)` | `void` | 替换指定位置脚本（UI 线程） |
| `set(ZDScriptManager manager)` | `void` | 替换整个脚本管理器（UI 线程） |
| `get(int index)` | `RunnableScript` | 获取指定位置脚本 |
| `remove(int index)` | `void` | 删除指定位置脚本（UI 线程） |
| `isFront()` | `boolean` | 是否在前台 |
| `stopRunning()` | `void` | 停止执行 |
| `startRunScript()` | `void` | 开始执行 |
| `runScript(RunnableScript script)` | `void` | 运行指定脚本 |
| `iterator()` | `Iterator<RunnableScript>` | 遍历脚本 |
| `toStringWithInfo()` | `String` | 获取字符串表示（含信息） |
| `toString()` | `String` | 获取字符串表示 |

### zdWindow 方法（浏览器窗口）

| 方法 | 返回值 | 说明 |
|------|--------|------|
| `getSetting()` | `BrowserWindowSetting` | 获取窗口设置 |
| `getWindowName()` | `String` | 获取窗口名称 |
| `setWindowName(name)` | `void` | 设置窗口名称 |
| `isRecording()` | `boolean` | 是否正在录制 |
| `setRecording(z)` | `void` | 设置录制模式 |
| `getScriptManager()` | `ZDScriptManager` | 获取脚本管理器 |
| `isRunningScript()` | `boolean` | 是否有脚本在运行 |
| `isRunningAndPlaying()` | `boolean` | 是否正在运行且未暂停 |
| `setScriptManager(mgr)` | `void` | 设置脚本管理器 |
| `isPageInit()` | `boolean` | 页面是否初始化 |
| `getWindowIndex()` | `int` | 获取窗口索引 |
| `getIndexAndNameForShow(showStar)` | `String` | 获取显示名称（如 "窗口1(名称)"） |
| `getNowPage()` | `WebPage` | 获取当前页面 |
| `getCookieStore()` | `CookieStore` | 获取 Cookie 存储 |
| `setCookiesAndClear(cookies)` | `void` | 设置 Cookie 并清除旧值 |
| `addCookie(cookie)` | `void` | 添加 Cookie |
| `preClose()` | `void` | 预关闭窗口 |
| `getWebCore()` | `WebCore` | 获取 Web 引擎 |
| `getActivity()` | `MainActivity` | 获取主 Activity |
| `loadUrl(url)` | `void` | 加载 URL |
| `loadUrl(url, listener)` | `void` | 加载 URL（带监听器） |
| `loadUrl(url, params)` | `void` | 加载 URL（带参数） |
| `loadUrl(url, params, listener)` | `void` | 加载 URL（带参数和监听器） |
| `post(url, params)` | `void` | POST 请求 |
| `post(url, params, listener)` | `void` | POST 请求（带监听器） |
| `reload()` | `void` | 重新加载 |
| `stopLoading()` | `void` | 停止加载 |
| `goBack()` | `void` | 后退 |
| `canGoback()` | `boolean` | 是否可以后退 |
| `goForward()` | `void` | 前进 |
| `canGoForward()` | `boolean` | 是否可以前进 |
| `canGoHome()` | `boolean` | 是否可以回主页 |
| `goHome()` | `void` | 回主页 |
| `isLoading()` | `boolean` | 是否正在加载 |
| `getProgress()` | `int` | 获取加载进度（0-100） |
| `setProgress(i)` | `void` | 设置加载进度 |
| `getTitle()` | `String` | 获取页面标题 |
| `getUrl()` | `String` | 获取页面 URL |
| `getReferUrl()` | `String` | 获取来源 URL |
| `favNowPage()` | `boolean` | 收藏当前页面 |
| `isNowPageFaved()` | `boolean` | 当前页面是否已收藏 |
| `checkCanClick()` | `boolean` | 是否可以点击 |
| `click(url, hitTestResult)` | `void` | 点击 URL |
| `clickEnterSite(url)` | `void` | 点击进入站点 |
| `clickForm(formInfo)` | `void` | 提交表单 |
| `clickReload()` | `void` | 点击重新加载 |
| `clickGoHome()` | `void` | 点击回主页 |
| `clickGoBack(animate)` | `void` | 点击后退 |
| `clickGoForward(animate)` | `void` | 点击前进 |
| `save(bg)` | `void` | 保存窗口状态 |

### BrowserWindow 静态常量

| 常量 | 值 | 说明 |
|------|-----|------|
| `HomeUrl` | `file://...` | 主页 URL |
| `Progress_AllFinished` | `100` | 加载完成 |
| `Progress_Executed` | `40` | 脚本已执行 |
| `Progress_HTMLFinished` | `80` | HTML 加载完成 |
| `Progress_Readed` | `70` | 内容已读取 |
| `Progress_Start` | `20` | 开始加载 |

### .zdp 脚本模板

```java
// 获取页面信息
String url = zdWindow.getUrl();
String html = zdWindow.getNowPage().getHtml();
String title = zdWindow.getTitle();

// 导航到新页面
zdWindow.loadUrl("https://example.com");

// 运行另一个脚本
import com.js.jscom.script.*;
ClickScript clickScript = new ClickScript("登录");
scriptManager.add(clickScript);

// 控制执行
scriptManager.pause();   // 暂停
scriptManager.resume();  // 恢复
scriptManager.stopRunning();  // 停止

// 返回 true 表示执行成功，false 表示继续执行下一个脚本
return true;
```

---

## 全局对象/变量速查

### .zdjs 全局对象

| 对象 | 类型 | 说明 |
|------|------|------|
| `ZDJSApi` | Java 对象 | 原生桥接对象（直接调用） |
| `zd` | JS 对象 | 高级封装（返回 Promise） |
| `main(args)` | 函数 | 插件入口函数（必须定义） |

### .zdp 全局变量

| 变量 | 类型 | 说明 |
|------|------|------|
| `zdWindow` | `BrowserWindow` | 浏览器窗口 |
| `scriptManager` | `ScriptManagerBridge` | 脚本管理器 |
| `runningScript` | `RunPlugScript` | 当前脚本 |
| `nextListerner` | `LoadListener` | 加载监听器 |
| `nextListener` | `LoadListener` | 加载监听器 |

### 临时变量作用域（getTmpValue/setTmpValue）

| scope 值 | 说明 |
|----------|------|
| `""` | 全局（Application 级别） |
| `"script"` | 当前脚本 |
| `"scriptList"` | 当前脚本列表 |
| `"window"` | 当前窗口 |

---