Bridge.js 接口说明

创意工坊小程序通过引入桥接文件 wordmomo_dev_bridge.js 获得全部能力。引入后页面全局会出现 window.WordMomo 对象，所有方法都返回 Promise。

API 按命名空间分类，便于理解和管理：

命名空间	说明
`WordMomo.session`	会话与单词数据（获取信息/单词、完成/退出会话）
`WordMomo.sound`	发音播放
`WordMomo.window`	主窗口控制（大小/最大化/主题/背景色）
`WordMomo.review`	复习算法（选项/提交结果）
`WordMomo.word`	单词状态（掌握/收藏/评分/显示次数）

引入方式

在 HTML 的 <head> 或 <body> 中加入：

html

<script src="http://127.0.0.1:27531/bridge/wordmomo_dev_bridge.js"></script>

bridge.js 会以自身 script 的 origin 作为 API 地址，因此：

正式模式（从创意工坊入口打开）：页面与 bridge 同域，也可以用相对路径 /bridge/wordmomo_dev_bridge.js；URL 自动携带 ?session=xxx，返回真实单词。
调试模式（file:// 或本地 dev server 打开）：引用上面的绝对地址，URL 无 session 参数，自动进入调试模式返回虚拟单词。

推荐的兼容写法（正式/调试自动切换）：

html

<script>
(function () {
  var s = document.createElement("script");
  s.src = "/bridge/wordmomo_dev_bridge.js";        // 正式模式同域加载
  s.onerror = function () {                        // 调试模式回退默认端口
    var f = document.createElement("script");
    f.src = "http://127.0.0.1:27531/bridge/wordmomo_dev_bridge.js";
    document.head.appendChild(f);
  };
  document.head.appendChild(s);
})();
</script>

由于加载是异步的，建议封装一个等待函数再调用 API：

function waitForBridge() {
  return new Promise(function (resolve) {
    var waited = 0;
    var timer = setInterval(function () {
      waited += 100;
      if (typeof WordMomo !== "undefined" || waited >= 5000) {
        clearInterval(timer);
        resolve(typeof WordMomo !== "undefined");
      }
    }, 100);
  });
}

模式判断

WordMomo.isMock   // true = 调试模式（虚拟数据，写操作不落库）

调试模式下所有写方法直接返回成功并在 console 输出提示，不会修改真实学习数据。

WordMomo.session — 会话与单词数据

session.getInfo()

const info = await WordMomo.session.getInfo();

{
  isMock: false,        // 是否调试模式
  appId: "3f2a...",     // 小程序 ID
  bookId: "xxx",        // 词书 ID
  bookName: "四级词汇",  // 词书名称
  language: "en",       // 语言
  sourceKey: "learn-new", // 词源（学新/复习/收藏等）
  wordCount: 50          // 本次单词数
}

session.getWords()

const words = await WordMomo.session.getWords();

返回单词数组，每个元素：

{
  wordId: "xxx",           // 单词唯一 ID（写操作都靠它定位）
  word: "apple",           // 单词文本
  translate: "n. 苹果",     // 译文（含扩展资料回退）
  symbol: "ˈæpl",          // 音标（含扩展资料回退）
  learnStatus: 0,          // 学习状态
  collected: 0,            // 是否收藏 0/1
  scoreValue: 0,           // 词汇评分
  reviewCount: 0,          // 复习次数
  showCount: 0,            // 显示次数
  nextReviewTime: "",      // 下次复习时间
  examples: [              // 例句列表
    { word: "apple", mean: "", amp: "An apple a day...", trans: "一天一苹果..." }
  ],
  notes: [                 // 笔记列表
    { type: 0, label: "词根", content: "..." }
  ]
}

session.complete(result?)

await WordMomo.session.complete({
  score: 95,
  detail: { correct: 48, wrong: 2 }
});

上报学习结果、停止学习计时并关闭会话。result 为任意对象，软件仅做记录。

session.exit()

await WordMomo.session.exit();  // 等价 session.complete({})

关闭会话。调用后页面可提示用户关闭窗口。

WordMomo.sound — 发音

sound.play(text, options?)

await WordMomo.sound.play("apple");
await WordMomo.sound.play("apple", { speed: 0.8 });  // speed 默认 1.0

使用当前词书配置的发音人播放。正式/调试模式都会真实发声。

WordMomo.window — 主窗口控制

不要求会话，正式/调试模式都生效，仅影响 WordMomo 主窗口。

window.setSize(width, height, options?)

await WordMomo.window.setSize(1280, 800);                   // 调整后自动居中
await WordMomo.window.setSize(1280, 800, { center: false }); // 不居中

若窗口当前处于最大化状态，会先自动还原再调整尺寸。

window.setMaximized(maximized)

await WordMomo.window.setMaximized(true);   // 最大化
await WordMomo.window.setMaximized(false);  // 还原

常见用法：游戏类小程序加载完成后直接最大化：

await waitForBridge();
WordMomo.window.setMaximized(true).catch(function () {});

window.getTheme()

const theme = await WordMomo.window.getTheme();
// { theme: "dark", skinIndex: 1 }   // theme: "light" | "dark"

获取主窗口当前主题，小程序可据此切换自己的亮/暗配色。

window.getBackgroundColor()

const bg = await WordMomo.window.getBackgroundColor();
// "#181a1f"   // #RRGGBB 格式，可直接用于 CSS

获取主窗口当前的背景颜色。配合 getTheme() 可让小程序背景与主窗口融为一体：

