horizontal-scroll-scenes
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseHorizontal Scroll Scenes
横向滚动场景
The mechanism: scroll position is the only state. One pure function turns into every frame, and everything on screen (camera, wipe line, craft clock, text, index) is written from that triple. Nothing remembers where you were, so every beat is a place on the page.
scrollY / (scrollHeight - innerHeight){scene, dwell 0→1, move 0→1}This is what Kibori does, and it is not a slider. Verified by running it: the page is a native-scroll track (15,678 px at 1440×900); a fixed stage holds one WebGL world whose camera travels 0 → 49.7 world units left to right through eight stations; between stations a ragged burn line wipes from a frozen frame of the scene being left to the live scene already framed on the next. There is no wheel handler, no snap, no stored "current chapter". Reload at depth, scrollbar drag and anchor jumps work because state is derived, not accumulated.
translateX1742vhReach for or for the story and 3D-world side, for pinned sticky sections, for a progress line. Reach for this when the deliverable is discrete chapters with a resting beat each, laid along an X axis, and the hard part is making that state machine survive reverse, skip and refresh. The demo is Vanilla JavaScript + DOM/CSS + inline SVG; the source is three.js. The state machine is identical.
scroll-world-storytellingbuild-threejs-scroll-worldsgsap-scrolltrigger-storytellingscroll-progress-timeline机制: 滚动位置是唯一状态。一个纯函数每帧将 转换为 ,屏幕上的所有内容(摄像机、擦除线、工艺进度时钟、文字、索引)都由这组三元值驱动。系统不会记住你之前的位置,因此每个节拍都直接对应页面上的一个位置。
scrollY / (scrollHeight - innerHeight){scene, dwell 0→1, move 0→1}这就是 Kibori 的实现方式,而且它并不是一个 滑块。实际运行验证如下:页面采用 的原生滚动轨道(在 1440×900 下为 15,678 px);固定舞台承载一个 WebGL 世界,其摄像机从左向右穿过八个站点,移动距离为 0 → 49.7 个世界单位;站点之间,一条参差不齐的燃烧擦除线从正在离开的场景冻结帧,擦除到已完成取景的下一场景实时帧。这里没有滚轮事件处理器、没有 scroll snap,也没有存储的“当前章节”。之所以在页面深处刷新、拖动滚动条和锚点跳转时都能正常工作,是因为状态由滚动位置推导,而不是累积得到。
translateX1742vh若要处理故事线和 3D 世界部分,可使用 或 ;若需要 fixed sticky 区块,可使用 ;若需要进度线,可使用 。当交付物是沿 X 轴排列、每个章节都有一个停留节拍的离散章节,且难点在于让状态机经受住反向滚动、跳过和刷新时,应采用本方案。Demo 使用 Vanilla JavaScript + DOM/CSS + inline SVG;源码基于 three.js。状态机完全相同。
scroll-world-storytellingbuild-threejs-scroll-worldsgsap-scrolltrigger-storytellingscroll-progress-timelineThe pace: two weights and a track height
节奏:两个时长权重和轨道高度
Every number lives in , and the track height. One unit is one screen of scrolling.
DWELLMOVE| constant | value | meaning |
|---|---|---|
| 1.15 | scroll spent inside a scene while its craft advances (about 1,030 px at 900 tall) |
| 0.85 | scroll spent crossing to the next scene (about 760 px); the last scene has none |
| 2.00 | one scene per two screens |
| | 8 scenes: 15.15 plus a 1.35 footer = 16.5; demo, 5 scenes: 9.15 |
| track | | so 1 unit ≈ 1 screen; Kibori is 1742vh for 16.5 |
js
function travel(sp){ // sp = scrollY / (scrollHeight - innerHeight)
const u = Math.min(SPAN - 1e-5, sp*SPAN);
const i = Math.min(N - 1, Math.floor(u/CYC));
const local = u - i*CYC;
const dw = Math.min(1, local/DWELL); // the scene's own clock
const f = i >= N-1 ? 0 : clamp01((local - DWELL)/MOVE); // the move
const rc = clamp01((f - 0.01)/0.97); // the line's own clock
return {i, u, dw, f, fe: sstep(0,1,f), L: -0.08 + 1.24*rc, // L: line, off-frame at both ends
live: Math.min(N-1, f < 0.39 ? i : i+1)}; // what the index shows
}Normalise by , never a hard-coded pixel height: a phone's collapsing URL bar changes mid-scroll and a px map drifts.
scrollHeight - innerHeightinnerHeight所有数值都集中在 、 和轨道高度中。一个单位相当于一屏的滚动量。
DWELLMOVE| 常量 | 数值 | 含义 |
|---|---|---|
| 1.15 | 在场景内部用于推进其工艺进度的滚动量(高度为 900 时约为 1,030 px) |
| 0.85 | 移动到下一场景所需的滚动量(约 760 px);最后一个场景没有此段 |
| 2.00 | 每个场景占两屏 |
| | 8 个场景:15.15,加 1.35 的页脚 = 16.5;Demo 中 5 个场景:9.15 |
| track | | 使 1 单位 ≈ 1 屏;SPAN 为 16.5 时,Kibori 为 1742vh |
js
function travel(sp){ // sp = scrollY / (scrollHeight - innerHeight)
const u = Math.min(SPAN - 1e-5, sp*SPAN);
const i = Math.min(N - 1, Math.floor(u/CYC));
const local = u - i*CYC;
const dw = Math.min(1, local/DWELL); // the scene's own clock
const f = i >= N-1 ? 0 : clamp01((local - DWELL)/MOVE); // the move
const rc = clamp01((f - 0.01)/0.97); // the line's own clock
return {i, u, dw, f, fe: sstep(0,1,f), L: -0.08 + 1.24*rc, // L: line, off-frame at both ends
live: Math.min(N-1, f < 0.39 ? i : i+1)}; // what the index shows
}始终通过 归一化,绝不要使用硬编码的像素高度:手机在滚动过程中收起或展开 URL 栏会改变 ,固定的 px 映射会产生漂移。
scrollHeight - innerHeightinnerHeightRules, each with the failure it prevents
规则:每条规则都对应一个它所防止的故障
- Derive, do not accumulate. Never keep or add wheel deltas. Stored state desyncs on scrollbar drag,
currentScene/Home, anchor jumps, back-forward and refresh. Prove it: record a signature of every visible style at 20Endvalues going forward, then again in reverse, then by jumping straight to each, then afteruat three depths. All must be equal (the demo run: 0 mismatches of 21, 0 skip, 0 reload).reload() - No wheel hijack, no . Hijacking breaks touch, trackpad momentum,
scroll-snap/Spaceand find-in-page. Snap fights the dwell, which is already the resting plateau (1.15 screens where nothing moves but the craft). Native scrolling stays 1:1: 2,000 px of wheel gave exactlyPageDown.u = 2000/(scrollHeight - vh)*SPAN - Pin the craft clock outside its dwell. Scene 's progress is
kif1,k < iifdw,k == iafter. Then nothing snaps back behind you and reverse retraces exactly. Write it as0and eased--p{k}custom properties on the stage; both world copies read them, so it is one write per frame.--e{k} - A move with nothing moving is dead scroll. Start the line at the frame's edge almost at once (); starting it further off made the first eighth of every move do nothing.
rc = (f-0.01)/0.97 - The wipe hides the camera. Freeze the outgoing frame ahead of the line and have the live world already standing on the destination behind it. A camera still travelling under the line reads as a double exposure. Demo: layer A at camera clipped to the far side of the line, layer B at
iclipped to the near side. Pan mode (i+1) is the alternative when no wipe is wanted.translateX(-(i+fe)/N*100%) - The line writes the next chapter in. Alternate sweep direction from the side the incoming words sit on. Mask outgoing text and incoming
linear-gradient(a, transparent (L-.01)%, #000 (L+.016)%), with#000 (L-.062)%, transparent (L-.048)%ora = 90deg. Two chapters never share a patch of frame. On a phone both sit in one slot: hide the incoming until the line has cleared,270deg.sstep(1.00, 1.14, L) - The index flips at , not 0.5. At the midpoint the incoming title is already half written; flipping late labels the wrong scene. Fade the inactive rows to
f < 0.39, not0.55.0 - Chapter clocks overlap on purpose. Arrival starts before the scene's home and finishes
MOVE*0.80into it; departure starts atDWELL*0.62and takesDWELL + MOVE*0.28. Each part (eyebrow, title, lede, numbers) takes its own slice ofMOVE*0.34(0, .12, .40, .60 plus a 0.30 ramp).arrive - Fast-skip plays only the last move. More than one scene away: roll smoke in over 380 ms, the station before the target (
scrollTogoing forward,(tgt-1)*CYC + DWELL*0.96going back), then play the final move for 2,600 ms with(tgt+1)*CYC + 0.02as the veil lifts over the first 24%. Hide the scene it passes through, or its words flash. Land at1-(1-x)^2.4so the target is assembled. One scene away or fewer: plain leg oftgt*CYC + DWELL*0.80ms with cubic in-out. Without this a jump from 1 to 8 strobes six fires.clamp(700 + |dy|/vh*150, 900, 2400) - Any wheel, touch or nav key cancels the glide. Otherwise the page fights the hand.
- breaks both the glide and every capture. Per-frame
html{scroll-behavior:smooth}chases itself; playwright screenshots land mid-scroll and look like overlap bugs. SetscrollTo.auto - Hidden chapters are plus
visibility:hidden. Opacity 0 alone leaves invisible links focusable and readable to screen readers.inert - Render on ,
scroll,resize,pageshowandload. Reload restores scroll after first paint; a bfcache restore fires no scroll event. Guard a zero-size stage and size from afonts.ready.ResizeObserver - Duplicate worlds need unique SVG ids. Two copies sharing a id resolve
clipPathto the first one only.url(#id) - Announce committed changes only. A polite live region says "Scene 4 of 5: Yakisugi" once when a glide lands, not on every threshold crossed on the way.
- 进行推导,不要累积。 绝不保存 ,也不要累加滚轮增量。存储状态会在拖动滚动条、按
currentScene/Home、锚点跳转、浏览器前进/后退和刷新时失步。验证方法:分别在正向滚动的 20 个End值、反向滚动的 20 个值、直接跳转到各值,以及在三个深度执行u后,记录每个可见样式的签名。所有结果必须一致(Demo 实测:21 项中 0 处不匹配、0 次跳过、0 次刷新问题)。reload() - 不要劫持滚轮,不要使用 。 劫持滚轮会破坏触摸滚动、触控板惯性、
scroll-snap/Space和页内查找功能。Snap 会与停留段争夺控制权,因为停留段本身已经是静止平台(持续 1.15 屏,只有工艺进度在推进)。原生滚动保持 1:1:滚轮滚动 2,000 px 后,得到的值恰好为PageDown。u = 2000/(scrollHeight - vh)*SPAN - 将工艺时钟钳制在其停留段之外。 场景 的进度在
k时为k < i,在1时为k == i,之后为dw。这样,已经离开的场景不会在你身后回弹,反向滚动也能精确复现路径。在舞台上将其写为0和缓动后的--p{k}自定义属性;两个世界副本都读取这些属性,因此每帧只需写入一次。--e{k} - 如果移动过程中没有任何东西在动,这段滚动就是无效滚动。 擦除线几乎立即从画面边缘开始();若起点更靠画外,每次移动的前八分之一都不会产生变化。
rc = (f-0.01)/0.97 - 擦除效果应该遮住摄像机运动。 让离场帧在擦除线扫过之前保持冻结,同时让实时世界已经位于其后方的目标场景。摄像机若仍在擦除线下方移动,视觉上就会像双重曝光。Demo 中,图层 A 的摄像机位于 ,并裁剪到擦除线的远侧;图层 B 位于
i,并裁剪到近侧。如果不需要擦除效果,可改用平移模式(i+1)。translateX(-(i+fe)/N*100%) - 让擦除线逐步写入下一章节。 根据入场文字所在的一侧交替改变扫动方向。使用 遮罩离场文字,使用
linear-gradient(a, transparent (L-.01)%, #000 (L+.016)%)遮罩入场文字,其中#000 (L-.062)%, transparent (L-.048)%为a或90deg。两个章节绝不会同时占据画面的同一区域。在手机上,两者共用同一个槽位:在线条扫过之前隐藏入场章节,使用270deg。sstep(1.00, 1.14, L) - 索引应在 时切换,而不是 0.5。 到达中点时,入场标题已经写入一半;切换过晚会标记错误的场景。非活动行淡出至
f < 0.39,而不是0.55。0 - 章节时钟有意重叠。 入场动画在场景主位置之前 处开始,并在进入场景
MOVE*0.80的位置结束;离场动画从DWELL*0.62处开始,持续DWELL + MOVE*0.28。每个组成部分(眉题、标题、导语、数字信息)分别占用MOVE*0.34的一个区段(0、.12、.40、.60,另加 0.30 的渐变段)。arrive - 快速跳过时只播放最后一次移动。 目标相距超过一个场景:让烟雾在 380 ms 内滚入,使用 跳到目标前的站点(向前为
scrollTo,向后为(tgt-1)*CYC + DWELL*0.96),然后在烟幕于前 24% 逐渐揭开时,以(tgt+1)*CYC + 0.02播放 2,600 ms 的最后一次移动。隐藏途经的场景,否则其文字会闪现。最终落在1-(1-x)^2.4,确保目标场景已经组装完成。若只相差一个场景或更近,则直接执行一段普通移动,时长为tgt*CYC + DWELL*0.80ms,并使用 cubic in-out 缓动。否则,从场景 1 跳到场景 8 会产生六次火光频闪。clamp(700 + |dy|/vh*150, 900, 2400) - 任何滚轮、触摸或导航键操作都要取消平滑跳转。 否则页面会与用户操作相互争夺控制权。
- 会破坏平滑跳转和所有截图。 逐帧调用
html{scroll-behavior:smooth}会不断追赶其自身目标;scrollTo截图可能落在滚动中途,看起来像图层重叠故障。应将其设为playwright。auto - 隐藏的章节应同时使用 和
visibility:hidden。 仅将 opacity 设为 0,会让不可见的链接仍可获得焦点,并被屏幕阅读器读取。inert - 在 、
scroll、resize、pageshow和load时渲染。 刷新后浏览器会在首次绘制后恢复滚动位置;从 bfcache 恢复时不会触发 scroll 事件。要处理舞台尺寸为 0 的情况,并通过fonts.ready跟踪尺寸。ResizeObserver - 重复的世界需要使用唯一的 SVG 。 两个副本共用一个
idclipPath时,id只会解析到第一个副本。url(#id) - 仅播报已经确认的变化。 平滑跳转落定后,polite live region 只播报一次“场景 4 / 5:Yakisugi”,而不是在途中每次越过阈值时都播报。
Accessibility and lifecycle
无障碍与生命周期
- Index rows are real links with and a visible 1 px outline at 5 px offset; brand link returns to scene 1. The stage is
aria-current="step"above a plain-height track soposition:fixed, arrows,Space,PageDownandHomescroll natively.End - : no line, no travel. Scene B cross-fades over
prefers-reduced-motion: reduce0.30 → 0.70, the incoming chapter waits untilf, glides are an instantf = 0.64, and the craft still advances with scroll (that is the user's own input). Controls stay live.scrollTo - : settle any glide at its target so a resumed tab does not integrate the pause.
document.hidden - Mobile: keep the index to the current row (), stack the chapter at the foot and the work above it.
03 / 05 Kigumi
- 索引行是真实链接,带有 ,并显示偏移 5 px 的 1 px 轮廓;品牌链接返回场景 1。舞台采用
aria-current="step",下方是仅负责撑高度的普通轨道,因此position:fixed、方向键、Space、PageDown和Home都能原生滚动。End - :不显示擦除线,不进行横向移动。场景 B 在
prefers-reduced-motion: reduce0.30 → 0.70 期间交叉淡化,入场章节等待到f,平滑跳转改为瞬时f = 0.64,但工艺进度仍随滚动推进,因为这是用户自己的输入。控件保持可交互。scrollTo - :让任何平滑跳转立即落定到目标,避免恢复标签页后继续处理暂停期间的时间。
document.hidden - 移动端:索引仅保留当前行(),将章节堆叠在底部,并把作品放在上方。
03 / 05 Kigumi
Cost, measured
成本(实测)
The state machine is free: sits at the 0.1 ms timer floor (p50 0, p90 0.1) over a 400-step sweep, and 8.3 ms p50 (120 Hz cap) with 9.2 ms max during a 2.6 s glide in the demo. The cost is whatever the scenes draw. In Kibori a dwell frame was slower than a transition until a 4096² shadow map stopped redrawing every frame, and a scissored live scene did the rest; see the notes. Never spend effort optimising .
render()kibori-60fpstravel()状态机本身几乎没有成本:在 400 步扫动中, 受 0.1 ms 定时器粒度限制(p50 为 0,p90 为 0.1);在 Demo 的 2.6 秒平滑跳转期间,p50 为 8.3 ms(120 Hz 上限),最大值为 9.2 ms。实际开销取决于场景所绘制的内容。在 Kibori 中,停留帧一度比过渡帧更慢,直到 4096² 的 shadow map 不再逐帧重绘,再由使用 scissor 裁剪的实时场景完成其余部分;参见 笔记。永远不要浪费时间优化 。
render()kibori-60fpstravel()Failure signatures
故障特征
| you see | cause |
|---|---|
| reload lands on scene 1 | state kept in JS; derive from |
| scene "sticks" between two beats | snap or wheel capture; delete it |
| two rooms overlap under the line | camera still travelling under the wipe |
| index shows the old scene as the title lands | flip threshold at 0.5 instead of 0.39 |
| jump link strobes several scenes | glide plays every move instead of the last |
| jump link overshoots or stutters | |
| second scene's clip does nothing | duplicated SVG |
| screen reader reads chapters that are not on screen | opacity 0 without |
| phone shows two titles spliced at the line | incoming chapter not held back until the line clears |
| 你看到的现象 | 原因 |
|---|---|
| 刷新后落在场景 1 | 状态保存在 JS 中;应从 |
| 场景在两个节拍之间“卡住” | 使用了 snap 或滚轮捕获;删除它 |
| 擦除线下方两个房间重叠 | 摄像机仍在擦除区域下移动 |
| 标题落定时索引仍显示旧场景 | 切换阈值误设为 0.5,而不是 0.39 |
| 跳转链接使多个场景闪现 | 平滑跳转播放了每次移动,而不是只播放最后一次 |
| 跳转链接越过目标或发生卡顿 | |
| 第二个场景的裁剪无效 | 重复的 SVG |
| 屏幕阅读器读出未显示的章节 | 仅将 opacity 设为 0,未使用 |
| 手机在擦除线处拼接显示两个标题 | 入场章节未在线条扫过之前保持隐藏 |
Provenance
来源
Extracted from KIBORI 木彫, an eight-craft Kyoto woodshop page in one three.js file (, and the glide block near the end of its module script). Demo staged in that page's dark-and-ember look with five hand-drawn SVG crafts.
kibori.htmltravel()提取自 KIBORI 木彫,这是一个京都木工工坊主题页面,包含八种工艺,全部集中在一个 three.js 文件中(、,以及模块脚本末尾附近的平滑跳转代码块)。Demo 沿用该页面的暗黑与余烬风格,并包含五个手绘 SVG 工艺图形。
kibori.htmltravel()