给课本点读造一把"尺子"——从热点偏移到像素级精准标注的实战

给课本点读造一把"尺子"——从热点偏移到像素级精准标注的实战

记录一次完整的前端工程闭环:把 50MB 的单文件点读网页拆成可维护的工程、把"点一下读一串"改成"一句一框"、定位并修复 hotspots 偏移,最后亲手做了一台可视化标注 + 播放工具,把坐标精度钉死在真实浏览器的 DOM 测量上。本文所有结论都来自真实 Chrome + CDP 驱动下的断言,而不是"看起来对了"。

写在前面

给六年级英语课本做一个"点哪句读哪句"的离线网页,听起来是个小工具。真做起来才发现,最难的从来不是"把音频接上",而是几个让人抓狂的问题:

  • 课本扫描图在不同屏幕、不同缩放下,点读热区为什么会偏移?到底是浏览器的锅,还是标注数据本身错了?
  • "点一下读一串"为什么体验很差,怎样才能做到一个框恰好对应一句完整的话?
  • 有没有办法把标注、调框、绑定音频、命中验证做成一条可复用、可量化的流程,而不是每次靠肉眼对齐?

这篇文章就把这趟从"能用"到"精准"的路走一遍。

最终的点读 App——顶部绿色导航、课本扫描图、点击后高亮的句框、中英译文条与底部绿色播放器
图1:最终的点读 App——绿色导航、课本图、高亮句框、中英译文条与底部播放器

一、缘起:一个"能点读的课本"需求

项目起点是一份 2026 秋人教 PEP 六年级上册的官方资源:50 段整课时 mp3、99 页课本扫描图。目标很直接——做成一个手机上打开就能点读的离线网页。

第一版是单 HTML 文件:50 段音频压成 64kbps 单声道后 base64 内嵌,图片也内嵌,40MB 左右,file:// 双击即用。逐句定位靠的是端上静音检测切分——20ms 能量窗、自适应阈值、≥260ms 静音为界,把整课时音频切成句子。这一版做到了"点句子列表发声",但和真人教点读还有差距:点课本图上的文字区域发声这件事没做。

于是有了后面几轮迭代。

二、三次迭代:布局、热区与"一句一框"

第一次:像 App 一样的布局

参考真实的人教点读 App 重排了界面:绿色渐变顶栏、课本图占主导、底部绿色播放器带复读/连读/测评/背诵四色圆钮,搜索和 50 个课时目录全部收进左侧抽屉。列表默认隐藏,点"≡列表"再展开。

目录抽屉——50 个课时、搜索框、显示设置都收进侧滑面板
图2:目录抽屉——50 个课时、搜索框、显示设置都收进侧滑面板

第二次:热区去底色 + 触摸翻页 + 遮挡修复

用户反馈很具体:热点高亮"不用底色,单独呈现虚线就可以,现在看不清语句了"。于是把 .hz.on 从半透明绿底改成只有绿色虚线框 + 小喇叭,课本印刷文字重新清晰可读。

同一轮还加了左右滑动翻页:在图片上 touchstart/touchend 监听,水平位移 >40px 且水平主导、时长 <700ms 就翻页;点按(无位移)仍触发点读,滑动后抑制误触 click。

还有一个隐蔽的 bug:译文条被底部播放器压住 5px。根因是 --player-h:150px 这个经验值——真实播放器高 155px。解法是运行时 fitPlayer() 读 player.offsetHeight 再写回 CSS 变量,让布局按真实高度预留空间。

第三次:一框一句

原来的 v2 热区以"行归属"合并同几何框的多句,s 数组塞进 2~7 句,点一下连读多句、译文条只显示第一句。数据诊断更触目惊心:全库 1136 句里有 400 个是 1 词碎片("Took."/"Walked."/"Ate." 这类词表词,被 OCR 对齐噪声挂到课文行上),40.9% 的热区是多句框。

于是写了 build_hotzones_v3:每框 s 恒为恰好 1 句;完整句(≥2 词)优先,挂在课文行上的单词碎片直接丢弃;一行含多个完整句时按词数比例水平横切成独立框;同一句跨行只生成第一个框。结果:753 个框全部单句,多句框归零,零几何重叠,完整句覆盖 586/736(约 79.6%)。

一框一句——点中某句时只有那一个虚线框高亮,译文条显示对应的中英对照
图3:一框一句——点中某句时只有那一个虚线框高亮,译文条显示对应的中英对照

三、真正的难题:热点为什么会"偏移"?

前面的迭代里,"前十页有些热点位置显示偏移"一直是悬案。到底是谁的锅?

诊断过程是这样的:把同一页图片和同一份标注 JSON,分别在不同缩放、不同视口下渲染,然后逐一比对"标注框中心点换算回原图的坐标"和"真实图片像素坐标"。结论出人意料——标注数据是对的,偏移来自 CSS 渲染。

罪魁祸首是这一行:

#imgwrap img { max-height: 100%; }

看起来人畜无害,但父级 #imgwrap 的高度本身依赖图片高度,形成循环依赖。max-height:100% 在这种布局下失效,图片被裁切而不是等比缩放——一旦图片被裁切,所有基于百分比的热区坐标自然全部错位。这正是用户担心的"缩放错位"的根因,而且它藏在浏览器的布局算法里,肉眼很难一眼看穿。

这也解释了为什么必须造一台"带尺子的标注器":不依赖 CSS 的隐式行为,而是用 JS 读取真实几何尺寸做显式换算。

四、造一把"尺子":标注器的五条精准化规则

基于上面的教训,做了一个独立的单文件工具 annotator.html(离线可用,30KB):左边加载课本页图,可视化画框、拖手柄微调、绑定音频;右边是标注列表和调试面板;导出/导入 JSON,坐标以原图归一化 0~1 存储,与显示缩放彻底解耦。

