分步动画学习网页
给一段学习材料,生成一个独立的 HTML 文件(双击就能打开,不联网),让学习者一步一步看懂。 材料不限于代码:讲义或文章里的一段话、一个概念(复利、梯度下降、TCP 握手)、一个公式、一个流程、一份文件都可以——只要里面有「一步一步发生的变化」,就能拆成动画。 效果:小格子里的数字 → 飞到结果格子;橙框 = 正在读,蓝框 = 正在写;底下是当前代码行 + 一句大白话;自动播放,停留时间按说明文字长短算;← → 翻步,空格暂停。
本目录:
engine/engine.js、engine/engine.css:引擎(格子、框、飞行数字、指针、变量面板、表格、折线图、播放器、自检)。不要改引擎来适配某一节课,课程里的东西都写在课程文件里。build.mjs:把「课程文件 + 引擎」拼成一个独立 HTML。check.mjs:无界面打开网页的?check模式,每一步都跑一遍,打印问题。tools/snap.mjs:给指定的步骤截图,用来自己看一眼效果。template/lesson.js:课程文件骨架,从这里开始写。reference/api.md:引擎全部函数的说明(写课程前读一遍)。examples/:compound-interest.lesson.js(复利,输入只有一段文字、没有代码)、binary-search.lesson.js(二分查找,含图表)、bubble-sort.lesson.js(冒泡排序,含交换动画)、sliding-window.lesson.js(滑动窗口)。写新课程前至少看一个和材料类型接近的。
流程
0. 拿到材料
- 用户直接贴的文字、代码:直接用。
- 给的是文件:先完整读一遍。.md/.txt/.csv/代码文件直接读;.pdf/.docx/.pptx 用能读这些格式的工具或 skill 读出文字(扫描版 PDF 先 OCR)。材料很长时,先列出里面的知识点让用户挑要做哪几个,或者按章节一节一节做。
- 材料里有数据(表格、CSV、实验结果):把要用的数据直接写成 JS 数组常量放进课程文件。
- 先判断材料里什么在一步一步变化:代码是变量和数组;概念讲解里通常是数量(钱、温度、概率)、状态(排队的人、网络包)、或者一张表格。演示的就是这个东西怎么变。
1. 读材料,拆成「节 → 步」
- 节(上方标签)= 一个独立的小知识点:一个函数、一个循环、一张图怎么读。第 0 节通常讲「数据长什么样」(比如「图片就是一张数字表格」「列表就是一排格子」)。
- 步 = 一个动作:一次读取、一次计算、一次比较、一次写入。一步只讲一件事。
- 循环:一轮里有几行有新东西的代码,就拆成几步(比如「更新 s」「更新 best」是两步)。轮数多时,前 1~2 轮细拆,后面每轮合成一步;再多就「……一直重复……」直接跳到关键的一轮。
- 一节 3
15 步比较合适。整个网页 310 节。 - 最后一节可以是「读图 / 看结果」:嵌入真实数据画折线图,回答材料里的问题。
2. 先用 JS 把材料里的计算真的跑一遍
网页上出现的每一个数字都要是算出来的,不要手填。做法:在课程文件里用 JS 实现同样的算法,记下 trace(每一步的中间值),再按 trace 生成步骤(见 examples/binary-search.lesson.js 的 trace() 和 searchScene())。要嵌入真实数据(CSV、实验结果)时,把数据直接写成 JS 数组常量放进课程文件。
3. 选演示用的小数据
- 用很小的数据:图片用 3×4、4×4 的表格,数组 5~12 个数。真实规模写在说明里(「真实是 8 行 9 列,这里用 2 行 4 列演示,道理一样」)。
- 数字要挑得好算、能看出规律:比如 10、20、200 而不是 137、59。
- 舞台宽度大约 900px:一排格子 × 格子边长不要超过 ~850px(12 格 × 54px 正好)。
4. 写每一步的 c(代码)和 p(说明)
c:这一步对应的原文。材料是代码时,就是正在执行的那一行(或几行)代码,原样照抄;可以在后面用→或#写出这一步的结果,比如'img[0, 2] → 200'。 材料是文字、概念或文件时,写这一步对应的原文那句话(用「」括起来)、公式或规则,比如'「每年的利息会加进本金,下一年连利息一起生利息」'、'本金 × (1 + 10%)'(见examples/compound-interest.lesson.js)。- 代码是一个完整函数/循环时,给这一节写
code: '整段代码',然后每步的c写行号(从 1 数),比如c: [5, 7],网页会显示整段代码并高亮这几行。
- 代码是一个完整函数/循环时,给这一节写
p:一两句大白话,说清「这一步在干什么、得到了什么」。规则:- 不堆术语;必须出现的术语,后面马上用大白话解释一次。
- 学习者懂 Java / C:能类比就类比(「相当于 C 的
unsigned char img[3][4]」「append = Java 的list.add」「//是整除,和 Java 两个 int 相除一样」)。 - 写出具体的数和算式:「(10 + 10 + 10 + 10) ÷ 4 = 10」,比「求平均」好懂得多。
- 用
<b>…</b>标出这一步最关键的几个字(显示成橙色),<code>…</code>标代码。 - 说明里的数字用模板字符串从 trace 里取,不手写。
- 停留时间自动按
p的长度算(4 秒 + 每字 70ms)。动画本身很长(比如画一条 2.5 秒的折线)时加wait: 2500。
5. 写每一步的 run(S)
build()只搭舞台:创建格子、结果框、图表,stage.appendChild(...),返回一个对象S。run(S)只写这一步的变化(增量)。引擎翻到第 k 步时,会先重新build(),再瞬间重放第 0 ~ k−1 步,再带动画播放第 k 步——所以每一步不需要也不应该重画前面的结果。- 动画写法:
- 读哪些格子 →
frame('a', CO, 格子们)(橙框);写哪个格子 →frame('b', BL, 格子)(蓝框)。同名框会平滑移动过去。 - 数字移动 →
fly(从, 到, '文字', () => 到达后要 set 的值)。结果一定在then回调里 set,不要只在setTimeout里 set。 - 多个数先后飞 → 给
fly传delay,或用T(fn, 毫秒);不要直接用 setTimeout(瞬间重放时T会立即执行,setTimeout 不会)。 - 指针(lo / hi / i / j)→
mark('lo', 格子, 'lo', BL);同一格子上多个指针会自动错开,grid 要加below: 行数留位置。 - 图表:
chart({...})创建,C.line(xs, ys, 颜色)画线(会逐渐画出来),C.text(x, y, '标注')写字:会自动上下挪,躲开其他文字、圆点和已经画好的曲线,并拉回边界内。所以先画线、再写标注;标注写在线的后面一步也行。
- 读哪些格子 →
- 详细函数表见
reference/api.md。
6. 生成网页
node <本目录>/build.mjs 你的课程.lesson.js [输出.html]
课程文件放在用户的工作目录里(不要放进本 skill 目录),输出的 HTML 和它放在一起。
7. 自检(必须做,不能跳过)
自检会把每一节的每一步都跑两遍:瞬间模式查布局,带动画(8 倍速)查回调报错和「动画播完的画面和瞬间重放是否一致」。会报告:
报错:JS 异常(包括动画回调里的);标注重叠:文字标签、格子、指针、图表文字互相压住;标注压住圆点/标注压线:图表文字压在圆点、圆圈或曲线上;超出画布/超出图表:东西伸出舞台或 SVG,被裁掉看不见;框没对准:框或指针没有对准它要指的格子;文字撑出格子:数字太长,格子装不下;重放不一致:只在动画里 set、瞬间重放时没 set 的值(会导致按「上一步」时画面不对);缺内容:某一步没有c或p、某一节steps是空的,或者课程文件有语法错误(这时一节都读不到)。
怎么跑(任选一种):
- 有 Node 和 Chrome/Edge:
node <本目录>/check.mjs 输出.html(退出码 0 = 通过),再加--width 760跑一次窄屏。 如果它报「缺少 puppeteer-core」,在本 skill 目录运行一次npm install(这是唯一需要在 skill 目录里做的改动)。 - 有浏览器工具(如 Claude 的内置浏览器):打开
file:///…/输出.html?check,等页面顶部出现「✅ 自检通过」或「❌ 自检发现 N 个问题」;也可以执行 JS 读window.__CHECK__({ok, steps, problems})。 - 都没有:告诉用户用浏览器打开
输出.html?check看顶部报告。
有问题就改课程文件 → 重新 build → 重新 check,直到通过。然后再截几张图自己看一眼:
node <本目录>/tools/snap.mjs 输出.html 截图目录 0:1 1:5 3:2 [--width 760]
节:步 里,节 = 上方标签从左数第几个(最左边是 0,不管标签上写的是「0」还是「①」);步 = 网页右下角「第 k / n 步」的 k。比如「① 找 77」是第 2 个标签,它的第 5 步写 1:5。
自检查不出「数字算错」「说明和画面对不上」「看起来挤」这类问题,要靠截图看。
8. 交付
告诉用户 HTML 的路径、一共几节几步、自检结果。不要在网页里放真实的个人信息、公司名、内网地址或真实监控画面;演示数据用编出来的小数字。
常见坑
build()里不要调用fly/frame/mark:那时元素还没布局好。- 改格子、结果框、变量、表格的内容,一律用
G.set/valBox.set/vars.set/table.add,不要直接改textContent:引擎靠这些函数知道布局变了,好让框和指针跟着挪。 - 课程代码会被包在自己的作用域里运行,起什么变量名、函数名都不会和引擎冲突;
LESSON会被自动交给引擎。 - 每步的
run里的if (!INST)分支只能放纯装饰(比如额外的飞行效果),不能 set 任何最终状态。 - 一个格子里的文字很长(比如 16 位哈希)→ 用
valBox并设置{w: 宽度, fs: 字号},或者截短显示。 - 横轴最右边的刻度文字和轴名字会挤:引擎已经把轴名放在刻度下面居中。自己加的标注先交给
C.text自动避让;如果自检还报重叠/压线(比如曲线很密、没空地方),再手动换一个空白处的坐标。 - 二维数据:
grid([[...],[...]]);一维:grid([...])也可以,取格子用G.c(列)或G.c(行, 列)。