Building Persistent Page Transitions with WebGPU and Vanilla JavaScript使用 WebGPU 和原生 JavaScript 构建持久化页面过渡效果

Hi. I’m Ben Paine. I am a creative developer and designer based in San Diego, CA. I am going to demonstrate how to create unique page transitions using WebGPU. I have found that page transitions, when done right, exponentially improves the user experience.你好，我是 Ben Paine。我是一名居住在加利福尼亚州圣地亚哥的创意开发者和设计师。我将演示如何使用 WebGPU 创建独特的页面过渡效果。我发现，如果处理得当，页面过渡可以极大地提升用户体验。

The reason I utilize WebGPU (this works the same with WebGL, I have been using WebGPU as a modern alternative) is to essentially eliminate the perception of the browser ‘popping’ the DOM state. With one continuous scene, we can trick the user experience to seamlessly transition between pages.我使用 WebGPU（这与 WebGL 的工作原理相同，我一直将其作为一种现代替代方案）的原因，本质上是为了消除浏览器在切换 DOM 状态时产生的“跳动感”。通过一个连续的场景，我们可以欺骗用户的视觉，实现页面间的无缝过渡。

For the sake of the tutorial’s focus, I will very briefly be diving into the logic of the WebGPU renderer or the SPA scaffolding, but essentially I am binding the textures to a DOM element and using a basic image texture. All of this can be viewed within the source code.为了专注于本教程的核心，我将非常简略地介绍 WebGPU 渲染器或 SPA 脚手架的逻辑，但本质上，我将纹理绑定到 DOM 元素并使用基础图像纹理。所有这些都可以在源代码中查看。

1. Getting Started1. 入门

Here I will lay out a bit of the scaffold and a little bit about how the SPA works. It’s important to illustrate this because understanding a client router will help you understand how the transitions work, but I will be very high-level and brief.在这里，我将简要介绍一下脚手架以及 SPA 的工作原理。说明这一点很重要，因为理解客户端路由将有助于你理解过渡效果是如何工作的，但我会保持高度概括和简洁。

There are two layers stacked on top of each other. If you have worked with WebGL/GPU in the past this is familiar. There is a DOM layer with “slots” for the images and a Canvas layer with one single Scene that loads all of the image planes. The image planes persist throughout the whole site and are bound to the DOM slots. The image planes are created once at startup and persist. We are controlling the visibility based on the page and available slots.这里有两个层叠在一起。如果你过去使用过 WebGL/GPU，这应该很熟悉。一个是带有图像“插槽”的 DOM 层，另一个是加载所有图像平面的 Canvas 层。图像平面在整个站点中持续存在，并绑定到 DOM 插槽。图像平面在启动时创建一次并保持不变。我们根据页面和可用插槽来控制它们的可见性。

Each image plane carries a bounds = { x, y, w, h, z } expressed in CSS pixels using getBoundingClientRect(). At any moment the plane’s bounds are owned by exactly one of:每个图像平面都带有 bounds = { x, y, w, h, z }，使用 getBoundingClientRect() 以 CSS 像素表示。在任何时刻，平面的边界都由以下其中之一控制：

• DOM Tracking: The plane points to a DOM “slot” and is updated every frame.DOM 追踪：平面指向一个 DOM “插槽”，并每帧更新。
• Manual control: plane.trackedEL is null and the bounds are written directly. This happens during the transition when the DOM is broken down and destroyed and the transition relies on lerped values.手动控制：plane.trackedEL 为 null，边界直接写入。这发生在 DOM 被拆解和销毁的过渡期间，过渡依赖于插值（lerped）值。

With this in mind, the transition is essentially detaching all planes from DOM tracking -> tween their bounds/opacity/scale freely -> reattach to destination page’s DOM slots and continue DOM tracking.考虑到这一点，过渡本质上就是将所有平面从 DOM 追踪中分离 -> 自由补间（tween）它们的边界/不透明度/缩放 -> 重新附加到目标页面的 DOM 插槽并继续 DOM 追踪。

