Files
marqdo/lib/浏览器.mq.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

23 KiB
Executable File
Raw Permalink Blame History

markup, title, description, import
markup title description import
occlusion lib/浏览器 浏览器效应助手(WASM 客户端)。优先 GFM 表格 + 本库;勿用 json.set 链拼效应。
table browser
lib/table.mq.md lib/browser.mq.md

浏览器效应助手(WASM 客户端)。优先 GFM 表格 + 本库;勿用 json.set 链拼效应。

使用普通结构化值构造浏览器效果。

能力与边界:构造效果是纯数据变换,由官方 WASM 桥接在浏览器中执行。原生进程生成效果记录不表示 DOM 已更新;业务逻辑仍写在 Marqdo 中。

本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。

实现入口:crates/marqdo-wasm/js/marqdo-bridge.js

开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。

设文本

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
文本 any 必填 本操作读取、转换或输出的文本
返回 类型 说明
result map 构造 set_text 效应

这里使用选择器、文本。

调用效应:pure。

直接调用此函数:

marqdo call lib/浏览器.mq.md 设文本 '选择器="#status"' '文本="Ready"' --effects none --json

构造 set_text 效应。

得到**m = [返回更新后的结构化值](table.put(in=None, at=选择器, value=文本))**。 完成后返回*[在新记录中设置 set_text 字段](table.put(in=None, at="set_text", value=m))*。

设HTML

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
html any 必填 HTML 片段;普通不可信文本应使用设文本
返回 类型 说明
result map 构造 set_html 效应

这里使用选择器、html。

调用效应:pure。

构造 set_html 效应。

得到**m = [返回更新后的结构化值](table.put(in=None, at=选择器, value=html))**。 完成后返回*[在新记录中设置 set_html 字段](table.put(in=None, at="set_html", value=m))*。

设值

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
值 any 必填 待转换或保存的值;不会就地修改输入
返回 类型 说明
result map 构造 set_value 效应

这里使用选择器、值。

调用效应:pure。

构造 set_value 效应。

得到**m = [返回更新后的结构化值](table.put(in=None, at=选择器, value=值))**。 完成后返回*[在新记录中设置 set_value 字段](table.put(in=None, at="set_value", value=m))*。

设类

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
类 any 必填 以空格分隔的 CSS 类名
返回 类型 说明
result map 构造 set_class 效应

这里使用选择器、类。

调用效应:pure。

构造 set_class 效应。

得到**m = [返回更新后的结构化值](table.put(in=None, at=选择器, value=类))**。 完成后返回*[在新记录中设置 set_class 字段](table.put(in=None, at="set_class", value=m))*。

加类

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
类 any 必填 以空格分隔的 CSS 类名
返回 类型 说明
result map 构造 add_class 效应(classList.add;可用空格分隔多个类名)

这里使用选择器、类。

调用效应:pure。

构造 add_class 效应(classList.add;可用空格分隔多个类名)。

得到**m = [返回更新后的结构化值](table.put(in=None, at=选择器, value=类))**。 完成后返回*[在新记录中设置 add_class 字段](table.put(in=None, at="add_class", value=m))*。

去类

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
类 any 必填 以空格分隔的 CSS 类名
返回 类型 说明
result map 构造 remove_class 效应

这里使用选择器、类。

调用效应:pure。

构造 remove_class 效应。

得到**m = [返回更新后的结构化值](table.put(in=None, at=选择器, value=类))**。 完成后返回*[在新记录中设置 remove_class 字段](table.put(in=None, at="remove_class", value=m))*。

切类

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
类 any 必填 以空格分隔的 CSS 类名
返回 类型 说明
result map 构造 toggle_class 效应

这里使用选择器、类。

调用效应:pure。

构造 toggle_class 效应。

得到**m = [返回更新后的结构化值](table.put(in=None, at=选择器, value=类))**。 完成后返回*[在新记录中设置 toggle_class 字段](table.put(in=None, at="toggle_class", value=m))*。

设样式

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
样式 any 必填 目标元素的 CSS 属性与值记录
返回 类型 说明
result map 构造 set_style 效应;样式为属性表或 cssText 字符串

这里使用选择器、样式。

调用效应:pure。

构造 set_style 效应;样式为属性表或 cssText 字符串。

得到**m = [返回更新后的结构化值](table.put(in=None, at=选择器, value=样式))**。 完成后返回*[在新记录中设置 set_style 字段](table.put(in=None, at="set_style", value=m))*。

设属性

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
属性 any 必填 目标元素的 HTML 属性与值记录
返回 类型 说明
result map 构造 set_attr 效应

