Community编程与开发github.com

深度滚动页面

构建一个深度滚动页面:一系列面板(绘图、单页卡片、阶段)作为深度轴上的站点,随着滚动前进,每个面板从远处浮现,在屏幕平面上清晰呈现,然后经过观看者,同时卡片流在它们之后向观看者飞来,灵感来自WhatTheFad(whatthefad.netlify.app)的着陆场。

深度滚动页面 是什么?

该技能用于构建一个“深度滚动”网页格式,读者可以逐个穿越一组图形面板。所有面板沿Z轴(深度)排列,而非传统页面的上下布局。它受WhatTheFad项目启发,该项目使用CSS 3D变换和requestAnimationFrame循环,在透视容器中创建无限飞行的卡片流。此格式增加了一个滚动控制相机,通过原生滚动(鼠标滚轮、触控板、触摸、按键)在站点间移动。每个站点在屏幕平面(z=0)上清晰呈现,经过观看者时淡出。站点可包含绘图、HTML内容或卡片行。最终输出为一个独立的HTML文件,无需外部脚本或WebGL。还包含一个捕获脚本(capture.mjs),用于通过DevTools协议进行实时无头浏览器截图和导航检查。该格式适合展示4到12个自包含的面板,每个面板占一屏,但不适合长篇文本或需要并排比较的内容。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/rafaelcarlosabbariao/skills/tree/HEAD/agnostic/depth-scroll

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

如果此文件夹中存在 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

  1. 内容优先。 将每个面板放在一个平面页面上,作为 <figure class="fig">,包含一个 .plate(绘图)和一个 figcaption。平面页面也是阅读副本。站点也可以携带原始 html。
  2. 编写一个规范(如下),作为 JSON 文件或作为项目自身构建脚本中的字典(当值被计算时,例如从数据文件读取的卡片名称)。
  3. 构建它。
    python3 -I $SK/build.py spec.json
    
    或者从脚本中:
    sys.path.insert(0, str(Path.home() / '.claude/skills/depth-scroll'))
    import build
    build.write(spec, base=HERE)
    
  4. 可选标题。 模板为固定标题预留了空间(--pin-h、header.pin、nav.pin-toc)。没有标题时,阶段从窗口顶部开始。
  5. 检查它 使用 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 中脚本的头部。

常量值作用
PERSP900必须与CSS中 .stations 和 .field 上的 perspective 匹配
GAP1400两个站点之间的世界深度
AHEAD2.2 × GAP站点被完全绘制出的前方距离
PASS300经过的站点淡出时的深度(缩放比例 1.5)
LIFT36等待的站点每GAP距离降低的像素数
DEPTH、NEAR2800、220流的生成深度和卡片飞过的深度
BASE46流静止时的速度,px/s
相机缓动9 / 秒相机追上滚动的速度

首次构建时出现的问题

以下每个问题都是通过观察发现的,并且已在模板中修复。

  • 标题的滚动边距。 固定标题为每个 [id] 设置了 scroll-margin-top,因此锚点落在标题下方。跳转总是比每个停止点短126px,直到停止点被设为零。
  • 轨道短了一个标题。 页面在最后一个停止点能到达顶部之前就结束了。轨道高度使用窗口高度,而非阶段高度。
  • 卡片飞到了内容列后面。 该列是固定且透明的,因此卡片透过其文字显示。当列固定时,阶段从其右侧开始。
  • 远处的卡片聚集在消失点。 WhatTheFad的遮罩解决了这个问题。
  • 经过的站点作为一个大模糊残留。 解决方法使用更短的 PASS 和二次淡出。
  • 等待的站点在矮站点下方显示。 它被绘制为暗淡(二次)。
  • 平面模式的内容指向隐藏的停止点。 停止点移到了站点上。
  • 在加载事件之前着陆的滚动遇到了短页面。 一旦文档被解析,轨道立即布局,并在字体和图像稳定后再次布局,因此恢复的滚动和 #st-<id> 链接都能正确着陆。
  • 在手机上宽绘图在其板块内横向平移,图像行被隐藏,站点变窄以便导轨保持右边缘。

待办事项

  • 捕获卡片。 在WhatTheFad中,捕获的片段会打开一个挖掘记录。这里卡片可以打开其记录,这需要目标页面在其URL中接受一个id,并进行上述的投影命中测试。
  • 暂停控制。 只要页面打开,流就会持续移动。减少动画会停止它,但没有暂停按钮,而WCAG 2.2.2要求持续超过五秒且与其他内容并存的运动有暂停功能。
  • 在真实触控板和手机上的感觉,以及帧率, 尚未经过人工评估。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能