Let’s dive into some specifics.让我们深入了解一些细节。

a. Render Loopa. 渲染循环

Everything starts with a single entrypoint of src/index.js. The renderer is made and we have one single requestAnimationFrame loop. We build all the image textures for all the pages at startup, so we do not have any latency in loading each page’s textures when routing.一切都从 src/index.js 的单一入口点开始。渲染器被创建，我们有一个单一的 requestAnimationFrame 循环。我们在启动时构建所有页面的图像纹理，因此在路由时加载每个页面的纹理不会有任何延迟。

b. Pagesb. 页面

Each page is just a function that returns a string of HTML for brevity. Here is the “Selected” page:为了简洁起见，每个页面只是一个返回 HTML 字符串的函数。这是“Selected”页面：

// pages/home.js
export function home() {
  const slots = [0, 1, 2, 3, 4]
    .map(
      (i) =>
        `<a href="/<span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>i</mi><mo>+</mo><mn>1</mn></mrow><mi mathvariant="normal">"</mi><mi>d</mi><mi>a</mi><mi>t</mi><mi>a</mi><mo>−</mo><mi>l</mi><mi>i</mi><mi>n</mi><mi>k</mi><mi>c</mi><mi>l</mi><mi>a</mi><mi>s</mi><mi>s</mi><mo>=</mo><mi mathvariant="normal">"</mi><mi>s</mi><mi>l</mi><mi>o</mi><mi>t</mi><mi>s</mi><mi>l</mi><mi>o</mi><mi>t</mi><mo>−</mo></mrow><annotation encoding="application/x-tex">{i + 1}" data-link class="slot slot-</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.7778em;vertical-align:-0.0833em;"></span><span class="mord"><span class="mord mathnormal">i</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">+</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mord">1</span></span><span class="mord">"</span><span class="mord mathnormal">d</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal" style="margin-right:0.03148em;">ink</span><span class="mord mathnormal">c</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">a</span><span class="mord mathnormal">ss</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">=</span><span class="mspace" style="margin-right:0.2778em;"></span></span><span class="base"><span class="strut" style="height:0.7778em;vertical-align:-0.0833em;"></span><span class="mord">"</span><span class="mord mathnormal">s</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">o</span><span class="mord mathnormal">t</span><span class="mord mathnormal">s</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">o</span><span class="mord mathnormal">t</span><span class="mord">−</span></span></span></span>{i}"><figure></figure></a>`,
    )
    .join('');

  return `
    <section data-page="main" class="page page-main">
      <h1 class="page-title">Selected</h1>
      <div class="carousel">${slots}</div>
    </section>
  `;
}

A few things I want to point out:我想指出几点：

• The <figure> is empty. There is no <img> anywhere on the page. That empty box is a slot. It only exists to hold space in the layout so I can measure where the image should be. The actual picture is a WebGPU plane sitting on top, tracking that slot.<figure> 是空的。页面上没有任何 <img>。那个空盒子是一个插槽。它存在的唯一目的是在布局中占据空间，以便我可以测量图像应该在哪里。实际的图片是一个位于顶部的 WebGPU 平面，追踪着那个插槽。
• data-page tells the router what kind of page this is (main, inner, index). Every transition keys off that category, not off the URL.data-page 告诉路由器这是什么类型的页面（main、inner、index）。每个过渡都基于该类别，而不是 URL。
• data-link is the opt-in for the router. Any <a> carrying it gets intercepted instead of triggering a full page load.data-link 是路由器的选择加入机制。任何带有该属性的 <a> 标签都会被拦截，而不是触发全页加载。

The inner pages work the exact same way. A function that returns a stack of slots, one hero plus a few supporting images. Same idea, different layout.内部页面（inner pages）的工作方式完全相同。一个返回插槽堆栈的函数，包含一个主图和几个辅助图像。思路相同，布局不同。

