插件系统总览（Plugin API 1.0）

WeAppDev 插件是一个 HTML（或 zip）文件，可以注入到小程序的三个上下文里执行，也可以作为面板挂在调试浮窗里。

插件 API 由三个全局变量组成，一层一个，进入哪个上下文就用哪个。所有能力都拍平到全局变量顶层——wadLogicLayer.page()、wadPanelLayer.ui.toast()，不需要再穿过中间命名空间。

本页你将学到

三个全局变量各自长什么样（结构图）；
三个上下文分别在哪运行、写法是什么；
每个 API 在三层的可用性速查；
一个最小可用插件怎么写。

三个全局变量

wadLogicLayer（逻辑层）

text

wadLogicLayer（逻辑层全局 · appservice V8 · 有 wx，无 DOM）
├── 元信息      apiVersion / layer / id / name / version / appid
│               instanceId / ready / instance() / log()
├── 业务面      page / register / call(n, ...args)
│               本层同步直调；eval 抛 E_EVAL_SANDBOX
├── 存储        storage.get/set/remove/keys/clear（Promise）+ *Sync（同步）
├── UI          ui.toast
├── 事件        on / off / emit
│               钩子糖 onReady/onAttach/onDetach/onPageChange/onStorageWrite/onNetwork
├── 工具包      tools.*（md5/sha256/base64/uuid/…）
├── 统一网络    http.*（wx.request 语义，默认 dataType 'json'，task 可 abort）
├── 消息广播    messaging.emit（→ Promise<payload>）/ on / once / off / onAny
├── 共享存储    sharedStorage.app / .global / watch
├── 网络改写    capture.intercept / watch / records / body / rules
│               addRule / removeRule / clear
├── mmtls/ilink native.intercept / observe / records / get / clear
├── 插件资产    assets.url / text / json / arrayBuffer / wasm / preload / clear
│               script / css 不可用（E_LAYER_ONLY）
├── 调试器      debugger.*（断点 / 求值 / 步进 / 截图…）
└── 跨层代理    renderLayer.eval / page / screenshot / domSnapshot / ui.toast / tools
                panelLayer.ui.toast / tools

wadRenderLayer（渲染层）

text

wadRenderLayer（渲染层全局 · 页面 WebView · 有 DOM，无 wx）
├── 元信息      同逻辑层（layer 'render'，instanceId 'render-xxxxxx'）
├── DOM        eval / dom.query / dom.create / dom.text / dom.render(fn)
├── 页面        page() → {url, title} / localStorage / sessionStorage / asset(p)
├── UI          ui.toast（页面内 DOM Toast）
├── 事件        on / off / emit + 钩子糖 onReady / onAttach / onDetach
├── 工具/网络   tools.* / http.*（fetch 语义）
│               messaging.* / sharedStorage.*
├── 资产        assets.* 全量（含 script / css）
├── 改写/回调 capture.* / native.*（注册类同步抛错，查询类 Promise.reject）
└── 跨层代理    logicLayer.call(fn, ...args) / emit / ui.toast / tools
                panelLayer.ui.toast / tools

wadPanelLayer（面板）

text

wadPanelLayer（面板全局 · 浮窗 WebView · 有 SDK，无 wx）
├── 元信息      同上 + clientId（多面板区分；version 是 SDK 版本 '1.0'，插件版本用 instance().version）
├── 存储        storage.*（面板宿主 JSON）/ localStorage / sessionStorage
├── UI 组件库   ui.el / button / card / input / select / field / badge / row / col / mount
├── 壳交互      ui.toast / setTitle / close / setSize；生命周期钩子用顶层 onOpen / onClose
├── 事件        on（纯事件）/ off / emit / onAny + 钩子糖（onReady / onDetach / onOpen / onClose）
├── 工具/网络   tools.* / http.*（宿主代理，请求 60s，abort 为 no-op）
│               messaging.* / sharedStorage.*
├── 总线        connected() / info() / call(method, ...args)
│               rpcWithTimeout(method, args, ms)
├── 网络能力    capture.records / body / rules / addRule / removeRule / watch / clear
│               capture.intercept 不存在
├── mmtls/ilink native.observe / records / get / clear；native.intercept 存在但同步抛 E_LAYER_ONLY
├── 资产/调试   assets.* 全量（含 script / css）/ debugger.*
└── 跨层代理    logicLayer.call / eval / page / storage / ui.toast
                renderLayer.eval / screenshot / domSnapshot / targets / page / ui.toast

三个全局变量的完整逐 API 对照见三层 API 对比。

三个上下文

上下文	在哪运行	全局变量	写法	典型用途
逻辑层 logic	appservice（业务 JS 上下文）	`wadLogicLayer`	`<script type="text/wad-logic">`	网络改写、Native 拦截、注册技能、定时任务
渲染层 render	页面 WebView（XWeb）	`wadRenderLayer`	`<script type="text/wad-render">`	改 DOM、注入样式、页面事件
面板 panel	调试浮窗网页	`wadPanelLayer`	普通 `<script>`（宿主自动注入 SDK）	操作 UI、看数据、跨层控制