标注器工作台——课本图 + 拖拽画框 + 右侧标注列表 + 底部实时坐标日志
图4:标注器工作台——课本图、拖拽画框、右侧标注列表与底部实时坐标日志

规则① 坐标换算必须读取真实几何

这是整个工具的基石。换算时不信任任何 CSS 百分比或缓存值,而是同时读取 getBoundingClientRect() 和 img.offsetLeft / offsetTop / clientWidth / clientHeight:

function screenToOrig(sx, sy) {
  const r = img.getBoundingClientRect();
  // 图片内容的真实显示区域(去除 border/padding 影响)
  const dispX = r.left + img.clientLeft;
  const dispY = r.top + img.clientTop;
  const dispW = img.clientWidth;
  const dispH = img.clientHeight;
  // 屏幕坐标 → 归一化 0~1 → 原图像素
  const nx = (sx - dispX) / dispW;
  const ny = (sy - dispY) / dispH;
  return { x: nx * img.naturalWidth, y: ny * img.naturalHeight, nx, ny };
}

关键在于用 clientWidth/clientHeight 而不是 offsetWidth/offsetHeight——后者含边框,前者才是内容区,直接影响换算精度。

规则② 命中:中心点优先 + 可选容错半径

点击后的命中判定不是"第一个包住点的框",而是中心距离优先:先算点击点到每个矩形中心的归一化距离,取最近的一个;若开启了容错半径,则在该半径内再纳入"最近块"候选。这样即使点偏了几像素,也能命中正确的句子,而不是误中相邻框。

规则③ 调试面板

右侧面板实时显示:当前页的 naturalWidth/naturalHeight、offset、client 尺寸、最近一次换算的屏幕坐标 → offset/client → 归一化 → 原图坐标 → 命中结果的完整链路。底部控制台逐条打印点击日志。出现偏差时,一眼能看出是哪一步出的问题。

规则④ 容错半径可调

一个滑杆,0~400px 实时调节。容错太小点不中,太大容易误中——有了滑杆就能按实际手指点击精度现场调参,而不是拍脑袋写死。

规则⑤ 多页导航

支持上一页/下一页按钮 + 页码输入,示例清单一次加载 99 页图片、50 段音频。标注按页存储,切页不丢失。

五、踩坑实录

1. max-height:100% 的循环依赖。 前面说过,这是偏移的真凶。在标注器里彻底改用 JS 等比适配:读取舞台的真实宽高,按图片原始比例算出目标 width/height,直接写行内样式。图片任何时候都不会被裁切。

2. 坐标映射的"精度幻觉"。 一开始想在无头浏览器里靠解析 console 文本来验证坐标,结果发现文本输出不稳定,断言时好时坏。解法是加一个 window.__lastMap 调试钩子——每次点击把完整的换算结果写成结构化对象挂在全局,断言直接读对象,绕过文本解析。这是"可观测性"胜过"打印日志"的典型例子。

3. 容错半径的几何陷阱。 有一次断言失败,查下来是测试点击点距离目标 356px,而容错半径设的 300px——不是代码错了,是测试用例的几何没算对。把点击点挪到 0.66/0.45 归一化位置就过了。

这些坑有个共同点:不跑真实浏览器根本发现不了。

六、验证:真实浏览器里跑出来的 10/10

工具做完后,写了一套 CDP 驱动的验证脚本 verify_annotator_cdp.py,用真实 Chrome(带绝对 --user-data-dir 避免 Chrome 21 退出码)、真实鼠标拖拽和点击,跑了 10 条断言:

验证项结果
标题 / 示例加载(99 页)✅
图片 naturalWidth=820×1159✅
拖拽画框后标注数=1✅
框几何与拖拽区域一致(30±0.2%)✅
中心点命中 [center]✅
容错最近块命中 [tolerance]✅
坐标映射:屏幕(447,248)→原图(203,289)@820×1159,误差≤2px✅
调试模式显示标注框✅
零 JS 异常✅

10/10 全部通过。其中最关键的一条是坐标映射精度:屏幕坐标换算回原图坐标的误差控制在 2 像素以内——这就是"尺子"准不准的硬指标。

之前点读 App 的几轮迭代也都各有真实浏览器验证:布局 37/37、热修 10/10、一句一框 22/22、线上站点 16/16。所有这些数字都不是"我觉得对了",而是断言跑出来的。

七、结语

回头看,这件事的核心经验可以浓缩成三句话:

  1. 不要相信 CSS 的隐式行为来做精确计算。 缩放、裁切、百分比——这些浏览器"自作主张"的地方,恰恰是偏移的温床。要精度,就用 JS 读真实几何(clientWidth/clientHeight、naturalWidth),把换算规则显式写死。
  2. 坐标归一化是解耦的银弹。 标注存 0~1 的归一化值,显示层怎么缩放都不影响数据。原图像素 = 归一化值 × naturalWidth/Height,简单、稳定、可复现。
  3. 可观测性 + 真实浏览器验证 = 可信。 调试面板让每一步换算都可见,__lastMap 钩子让断言能读结构化数据,真实 Chrome + CDP 让验证不是纸上谈兵。三者合起来,才能把"看起来对了"变成"确实对了"。

工具本身是单文件 HTML,离线可用;标注 JSON 跨平台通用。如果你也在做图像标注、点读、热区命中这类需求,希望这把"尺子"能省下你几个抓狂的夜晚。


本文记录的技术方案均已在该项目中落地并通过真实浏览器验证。文中截图来自项目验证过程中的真实运行画面。

评论 / 0

发表评论

验证码