The other half of a page is a function that measures those slots. When a transition needs to know where a plane should fly to, it reads the destination’s slots straight from the DOM:页面的另一半是一个测量这些插槽的函数。当过渡需要知道平面应该飞向哪里时，它直接从 DOM 读取目标的插槽：

// pages/home.js
export function getMainTargets(rootEl) {
  const slots = rootEl.querySelectorAll('.slot');
  return Array.from(slots, (s) => {
    const r = s.getBoundingClientRect();
    return { x: r.left, y: r.top, w: r.width, h: r.height };
  });
}

This is the whole trick to keeping everything in sync: I never hardcode coordinates. CSS lays out the slots, getBoundingClientRect() tells me where they landed, and the planes tween to those rects. Change the CSS and the transition still lands in the right place.这就是保持一切同步的全部诀窍：我从不硬编码坐标。CSS 布局插槽，getBoundingClientRect() 告诉我它们落在哪里，平面补间到这些矩形。更改 CSS，过渡效果依然会落在正确的位置。

c. The Routerc. 路由器

The router is one class called Controller and it does two jobs: it intercepts navigation, and it conducts the transition.路由器是一个名为 Controller 的类，它做两件事：拦截导航，并执行过渡。

Let’s do navigation first.我们先从导航开始。

It starts with a plain route table declaring the routes:它始于一个声明路由的普通路由表：

const ROUTES = {
  '/':      { page: 'main',  view: home,      image: null },
  '/index': { page: 'index', view: indexPage, image: null },
  '/1':     { page: 'inner', view: inner(0),  image: 0 },
  '/2':     { page: 'inner', view: inner(1),  image: 1 },
  // ...through /5
};

Each route is three things: a page category, the view function that returns the HTML, and the image index it foregrounds. Notice /1 through /5 all share page: 'inner' because the ‘inner’ page is a template. The transitions care about the category, not the exact URL.每个路由包含三件事：页面类别、返回 HTML 的视图函数以及它作为前景的图像索引。注意 /1 到 /5 都共享 page: 'inner'，因为“inner”页面是一个模板。过渡关注的是类别，而不是确切的 URL。

To catch clicks, I put a single listener on the document and filter for my links:为了捕获点击，我在 document 上放置了一个单一的监听器，并过滤我的链接：

onClick(e) {
  const a = e.target.closest('a[data-link]');
  if (!a) return;
  e.preventDefault();                    // stop the full page reload
  this.navigate(a.getAttribute('href'));
}

onPopState() {
  this.navigate(window.location.pathname, 'back');  // back/forward button
}

• One listener on document, not one per link. Pages I inject later are covered automatically so there is nothing to rebind.在 document 上设置一个监听器，而不是每个链接一个。我稍后注入的页面会自动被覆盖，因此无需重新绑定。
• preventDefault() is the line that turns a real link into an SPA navigation. The <a href> stays a real, shareable, right-clickable URL; I just hijack the left-click.preventDefault() 是将真实链接转换为 SPA 导航的那一行代码。 <a href> 仍然是一个真实的、可共享的、可右键点击的 URL；我只是劫持了左键点击。
• popstate handles the browser’s back and forward buttons. I pass a 'back' flag so navigate knows not to push another history entry.popstate 处理浏览器的后退和前进按钮。我传递一个 'back' 标志，以便 navigate 知道不要再推入一条历史记录。

That’s the routing half. navigate() itself runs the transition, so I’ll cover it in the next section because in this project, navigation and the transition are the same method.这就是路由部分。navigate() 本身运行过渡，所以我将在下一节中介绍它，因为在这个项目中，导航和过渡是同一个方法。

2. Page Transitions2. 页面过渡

This is the meat of the tutorial. Everything above was scaffolding so this section makes sense.这是本教程的核心。以上所有内容都是脚手架，以便本节内容能够成立。

Keep, remove, add保留、移除、添加

