如果此文件夹中存在 SKILL.local.md,请先阅读它;它包含你的路径、数据和内务规则。
深度滚动
一种页面格式,用于一组读者逐个穿过的图形。首次构建将一组解释性绘图转换成一个向观看者滚动的滚动页面,灵感来自WhatTheFad的着陆页(whatthefad.netlify.app,源代码位于github.com/rafaelcarlosabbariao/cultural-archaeology)。
该技能包含四个文件:
| 文件 | 说明 |
|---|---|
template.html | 页面:站点框架、流、导轨以及运行它们的脚本 |
build.py | 根据规范填充模板,可作为命令或模块使用 |
capture.mjs | 通过DevTools协议进行实时无头截图和导航检查 |
SKILL.md | 本文件 |
适用场景
- 适用于4到12个自包含面板,逐个阅读,每一屏一个:绘图、单页卡片、序列中的各个阶段。
- 不适用于长篇幅散文、表格,或任何需要读者并排比较或来回扫描的内容。这些情况请构建普通平面页面。
- 输出。 页面是一个自包含的
.html文件,无外部脚本且无WebGL。模板自带暖奶油色和墨色:root令牌配色方案;可根据喜好重新设置样式。
工作原理
WhatTheFad的场,源代码
阅读WhatTheFad的 index.html(#landing-trendfield CSS 和 renderTrendField 函数)。
- 投影。 场是一个容器,带有
perspective: 900px,每个片段使用translate3d(x, y, z)放置。浏览器在 scale 900 / (900 − z) 处绘制片段:在 z = −2800 处为 0.24,在屏幕平面处为 1,在 z = 220 处为 1.3。 - 时钟驱动运动。 一个
requestAnimationFrame循环以 150 px/s 的速度(乘以每个片段 0.75 到 1.25 的系数)将每个片段向观看者移动。超过 z = 220 后,它在 z = −2800 处的椭圆环上重新生成。 - 淡入淡出和绘制顺序。 片段在其深度的前四分之一处淡入,在 z = 60 到 220 之间淡出。场从不使用
preserve-3d,因此每个片段的z-index根据其深度设置,使较近的片段绘制在上层。 - 静默中心。 一个径向
mask-image隐藏中间部分,远处的片段在此汇聚于消失点。 - 捕获片段。 浏览器仅在指针移动时重新检查
:hover,因此静止光标下漂移的片段永远不会点亮。WhatTheFad 每帧测试指针相对于每个片段投影矩形的位置,捕获的片段将场速度减慢至 8%。
此格式新增内容
- 滚动即相机。
- 一个高轨道(
main.depth)容纳每个站点一个停止点,间隔一个阶段高度,带有scroll-snap-type: y proximity。 - 固定标题下方的粘性阶段容纳场景。
- 滚动位置变为站点索引,在每个停止点处为整数。相机以 9/秒的速率缓动到该位置,站点
i绘制在 z = (camera − i) × 1400 处。
- 一个高轨道(
- 站点的通过。
- 后方等待的站点变暗并略微偏低,因此向前移动时会上升到位。
- 静止时它位于 z = 0,缩放比例为 1,位于整数像素上,因此其文字与平面页面一样清晰。
- 经过观看者时,它在 z = 300 处、1.5 倍大小时淡出。
- 高于阶段的站点会按比例缩放以适应。
- 流。 WhatTheFad的场,包括遮罩。卡片的速度基础值为 46,加上相机速度的 0.9 倍,因此向前滚动会使卡片飞驰而过,向后滚动则使其远离。一个站点命名它绘制的卡片组(
lit),当该站点在前方时,这些卡片会亮起。 - 输入。
- 滚轮、触控板、触摸、方向键、导轨和标题内容都控制同一个原生滚动,因此所有输入都落在相同的停止点上。
- 焦点进入一个不在前方的站点会滚动到该站点。
- 流是装饰性的,只有静止的站点接收指针事件,因此无需每帧命中测试。
- 降级。 如果没有JavaScript,或者
prefers-reduced-motion: reduce,页面将站点平铺堆叠。深度由脚本添加的deep类启用。在平面模式下,内容锚点移动到站点上。
构建一个
SK 代表你安装此技能的路径,例如 ~/.claude/skills/depth-scroll
- 内容优先。 将每个面板放在一个平面页面上,作为
<figure class="fig">,包含一个.plate(绘图)和一个figcaption。平面页面也是阅读副本。站点也可以携带原始html。 - 编写一个规范(如下),作为 JSON 文件或作为项目自身构建脚本中的字典(当值被计算时,例如从数据文件读取的卡片名称)。
- 构建它。
或者从脚本中:python3 -I $SK/build.py spec.jsonsys.path.insert(0, str(Path.home() / '.claude/skills/depth-scroll')) import build build.write(spec, base=HERE) - 可选标题。 模板为固定标题预留了空间(
--pin-h、header.pin、nav.pin-toc)。没有标题时,阶段从窗口顶部开始。 - 检查它 使用
capture.mjs(如下),然后提交。
规范
路径相对于 base:规范文件所在的文件夹,或传递给 write 的文件夹。图像路径按原样写入页面,因此请相对于输出页面给出它们。
| 字段 | 内容 |
|---|---|
out | 要写入的页面 |
title | <title>,按类型命名(<主题> <类型名词>) |
source | 可选的平面页面。其 figure.fig 块变为 fig: n,其样式块(非标题的)被复制进来,以便绘图保留其类 |
kicker | 章节级站点上方的小标签;子站点的kicker是其章节名称 |
door | 第一个站点的HTML:引语、注释、指向平面页面的链接 |
stations[] | id;sec 和/或 sub(内容行;仅 sec 表示章节,仅 sub 表示子章节,两者同时存在则表示此站点开启一个章节);title(默认为 sub,然后是 sec);lead(HTML,一到两句);fig 或 html;cards([{img, label}],一个小图像行);lit(要点亮的流组) |
cards_label | 站点图像行末尾的标签 |
close | 最后一个站点的 {title, kicker, html},通常为来源 |
stream[] | 每个卡片为 {label, img, group}。40到80个可构成一个流 |
css | 可选的额外CSS,最后追加 |
检查
K=$SK/capture.mjs
node $K file:///path/page.html at-2.png 2 # 一个静止的站点
node $K file:///path/page.html transit.png 4.4 --wait=900 # 两个站点之间,捕捉关闭
node $K file:///path/page.html last.png 9 # 最后一个停止点可到达
node $K file:///path/page.html light.png 5 --light # 日光背景
node $K file:///path/page.html phone.png 3 375 700 # 手机宽度
node $K file:///path/page.html flat.png 0 --reduce # 减少动画的页面
node $K "file:///path/page.html#st-model" hash.png - # 加载时链接到一个停止点
node $K file:///path/page.html nav.png 0 --nav # 箭头、最后一个内容链接、导轨
每次运行都会打印停止点,以及每一步的 y、front(接收指针事件的站点)、rail、cardsShown、cardsLit、deep 和 pageWidth。静止的站点 front 等于其索引;pageWidth 必须读取视口宽度(无横向页面滚动)。在两种背景和手机宽度下查看每张图像,然后才能视为完成。对于图像位于文件夹外部的页面,首先将页面复制到暂存区并附上绝对图像路径。
不要使用 chrome --headless --screenshot 进行检查。在 --virtual-time-budget 下,动画帧几乎不推进,因此缓动相机永远不会到达,截取滚动窗口的截图可能返回空白。capture.mjs 驱动一个实时无头Chrome,其中帧以真实速率运行。
调优
常量位于 template.html 中脚本的头部。
| 常量 | 值 | 作用 |
|---|---|---|
PERSP | 900 | 必须与CSS中 .stations 和 .field 上的 perspective 匹配 |
GAP | 1400 | 两个站点之间的世界深度 |
AHEAD | 2.2 × GAP | 站点被完全绘制出的前方距离 |
PASS | 300 | 经过的站点淡出时的深度(缩放比例 1.5) |
LIFT | 36 | 等待的站点每GAP距离降低的像素数 |
DEPTH、NEAR | 2800、220 | 流的生成深度和卡片飞过的深度 |
BASE | 46 | 流静止时的速度,px/s |
| 相机缓动 | 9 / 秒 | 相机追上滚动的速度 |
首次构建时出现的问题
以下每个问题都是通过观察发现的,并且已在模板中修复。
- 标题的滚动边距。 固定标题为每个
[id]设置了scroll-margin-top,因此锚点落在标题下方。跳转总是比每个停止点短126px,直到停止点被设为零。 - 轨道短了一个标题。 页面在最后一个停止点能到达顶部之前就结束了。轨道高度使用窗口高度,而非阶段高度。
- 卡片飞到了内容列后面。 该列是固定且透明的,因此卡片透过其文字显示。当列固定时,阶段从其右侧开始。
- 远处的卡片聚集在消失点。 WhatTheFad的遮罩解决了这个问题。
- 经过的站点作为一个大模糊残留。 解决方法使用更短的
PASS和二次淡出。 - 等待的站点在矮站点下方显示。 它被绘制为暗淡(二次)。
- 平面模式的内容指向隐藏的停止点。 停止点移到了站点上。
- 在加载事件之前着陆的滚动遇到了短页面。 一旦文档被解析,轨道立即布局,并在字体和图像稳定后再次布局,因此恢复的滚动和
#st-<id>链接都能正确着陆。 - 在手机上宽绘图在其板块内横向平移,图像行被隐藏,站点变窄以便导轨保持右边缘。
待办事项
- 捕获卡片。 在WhatTheFad中,捕获的片段会打开一个挖掘记录。这里卡片可以打开其记录,这需要目标页面在其URL中接受一个id,并进行上述的投影命中测试。
- 暂停控制。 只要页面打开,流就会持续移动。减少动画会停止它,但没有暂停按钮,而WCAG 2.2.2要求持续超过五秒且与其他内容并存的运动有暂停功能。
- 在真实触控板和手机上的感觉,以及帧率, 尚未经过人工评估。