支持矩阵（速查）

图例：✅ 本地 · 🔁 跨层 Promise · 👁 只读 · — 不可用（抛 E_LAYER_ONLY）

API	逻辑层	渲染层	面板层
元信息 / ready / instance / log	✅	✅	✅（另有 clientId；version 为 SDK '1.0'）
`page / register / call / eval / storage`	page/register/call ✅；eval 抛 E_EVAL_SANDBOX	🔁（仅 call）；page/eval 本地	🔁
`screenshot / domSnapshot / targets`	🔁	—（无这些本地 API）	🔁
`storage`（面板宿主）	—	—	✅
`sharedStorage.app / global / watch`	✅	✅	✅
`messaging.emit / on / onAny`	✅	✅	✅
`http.request / get / post / … / upload`	✅ wx.request	✅ fetch	✅ 宿主代理（65s）
`capture.intercept`	✅	—（同步抛错）	—
`capture.records / watch / addRule / clear`	✅	🔁 reject	✅
`native.intercept`	✅	✋ 同步抛 E_LAYER_ONLY	✋ 同步抛 E_LAYER_ONLY
`native.observe / records`	✅	🔁 reject	✅
`assets.url / text / json / wasm / preload`	✅	✅	✅
`assets.script / css`	🔁 reject	✅	✅
`tools.*`	✅	✅	✅
`debugger.*`	✅	—	✅

完整逐 API 对照（含字段级说明）见三层 API 对比。

最小可用插件

html

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="wad:id" content="hello">
  <meta name="wad:package" content="hello">
  <meta name="wad:version" content="1.0.0">
  <meta name="wad:versionCode" content="1">
  <meta name="wad:author" content="you">
  <meta name="wad:name" content="你好">
  <meta name="wad:description" content="最小可用插件">

  <script type="text/wad-logic">
    // 逻辑层全局：wadLogicLayer
    wadLogicLayer.onAttach(function (appid) {
      wadLogicLayer.log('hello 已注入 ' + appid);
      wadLogicLayer.register('greet', function (name) { return '你好，' + name; });
    });
  </script>
</head>
<body>
  <h3>你好</h3>
  <button id="go">打个招呼</button>
  <script>
    // 面板全局：wadPanelLayer
    document.getElementById('go').onclick = async function () {
      const msg = await wadPanelLayer.logicLayer.call('greet', 'WeAppDev');  // 可变参
      wadPanelLayer.ui.toast(msg);
    };
  </script>
</body>
</html>

安装方式（管理页导入 / 市场分发 / zip 带资产）见快速开始与安装、签名与上架。

文档索引

文档	内容
快速开始	30 秒上手、meta 字段、硬限制
核心 API	身份、instance、ready、log、错误约定
三层 API 对比	每个 API 在三层的行为对照
工具包 tools	md5/sha256/base64/uuid/… 三层同一实现
逻辑层	wadLogicLayer 全量（本地 + 跨层）
渲染层	wadRenderLayer 全量（DOM/Web Storage/eval）
面板 UI	wadPanelLayer.ui、storage、onOpen/onClose
事件系统	attach/detach/messaging/watch 三类事件
生命周期与回调	投递矩阵、注入时序、钩子糖全表
共享存储	sharedStorage.app/global/watch
消息广播	messaging.emit/on/onAny + 回声过滤
HTTP 请求	统一网络 API + 改写请求/响应五类案例
通过插件 · 网络重写	声明式规则
通过插件 · 网络脚本	JS 请求/响应回调
抓包与改写 capture	records/rules/addRule 插件侧 API
通过插件 · Native脚本	mmtls/ilink 请求/响应 intercept/observe
跨层调用实例集	15 个可直接抄的组合
存储	四种存储怎么选
资源与 WASM	assets 全量 + wasm 实战
插件多层函数注册	register/call
断点调试	debugger 全量
安装与上架	zip、签名、市场

官方插件案例

插件Demo · 修改定位：包装定位 API，真实/接管坐标对照
插件Demo · 替换 wx.login 的 Code：登录 code 替换与 detach 恢复
插件Demo · 跳一跳无敌：动作断点自动改落点/分数，无暂停感

下一步

快速开始：30 秒写出第一个三上下文插件
三层 API 对比：每个 API 在三层的行为对照

插件系统总览（Plugin API 1.0） ​

三个全局变量 ​

wadLogicLayer（逻辑层） ​

wadRenderLayer（渲染层） ​

wadPanelLayer（面板） ​

三个上下文 ​

支持矩阵（速查） ​

最小可用插件 ​

文档索引 ​

官方插件案例 ​

下一步 ​

插件系统总览（Plugin API 1.0）

三个全局变量

wadLogicLayer（逻辑层）

wadRenderLayer（渲染层）

wadPanelLayer（面板）

三个上下文

支持矩阵（速查）

最小可用插件

文档索引

官方插件案例

下一步