Going back to the mental model, the planes are never created or destroyed. So a transition is never “build the new images, tear down the old ones.” Every plane on screen is doing exactly one of three things:回到思维模型，平面永远不会被创建或销毁。因此，过渡永远不是“构建新图像，拆除旧图像”。屏幕上的每个平面都在做以下三件事之一：

• Keep: the image exists on both pages, so I morph it: tween its bounds from the old rect to the new rect. This is the seamless fly-and-scale.保留：图像在两个页面上都存在，所以我对其进行变形：将其边界从旧矩形补间到新矩形。这就是无缝的飞行和缩放效果。
• Remove: the image is leaving. I fade its opacity to 0. The plane stays alive; it just goes invisible and gets reused later.移除：图像正在离开。我将其不透明度淡出至 0。平面保持存活；它只是变得不可见，稍后会被重用。
• Add: the image is new to the destination. I stamp it at its target rect (set bounds instantly, no tween) and fade opacity from 0 to 1, so it materializes in place instead of flying in from nowhere.添加：图像对于目标页面是新的。我将其印在目标矩形上（立即设置边界，无补间），并将不透明度从 0 淡入到 1，这样它就会在原地显现，而不是从虚空中飞入。

// transitions/constants.js
export function tweenBounds(plane, target, opts = {}) {
  return gsap.to(plane.bounds, { x: target.x, y: target.y, w: target.w, h: target.h, /* ... */ });
}

export function tweenOpacity(plane, to, opts = {}) {
  return gsap.to(plane, { opacity: to, /* ... */ });
}

tweenBounds is “keep and move.” tweenOpacity is “remove or add.” Every transition in the project is built from just those two.tweenBounds 是“保留并移动”。tweenOpacity 是“移除或添加”。项目中的每个过渡都是仅由这两个动作构建的。

A transition consists of out() + in()过渡由 out() + in() 组成

Each transition is a small class with two async methods:每个过渡都是一个带有两个异步方法的小类：

class SomeTransition {
  async out(fromEl, toEl, ctx) { /* the planes that exist on the FROM page */ }
  async in(fromEl, toEl, ctx)  { /* the planes that are new to the TO page */ }
}

By convention out handles the planes leaving (morph the shared one, fade the rest out), and in handles the planes arriving (stamp them, fade them up). The controller fires both at once and waits for them together, so the two halves overlap and old and new are in motion at the same time. That overlap is what makes it read as one continuous move instead of “old leaves, then new arrives.”按照惯例，out 处理离开的平面（变形共享的平面，淡出其余的），in 处理到达的平面（盖章，淡入）。控制器同时触发两者并等待它们完成，因此两部分重叠，旧的和新的同时处于运动状态。这种重叠使得它看起来是一个连续的动作，而不是“旧的离开，然后新的到达”。

Here is the main → inner transition. You’re on Selected, you click image #2. Its hero should fly and grow into the inner page’s lead slot, the other four fade out, and #2’s supporting images appear below:这是 main → inner 的过渡。你在 Selected 页面，点击图像 #2。它的主图应该飞入并放大到内部页面的引导插槽，其他四个淡出，#2 的辅助图像出现在下方：

// transitions/mainToInner.js
export class MainToInnerTransition {
  async out(_from, toEl, ctx) {
    const { gpu, toImage } = ctx;
    const innerRects = getInnerTargets(toEl);   // measure the destination slots
    const target = innerRects[0];               // slot 0 = the hero position
    const tweens = [];
    for (let i = 0; i < MAIN_COUNT; i++) {
      const plane = gpu.planes[mainIdx(i)];
      if (i === toImage) {
        tweens.push(tweenBounds(plane, target));  // KEEP: fly the hero into place
      } else {
        tweens.push(tweenOpacity(plane, 0));      // REMOVE: fade the others out
      }
    }
    await Promise.all(tweens);
  }