这里使用选择器、属性。

调用效应:pure。

构造 set_attr 效应。

得到**m = [返回更新后的结构化值](table.put(in=None, at=选择器, value=属性))**。 完成后返回*[在新记录中设置 set_attr 字段](table.put(in=None, at="set_attr", value=m))*。

包装

参数 类型 默认 说明
键 any 必填 要读取、比较或更新的字段名或存储键
值 any 必填 待转换或保存的值;不会就地修改输入
返回 类型 说明
result map 单键效应包装

这里使用键、值。

调用效应:pure。

单键效应包装。

完成后返回*[返回更新后的结构化值](table.put(in=None, at=键, value=值))*。

合并

参数 类型 默认 说明
甲 any 必填 第一个浏览器效果记录
乙 any 必填 合入第一个记录的浏览器效果记录
返回 类型 说明
result map 合并两张效应表,右侧优先

这里使用甲、乙。

调用效应:pure。

合并两张效应表,右侧优先。

完成后返回*[调用 merge](table.merge(a=甲, b=乙))*。

画布

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
命令 any 必填 按执行顺序排列的画布绘制命令列表
清空 any True 绘制命令前是否清空画布
返回 类型 说明
result map 构造 canvas 效应;命令一般为 @ 行表

这里使用选择器、命令、清空=True。

调用效应:pure。

构造 canvas 效应;命令一般为 @ 行表。

spec =

sel clear commands
选择器 清空 命令

完成后返回*[在新记录中设置 canvas 字段](table.put(in=None, at="canvas", value=spec))*。

音频

参数 类型 默认 说明
操作 any "play" 音频命令:play、pause 或 stop
id any "default" 音频通道标识
源 any "" 音频 URL;beep 表示合成提示音
频率 any None 振荡器频率,单位 Hz
毫秒 any None 时长或延迟,单位毫秒
选择器 any "" 目标浏览器元素的 CSS 选择器
返回 类型 说明
result map 构造 audio 效应

这里使用操作="play"、id="default"、源=""、频率=None、毫秒=None、选择器=""。

调用效应:pure。

构造 audio 效应。

本函数只返回效果记录,不会立刻播放声音。播放源、合成频率与音频元素按桥接规则选择;浏览器可能要求用户先交互。

得到**spec = [在新记录中设置 op 字段](table.put(in=None, at="op", value=操作))。 得到spec = [在新记录中设置 id 字段](table.put(in=spec, at="id", value=id))**。

  1. 源 != "" 得到**spec = [在新记录中设置 src 字段](table.put(in=spec, at="src", value=源))**。
  2. 频率 != None 得到**spec = [在新记录中设置 freq 字段](table.put(in=spec, at="freq", value=频率))**。
  3. 毫秒 != None 得到**spec = [在新记录中设置 ms 字段](table.put(in=spec, at="ms", value=毫秒))**。
  4. 选择器 != "" 得到**spec = [在新记录中设置 sel 字段](table.put(in=spec, at="sel", value=选择器))**。 完成后返回*[在新记录中设置 audio 字段](table.put(in=None, at="audio", value=spec))*。

读文件

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
然后 any 必填 桥接结果回调的 Marqdo 函数名;空文本表示无回调
格式 any "text" 浏览器桥接读取文件所用的内容表示
返回 类型 说明
result map 构造 read_file 效应

这里使用选择器、然后、格式="text"。

调用效应:pure。

构造 read_file 效应。

spec =

sel as then
选择器 格式 然后

完成后返回*[在新记录中设置 read_file 字段](table.put(in=None, at="read_file", value=spec))*。

观察

参数 类型 默认 说明
规格 any 必填 效果规格;使用单条记录或 @ 行记录列表
返回 类型 说明
result map 构造 observe 效应

这里使用规格。

调用效应:pure。

构造 observe 效应。

完成后返回*[在新记录中设置 observe 字段](table.put(in=None, at="observe", value=规格))*。

取消观察

参数 类型 默认 说明
规格 any 必填 效果规格;使用单条记录或 @ 行记录列表
返回 类型 说明
result map 构造 unobserve 效应

这里使用规格。

调用效应:pure。

构造 unobserve 效应。

完成后返回*[在新记录中设置 unobserve 字段](table.put(in=None, at="unobserve", value=规格))*。

聚焦

参数 类型 默认 说明
选择器 any 必填 目标浏览器元素的 CSS 选择器
返回 类型 说明
result map 构造目标元素的聚焦效果;浏览器桥接在处理函数返回后执行

这里使用选择器。

调用效应:pure。

构造目标元素的聚焦效果;浏览器桥接在处理函数返回后执行。

