网页应用接口规范 0.1.0
本包让一个浏览器里的豫言应用启动同一站点上的另一个豫言浏览器应用。云控制台的各服务页(用量分析、AI 市场)各是一个独立构建的豫言应用,宿主页里的控制台应用在需要时把它们挂到页面上,而不必让页面另写 JavaScript 去动态加载。应用依赖本包后,全部函数都必须实现。
“豫言浏览器应用”指构建器生成的应用目录:目录里有加载器 入口.mjs(导出 启动豫言浏览器应用(选项))、程序.wasm、值桥.wasm、宿主 JS 与接口清单;子应用有自己的 Wasm 实例、自己的统一事件队列、自己的句柄表,与父应用只通过页面本身(DOM、网页消息)交换信息。
函数
启动页面应用 : 字符串 → 有
参数是子应用加载器的站内路径,例如 /AI市场应用/入口.mjs。宿主:
- 校验路径(见下);
- 动态加载该模块,调用它导出的
启动豫言浏览器应用()(应用文件的位置默认是该模块所在目录); - 挂起当前调用,直到子应用就绪——它第一次进入事件等待,或已经运行结束;就绪前父应用的事件照常排队;
- 返回。子应用此后独立运行,直到页面结束或父应用结束(宿主关闭时子应用一并关闭);父应用无法停止或查询它。
路径规则:以 / 开头且不以 // 开头;以 /入口.mjs 结尾;至多 512 个 UTF-16 码元;不含 ..、. 目录段、查询(?)、片段(#)、反斜杠、控制字符与百分号编码。违反属违规调用。
限额与失败:同一路径在一个页面里只能启动一次(重复启动抛事故,避免两个应用争抢同一片 DOM);同时最多启动 8 个子应用;模块不存在或加载失败、模块没有导出 启动豫言浏览器应用、子应用装载或接口核对失败、30 秒内未就绪,都抛事故并带中文说明(子应用启动后才发生的失败不影响父应用)。
使用约定
- 先备好 DOM,再启动:子应用在启动时读取页面里它需要的元素与订阅事件,所以父应用要先用文树接口(例如
装入页面模板)把子应用的容器与静态骨架放到页面里,再调用启动页面应用。 - 一个页面里各应用的元素 ID 不得冲突(子应用按 ID 读写页面)。
- 父子之间要通信,用网页消息包(前缀“豫言”的文档消息)。
一致性样例
- 页面已有
<div id="子根"></div>;父应用启动页面应用("/子应用/入口.mjs")返回后,子应用已经把文字写进子根,并且响应它订阅的点击。 - 再次
启动页面应用("/子应用/入口.mjs"):抛事故(已启动)。 启动页面应用("/子应用/程序.wasm")、启动页面应用("../入口.mjs")、启动页面应用("/子应用/入口.mjs?x=1"):抛事故(路径不合规)。- 路径合规但文件不存在:抛事故,说明加载失败。
- 子应用启动期间到达的父应用事件(点击、消息)不丢,
启动页面应用返回后可取到。
边界
本包不规定:停止或重启子应用、把参数传给子应用(用页面 DOM 与网页消息)、跨来源的应用、子应用退出的通知、共享内存或共享句柄。