  async in(_from, toEl, ctx) {
    const { gpu, toImage } = ctx;
    const innerRects = getInnerTargets(toEl);
    const fades = [];
    for (let j = 0; j < SATELLITES_PER_IMAGE; j++) {
      const sat = gpu.planes[satIdx(toImage, j)];
      sat.bounds = { ...innerRects[j + 1] };      // ADD: stamp at its target
      sat.opacity = 0;
      fades.push(tweenOpacity(sat, 1, { delay: 0.25 + j * 0.08 }));  // ...then fade in, staggered
    }
    await Promise.all(fades);
  }
}

Read it against the three roles: one plane is kept and morphed, four are removed, four are added. Nothing gets built, nothing gets destroyed.对照这三个角色来阅读：一个平面被保留并变形，四个被移除，四个被添加。没有东西被构建，没有东西被销毁。

The one trick that makes it work使其生效的一个诀窍

There is a catch, and it’s the most important detail in the whole thing.有一个陷阱，这是整个过程中最重要的细节。

Normally a plane tracks its slot on every frame, the render loop copies the slot’s getBoundingClientRect() into the plane’s bounds. That’s exactly what I want while you’re sitting on a page. But during a transition I’m trying to tween those same bounds myself. If the plane were still tracking a slot, the render loop would overwrite my tween 60 times a second and the morph would be invisible.通常，平面在每一帧都追踪其插槽，渲染循环将插槽的 getBoundingClientRect() 复制到平面的边界中。这正是我在页面停留时想要的。但在过渡期间，我试图自己补间这些边界。如果平面仍在追踪插槽，渲染循环会每秒 60 次覆盖我的补间，变形将不可见。

So the first thing the controller does on the way out is detach every plane from the DOM and unfreeze the bounds:因此，控制器在离开时做的第一件事就是将每个平面从 DOM 中分离并解冻边界：

_leavePage(state) {
  // ...stop the carousel, clear tilt, etc...
  for (const plane of this.gpu.planes) {
    plane.trackedEl = null;   // ★ hand the bounds over to the tweens
  }
}

With trackedEl cleared, nothing is fighting the tween and GSAP owns every plane’s bounds until the transition finishes. Once it’s done, I reattach the destination’s planes to their slots and tracking resumes. The seam is invisible because the tween already ended exactly on the new slot’s rect. I tweened to getInnerTargets(toEl), which is that rect.随着 trackedEl 被清除，没有任何东西会干扰补间，GSAP 在过渡完成前拥有每个平面的边界。一旦完成，我将目标的平面重新附加到它们的插槽，追踪恢复。接缝是不可见的，因为补间已经在新的插槽矩形处结束。我补间到了 getInnerTargets(toEl)，也就是那个矩形。

Putting it together: navigate()整合：navigate()

Now navigate() reads top to bottom (trimmed slightly for clarity):现在 navigate() 从上到下读取（为清晰起见略有删减）：

async navigate(path, target = null) {
  if (this.mutating) return;                  // 1. ignore clicks mid-transition
  if (path === this.current?.path) return;
  const next = this.routes[path];
  if (!next) return;

  const fromState = this.current;
  const toState = { path, ...next };
  const transition = this._resolveTransition(fromState.page, next.page);

  this.mutating = true;                        // 2. lock
  if (target !== 'back') history.pushState({ path }, '', path);  // 3. update the URL

  animateTitleOut(this.app.children[0]);       // 4. animate the old page's text out

  this._leavePage(fromState);                  // 5. detach ALL planes from the DOM

  this.app.insertAdjacentHTML('beforeend', next.view());  // 6. inject dest. both pages coexist now
  const fromEl = this.app.children[0];
  const toEl = this.app.lastElementChild;

  // 7. prepare the destination's layout engine (carousel / index) so its target rects exist
  // 8. animate the new page's text in

  const ctx = { gpu: this.gpu, fromImage: fromState.image, toImage: next.image, indexFloat: this.indexFloat };
  const txOut = transition.out(fromEl, toEl, ctx);   // 9. fire both halves at once
  const txIn  = transition.in(fromEl, toEl, ctx);

  await Promise.all([/* text tweens, */ txOut, txIn]);  // 10. wait for everything

  fromEl.remove();                             // 11. drop the old page
  this.current = toState;
  this._snapLayout(toState);                   // lock the exact final opacities
  this._enterPage(toState);                    // reattach tracking + start behaviors
  this.mutating = false;                       // 12. unlock
}