完成后返回*[在新记录中设置 focus 字段](table.put(in=None, at="focus", value=选择器))*。

导航

参数 类型 默认 说明
url text 必填 目标 URL;HTTP 接口接受 http 或 https
替换 any False 导航时是否替换当前历史项
返回 类型 说明
result map 构造 navigate 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面

这里使用url、替换=False。

调用效应:pure。

构造 navigate 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面。

spec =

url replace
url 替换

完成后返回*[在新记录中设置 navigate 字段](table.put(in=None, at="navigate", value=spec))*。

存设

参数 类型 默认 说明
键 any 必填 要读取、比较或更新的字段名或存储键
值 any 必填 待转换或保存的值;不会就地修改输入
作用域 any "memory" 存储范围:memory、local 或 session
然后 any "" 桥接结果回调的 Marqdo 函数名;空文本表示无回调
返回 类型 说明
result map SPA 客户端状态写入

这里使用键、值、作用域="memory"、然后=""。

调用效应:pure。

SPA 客户端状态写入。优先 作用域=memory(页内内存)。 可选 然后:写入后回调,参数含 {ok, op, key, scope}。

spec =

op key value scope
set 键 值 作用域
  1. 然后 != "" 得到**spec = [在新记录中设置 then 字段](table.put(in=spec, at="then", value=然后))**。 完成后返回*[在新记录中设置 storage 字段](table.put(in=None, at="storage", value=spec))*。

存取

参数 类型 默认 说明
键 any 必填 要读取、比较或更新的字段名或存储键
然后 any 必填 桥接结果回调的 Marqdo 函数名;空文本表示无回调
作用域 any "memory" 存储范围:memory、local 或 session
返回 类型 说明
result map 读取键并回调 然后,参数含 {ok, value, found, key, scope}

这里使用键、然后、作用域="memory"。

调用效应:pure。

读取键并回调 然后,参数含 {ok, value, found, key, scope}。

spec =

op key then scope
get 键 然后 作用域

完成后返回*[在新记录中设置 storage 字段](table.put(in=None, at="storage", value=spec))*。

页跳

参数 类型 默认 说明
url text 必填 目标 URL;HTTP 接口接受 http 或 https
替换 any False 导航时是否替换当前历史项
返回 类型 说明
result map SPA 导航(bridge navigate)

这里使用url、替换=False。

调用效应:pure。

SPA 导航(bridge navigate)。

spec =

url replace
url 替换

完成后返回*[在新记录中设置 navigate 字段](table.put(in=None, at="navigate", value=spec))*。

存储

参数 类型 默认 说明
规格 any 必填 存储操作记录:op、key、scope,以及可选 value 和 then
返回 类型 说明
result map 把存储规格包装为浏览器效果;桥接处理 op、key、value、scope 和 then

这里使用规格。

调用效应:pure。

把存储规格包装为浏览器效果;桥接处理 op、key、value、scope 和 then。

完成后返回*[在新记录中设置 storage 字段](table.put(in=None, at="storage", value=规格))*。

定时

参数 类型 默认 说明
毫秒 any 必填 时长或延迟,单位毫秒
然后 any 必填 桥接结果回调的 Marqdo 函数名;空文本表示无回调
id any "default" 定时器标识,之后传给清除定时器
返回 类型 说明
result map 构造 interval 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面

这里使用毫秒、然后、id="default"。

调用效应:pure。

构造 interval 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面。

spec =

ms then id
毫秒 然后 id

完成后返回*[在新记录中设置 interval 字段](table.put(in=None, at="interval", value=spec))*。

清定时

参数 类型 默认 说明
id any "default" 对应创建或启动操作返回的标识
返回 类型 说明
result map 使用创建定时器时相同的标识,构造取消定时器效果

这里使用id="default"。

调用效应:pure。

使用创建定时器时相同的标识,构造取消定时器效果。

得到**spec = [在新记录中设置 id 字段](table.put(in=None, at="id", value=id))**。 完成后返回*[在新记录中设置 clear_interval 字段](table.put(in=None, at="clear_interval", value=spec))*。

拉取

参数 类型 默认 说明
url text 必填 目标 URL;HTTP 接口接受 http 或 https
然后 any 必填 桥接结果回调的 Marqdo 函数名;空文本表示无回调
方法 any "GET" HTTP 方法,例如 GET 或 POST
返回 类型 说明
result map 构造 fetch 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面

这里使用url、然后、方法="GET"。

调用效应:pure。

构造 fetch 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面。

spec =

url then method
url 然后 方法