await waitForBridge();
var theme = await WordMomo.window.getTheme();
var bg = await WordMomo.window.getBackgroundColor();
document.body.style.backgroundColor = bg;
document.body.classList.toggle("dark", theme.theme === "dark");

WordMomo.review — 复习（写）

与内置学习工具使用完全相同的复习算法。

review.getOptions(wordId)

const options = await WordMomo.review.getOptions(wordId);
// [{ menuKey: "again", menuName: "重来", color: "ffff4444", remark: "1分钟" }, ...]

remark 是按当前算法计算出的「下次复习时间」预览，可直接展示给用户。

review.submit(wordId, reviewKey)

await WordMomo.review.submit(wordId, "good");  // reviewKey 取 getOptions 返回的 menuKey

提交一次复习结果，更新该单词的下次复习时间并落库。

WordMomo.word — 单词状态（写）

await WordMomo.word.setMastered(wordId);          // 标记为已掌握
await WordMomo.word.setCollected(wordId, 1);      // 收藏；传 0 取消收藏
await WordMomo.word.updateScore(wordId, 1);       // 评分 +1（答对）；传 -1 答错
await WordMomo.word.addShowCount(wordId);         // 显示次数 +1

以上方法在调试模式下均为 no-op，只会在 console 提示。

完整示例

一个最小可运行的单词闪卡小程序：

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>闪卡示例</title>
<style>
  body { font-family: sans-serif; text-align: center; padding-top: 15vh; }
  #word { font-size: 48px; font-weight: 800; }
  #trans { font-size: 24px; color: #666; margin: 16px 0; }
  button { font-size: 18px; padding: 8px 24px; margin: 4px; cursor: pointer; }
</style>
<script src="http://127.0.0.1:27531/bridge/wordmomo_dev_bridge.js"></script>
</head>
<body>
  <div id="word">加载中...</div>
  <div id="trans" hidden></div>
  <button id="speak">🔊 发音</button>
  <button id="show">显示释义</button>
  <button id="know">认识 ✔</button>
  <button id="dont">不认识 ✘</button>

<script>
var words = [], idx = 0;

function render() {
  var w = words[idx];
  document.getElementById("word").textContent = w.word;
  var t = document.getElementById("trans");
  t.textContent = w.translate;
  t.hidden = true;
}

function next(delta) {
  WordMomo.word.updateScore(words[idx].wordId, delta).catch(function () {});
  WordMomo.word.addShowCount(words[idx].wordId).catch(function () {});
  idx++;
  if (idx >= words.length) {
    WordMomo.session.complete({ score: 100 }).catch(function () {});
    document.body.innerHTML = "<h1>完成！可以关闭本窗口</h1>";
    return;
  }
  render();
}

window.addEventListener("load", async function () {
  await WordMomo.window.setMaximized(true).catch(function () {});
  // 让页面背景跟随主窗口
  var bg = await WordMomo.window.getBackgroundColor().catch(function () { return null; });
  if (bg) document.body.style.backgroundColor = bg;

  words = await WordMomo.session.getWords();
  render();

  document.getElementById("show").onclick = function () {
    document.getElementById("trans").hidden = false;
  };
  document.getElementById("speak").onclick = function () {
    WordMomo.sound.play(words[idx].word).catch(function () {});
  };
  document.getElementById("know").onclick = function () { next(1); };
  document.getElementById("dont").onclick = function () { next(-1); };
});
</script>
</body>
</html>

调试技巧：把文件保存后直接用浏览器打开即为调试模式（虚拟数据）；调试完成后到「学习管理 → 创意工坊 → 创建小程序」粘贴代码，即可用真实单词运行。

旧版 API 兼容

2026-07 之前的版本使用扁平方法名（如 WordMomo.getWords()、WordMomo.playSound()）。这些旧方法名在软件端仍被兼容，已发布的小程序无需修改即可继续运行；新开发的小程序请使用上表的命名空间写法。

错误处理

所有 API 失败时会 reject 一个 Error：

session expired：会话不存在或已超时（创建后 2 小时无活动自动清理）
not found the word：wordId 不在本次会话单词中
unknown method: xxx：方法名错误

建议对写操作静默处理，不阻断小程序主流程：

function wmCall(fn) {
  try { Promise.resolve(fn()).catch(function () {}); } catch (e) {}
}
wmCall(function () { return WordMomo.word.updateScore(wordId, 1); });

Bridge.js 接口说明 ​

引入方式 ​

模式判断 ​

WordMomo.session — 会话与单词数据 ​

session.getInfo() ​

session.getWords() ​

session.complete(result?) ​

session.exit() ​

WordMomo.sound — 发音 ​

sound.play(text, options?) ​

WordMomo.window — 主窗口控制 ​

window.setSize(width, height, options?) ​

window.setMaximized(maximized) ​

window.getTheme() ​

window.getBackgroundColor() ​

WordMomo.review — 复习（写） ​

review.getOptions(wordId) ​

review.submit(wordId, reviewKey) ​

WordMomo.word — 单词状态（写） ​

完整示例 ​

旧版 API 兼容 ​

错误处理 ​

Bridge.js 接口说明

引入方式

模式判断

WordMomo.session — 会话与单词数据

session.getInfo()

session.getWords()

session.complete(result?)

session.exit()

WordMomo.sound — 发音

sound.play(text, options?)

WordMomo.window — 主窗口控制

window.setSize(width, height, options?)

window.setMaximized(maximized)

window.getTheme()

window.getBackgroundColor()

WordMomo.review — 复习（写）

review.getOptions(wordId)

review.submit(wordId, reviewKey)

WordMomo.word — 单词状态（写）

完整示例

旧版 API 兼容

错误处理