Plainly:简单来说：

lock → update history → detach all planes → inject the new page (both briefly on screen) → fire out() and in() together → await everything → remove the old page → reattach tracking → unlock.锁定 -> 更新历史记录 -> 分离所有平面 -> 注入新页面（两者短暂同时出现在屏幕上） -> 同时触发 out() 和 in() -> 等待一切完成 -> 移除旧页面 -> 重新附加追踪 -> 解锁。

A few decisions worth pointing at:几个值得指出的决定：

• The mutating lock makes the whole thing atomic. Mash the navigation links and the second click is ignored until the first transition lands. Otherwise two transitions would fight over the same shared planes.突变的锁使整个过程原子化。疯狂点击导航链接时，第二次点击会被忽略，直到第一次过渡结束。否则两个过渡会争夺同一个共享平面。
• Both pages coexist for the duration. The old page stays in the DOM (just un-clickable) so its text can animate out and the layout doesn’t collapse while the planes are still flying. It’s removed only after the await.两个页面在过渡期间共存。旧页面保留在 DOM 中（只是不可点击），因此其文本可以动画移出，并且在平面仍在飞行时布局不会崩溃。它仅在 await 之后被移除。
• The planes are detached the entire time. From step 5 to step 11 nothing is tracking the DOM, so the tweens own every bounds value uncontested. The instant the transition resolves, _enterPage reattaches and live tracking picks up right where the tween left off.平面在整个时间内都是分离的。从第 5 步到第 11 步，没有任何东西在追踪 DOM，因此补间不受干扰地拥有每个边界值。过渡解析的瞬间，_enterPage 重新附加，实时追踪从补间停止的地方继续。

5. Going Further5. 深入探索

That’s the core of it. A fixed pool of planes, a router that swaps the scaffolding, and transitions that keep/remove/add by tweening bounds and opacity. Once that clicks, everything else in the source is a variation on the same idea:这就是核心。一个固定的平面池，一个交换脚手架的路由器，以及通过补间边界和不透明度来保留/移除/添加的过渡。一旦理解了这一点，源代码中的其他一切都是同一想法的变体：

• The carousel on Selected doesn’t move planes at all. It moves the DOM slots and lets the planes track them, so the GPU side needs zero carousel-specific code.Selected 页面上的轮播图根本不移动平面。它移动 DOM 插槽并让平面追踪它们，因此 GPU 端不需要任何轮播图特定的代码。
• The index page drives bounds a different way: it projects the planes in 3D and writes the result straight into bounds, but the transition still just tweenBounds into those rects.索引页面以不同的方式驱动边界：它在 3D 中投影平面并将结果直接写入边界，但过渡仍然只是将边界补间到这些矩形中。
• The text (titles, facts, captions) animates in and out with GSAP SplitText alongside the planes, awaited together so everything lands at once.文本（标题、事实、说明）与平面一起使用 GSAP SplitText 进出动画，并一起等待，以便一切同时落地。

Add your own page category, write a view + a getTargets measurer, register a transition built from those same two verbs, and it drops right in. With a little tuning on the eases and timings, you can take this a long way.添加你自己的页面类别，编写一个视图 + 一个 getTargets 测量器，注册一个由这两个动词构建的过渡，它就能直接插入。通过对缓动和时序的一点调整，你可以走得很远。

You can dig through the full source for the carousel, the index projection, the custom cursor, and the shader that draws the rounded corners.你可以深入研究完整的源代码，了解轮播图、索引投影、自定义光标以及绘制圆角的着色器。

Please share what you think and follow me on Twitter and Instagram.请分享你的想法，并在 Twitter 和 Instagram 上关注我。