完成后返回*[在新记录中设置 fetch 字段](table.put(in=None, at="fetch", value=spec))*。

拉取全部

参数 类型 默认 说明
请求 any 必填 按顺序排列的浏览器请求规格记录列表
然后 any 必填 桥接结果回调的 Marqdo 函数名;空文本表示无回调
返回 类型 说明
result map 构造 fetch_all 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面

这里使用请求、然后。

调用效应:pure。

构造 fetch_all 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面。

spec =

requests then
请求 然后

完成后返回*[在新记录中设置 fetch_all 字段](table.put(in=None, at="fetch_all", value=spec))*。

延后

参数 类型 默认 说明
毫秒 any 必填 时长或延迟,单位毫秒
然后 any 必填 桥接结果回调的 Marqdo 函数名;空文本表示无回调
返回 类型 说明
result map 构造 after 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面

这里使用毫秒、然后。

调用效应:pure。

构造 after 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面。

spec =

ms then
毫秒 然后

完成后返回*[在新记录中设置 after 字段](table.put(in=None, at="after", value=spec))*。

套接字

参数 类型 默认 说明
规格 any 必填 一条桥接效果规格记录
返回 类型 说明
result map 把 WebSocket 操作规格包装为浏览器桥接效果;本函数不会打开原生套接字

这里使用规格。

调用效应:pure。

把 WebSocket 操作规格包装为浏览器桥接效果;本函数不会打开原生套接字。

完成后返回*[在新记录中设置 ws 字段](table.put(in=None, at="ws", value=规格))*。

剪贴板

参数 类型 默认 说明
文本 any 必填 本操作读取、转换或输出的文本
返回 类型 说明
result map 按文本构造剪贴板效果;消费效果时仍受浏览器权限和用户手势要求约束

这里使用文本。

调用效应:pure。

按文本构造剪贴板效果;消费效果时仍受浏览器权限和用户手势要求约束。

得到**spec = [在新记录中设置 text 字段](table.put(in=None, at="text", value=文本))**。 完成后返回*[在新记录中设置 clipboard 字段](table.put(in=None, at="clipboard", value=spec))*。

下载

参数 类型 默认 说明
正文 any 必填 请求正文;文档操作中为替换正文
文件名 any "download.txt" 建议的下载文件名
mime any "text/plain;charset=utf-8" 内容的 MIME 类型
返回 类型 说明
result map 构造 download 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面

这里使用正文、文件名="download.txt"、mime="text/plain;charset=utf-8"。

调用效应:pure。

构造 download 效果记录,由浏览器桥接消费后执行;调用本函数本身不修改页面。

spec =

body filename mime
正文 文件名 mime

完成后返回*[在新记录中设置 download 字段](table.put(in=None, at="download", value=spec))*。

渲染列表

参数 类型 默认 说明
选择器 text 必填 已有列表容器的 CSS 选择器
条目 list 必填 字面文字或含 tag、text 或 children、class、attrs 的记录列表
标签 text "li" 官方桥使用的元素名,通常为 li
返回 类型 说明
result map 交给官方浏览器桥执行的纯列表更新指令

这里使用选择器、条目和标签="li"。动态数据按记录传入,文字放在 text,委托事件需要的标识放在 attrs 的 data-id;无需手动拼接列表 HTML。官方桥会转义普通文字,但构造指令不表示已经更新页面,也不验证选择器确实存在。标签与属性名由应用决定,业务输入应保留为文字。页面最初的容器布局仍由 Document 组件负责,这个工具只替换已存在列表的条目。

记录还可包含 tag 与 children,children 是同样结构的文本/控件记录列表。例如一条 li 内先放 span 文本,再放带 data-id 的 button,删除交互就不需要拼 HTML。text、html 与 children 不混用;嵌套最多 32 层,总记录最多 10000。元素名和属性名经过结构检查,事件属性与活动 URL 被拒绝。用户内容放 text,原有 html 只保留明确的兼容出口。

下例直接返回组合指令,不加载服务器插件,也不执行浏览器 IO;真实的 浏览器工程 使用同一结构。元素、属性名与兼容 html 都属于作者决定的能力,外部业务值应只进入 text 或标量属性值。结构检查不能替代对显式原生 HTML 的内容清理。

marqdo call lib/浏览器.mq.md 渲染列表 '选择器="#items"' '条目=[{"tag":"li","children":[{"tag":"span","text":"字面 <文字> & 内容"},{"tag":"button","text":"删除","attrs":{"type":"button","data-id":"1"}}]}]' --effects none --json

完成后返回*[描述已有列表的文字更新](browser.render_list(sel=选择器, items=条目, tag=标签))*.