前言

前端开发一直有一个老大难的问题，那就是——瀑布流布局。

效果需求并不复杂：卡片错落，参差有致，看起来高级，滚动起来流畅。

就是这样一个看似简单的效果，其实已经困扰了前端开发者好多年。

要引入 JavaScript 库，要让内容智能填充，要实现响应式布局，写无数个媒体查询，要实现无限滚动加载，要用 JavaScript 处理复杂的布局逻辑……

现在，经过 Mozilla、苹果 WebKit 团队、CSS 工作组和所有浏览器的多轮讨论，它终于有了终极解决方案！

这就是 CSS Grid Lanes。

且让我们先翻译它为“CSS 网格车道”吧。

之所以叫车道，想象一下高速公路：有好几条车道，车辆会自动选择最短的那条车道排队。

CSS Grid Lanes 就是这个原理——你先定义好有几条“车道”（列），网页内容会自动填充到最短的那一列，就像车辆自动选择最不拥堵的车道一样。

具体使用起来也很简单，三行代码就能实现：

.container {
  display: grid-lanes;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
  gap: 16px;
}

实现原理

现在，让我们来细致讲解下如何实现开头图中的瀑布流效果。

首先是 HTML 代码：

<main class="container">
  <figure><img src="photo-1.jpg" /></figure>
  <figure><img src="photo-2.jpg" /></figure>
  <figure><img src="photo-3.jpg" /></figure>
  <!-- etc -->
</main>

然后是 CSS 代码：

.container {
  display: grid-lanes;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
  gap: 16px;
}

代码一共 3 行。

display: grid-lanes 创建网格容器，使用瀑布流布局。

grid-template-columns 创建车道，我们将值设为 repeat(auto-fill, minmax(250px, 1fr))，意思是至少 250 像素宽的灵活列。浏览器决定创建多少列，并填充所有可用空间。

gap: 16px表示车道之间有 16px 的间歇。

就是这么简单。

3 行 CSS 代码，无需任何媒体查询或容器查询，我们就创建了一个适用于所有屏幕尺寸的灵活布局。

---

更绝的是，这种布局能让用户通过 Tab 键在各个栏目之间切换，访问所有当前可见的内容（而不是像以前那样，先滚动到第一列底部，然后再返回第二列顶部）。

它也支持你实现无限循环加载，随着用户滚动页面，内容无限加载，而无需使用 JavaScript 来处理布局。

功能强大

不同车道尺寸

Grid Lanes 充分利用了 CSS Grid 的强大功能 grid-template-*来定义车道，所以很容易创建出富有创意的布局。

例如，我们可以创建一个布局，其中窄列和宽列交替出现——即使列数随视口大小而变化，第一列和最后一列也始终是窄列。

实现也很简单：

grid-template-columns: repeat(auto-fill, minmax(8rem, 1fr) minmax(16rem, 2fr)) minmax(8rem, 1fr);

效果如下：

跨车道

由于我们拥有网格布局的全部功能，我们当然也可以跨越车道。

效果如下：

实现代码：

main {
  display: grid-lanes;
  grid-template-columns: repeat(auto-fill, minmax(20ch, 1fr));
  gap: 2lh;
}
article {
  grid-column: span 1;
}
@media (1250px < width) {
  article:nth-child(1) {
    grid-column: span 4;
  }
  article:nth-child(2),
  article:nth-child(3),
  article:nth-child(4),
  article:nth-child(5),
  article:nth-child(6),
  article:nth-child(7),
  article:nth-child(8) {
    grid-column: span 2;
  }
}

放置项目

我们也可以在使用网格车道时显式地放置项目。这时，无论有多少列，标题始终位于最后一列。

实现代码为：

main {
  display: grid-lanes;
  grid-template-columns: repeat(auto-fill, minmax(24ch, 1fr));
}
header {
  grid-column: -3 / -1;
}

改变方向

网格车道也可以双向排列！

上面的所有示例创建的是“瀑布式”布局，内容以列的形式排列。

网格车道也可以用于创建另一种方向的布局，即“砖块式”布局。

当使用 grid-template-columns定义列时，浏览器会自动创建瀑布式布局，如下所示：

.container {
  display: grid-lanes;
  grid-template-columns: 1fr 1fr 1fr 1fr;
}

如果你想要反方向的砖块布局，使用 grid-template-rows：

.container {
  display: grid-lanes;
  grid-template-rows: 1fr 1fr 1fr;
}

容差

“容差”是为 Grid Lanes 创建的一个新概念。它允许你调整布局算法在决定放置项目位置时的精确度。

回到高速公路的比喻：

假设 1 号车道前面的车比 2 号车道长了 1 厘米，下一辆车要排到哪条车道？

如果严格按“哪条短选哪条”，它会选 2 号车道。但 1 厘米的差距根本不重要！这样来回切换车道反而让人困惑。

“容差”就是告诉系统：“差距小于这个值，就当作一样长”。

容差默认值是 1em（大约一个字的高度）。

为什么容差很重要呢？

因为用键盘 Tab 键浏览网页的人（比如视障用户）会按内容顺序跳转。

如果布局乱跳，他们会很迷惑。合适的容差能让浏览体验更流畅。

现在能用吗？

目前可以在 Safari 技术预览版 234 中体验，其他浏览器还在开发中。

苹果 WebKit 团队从 2022 年中就开始实现这个功能，现在基本语法已经稳定了。虽然还有些细节在讨论（比如属性命名），但核心用法不会变。

你可以访问 webkit.org/demos/grid3 看各种实际例子。

最后

欢迎围观我的“网页版朋友圈”，关注我的公众号：冴羽（或搜索 yayujs），每天分享前端知识、AI 干货。

1. 前言 快来看！JavaScript Rising Stars 公布了 2025 年 JavaScript 明星项目榜单。 此榜单根据 2025 年 GitHub 新增的星标数量，还建立了以下榜单

1. 前言

5 月的时候，React 的核心开发者 Dan 发表了一篇名为《Progressive JSON》 的文章，介绍了一种将 JSON 数据从服务器流式传输到客户端的技术，允许客户端在接收到全部数据之前就开始渲染部分数据。

这可以显著提升用户体验，尤其是处理大型数据集时。

让我们以“获取用户文章”这个场景为例。

这是一个完整的数据结构：

{
  "user": {
    "id": 1,
    "name": "John Doe",
    "posts": [
      { "id": 101, "title": "First Post", "content": "..." },
      { "id": 102, "title": "Second Post", "content": "..." }
    ]
  }
}

假设我们能够很快获取用户信息，但文章数据还需要一段时间从数据库获取。

与其等待数据完全加载完毕，不如先发送一个占位符表示文章字段：

{
  "user": {
    "id": 1,
    "name": "John Doe",
    "posts": "_$1"
  }
}

客户端收到数据后，先将用户信息渲染出来。

然后，当文章数据准备完毕后，我们将文章数据作为一个单独的 chunk 发送：

{
  "_$1": [
    { "id": 101, "title": "First Post", "content": "..." },
    { "id": 102, "title": "Second Post", "content": "..." }
  ]
}

客户端收到数据后，最后将文章数据渲染出来。

要实现这样一个功能，客户端需要具备处理这些占位符的能力，并在最终数据到达时替换为实际数据。

如果要实现这样一个单独的功能需要多少代码呢？

200 行就可以！

本篇文章和大家介绍下实现思路，供大家学习和思考使用。

2. 服务端实现

让我们来看下服务器端实现。

首先是服务端函数。

function serve(res, data) {
  res.setHeader("Content-Type", "application/x-ndjson; charset=utf-8");
  res.setHeader("Transfer-Encoding", "chunked");

  // 向客户端发送 chunks
  res.write(JSON.stringify(...) + "\n");
  res.write(JSON.stringify(...) + "\n");

  // 当完成的时候
  res.end();
}

这里有 2 点值得注意：

1. 我们使用了 application/x-ndjson内容类型。

NDJSON，全拼 Newline Delimited JSON，其实就是一种换行符分割的 JSON，其中每一行都是一个有效的 JSON 对象。这允许我们在单个响应中发送多个 JSON 对象，并以换行符分隔。

2. 我们使用了 Transfer-Encoding: chunked响应头。

使用该响应头，可以通知客户端，响应将分块发送。在调用 res.end()之前，请保持连接活跃状态。

其次，我们需要对数据进行分块。

实现方式也很简单，遍历数据对象，并用占位符替代那些暂时没有准备好的部分。

当遇到需要稍后发送的部分（一个 Promise）时，我们将其存储到队列中，并在准备就绪后，将其作为单独的数据块发送。

函数如下：

function normalize(value) {
  function walk(node) {
    if (isPromise(node)) {
      const id = getId();
      registerPromise(node, id);
      return id;
    }
    if (Array.isArray(node)) {
      return node.map((item) => walk(item));
    }
    if (node && typeof node === "object") {
      const out = {};
      for (const [key, val] of Object.entries(node)) {
        out[key] = walk(val);
      }
      return out;
    }
    return node;
  }
  return walk(value);
}

函数递归遍历数据对象。

当遇到 Promise 时，它会生成一个唯一的占位符 ID，注册该 Promise 以便稍后解析，并返回该占位符。

对于数组和对象，它会递归处理它们的元素或属性。原始值将按原样返回。

这是注册 Promise 的代码：

let promises = [];

function registerPromise(promise, id) {
  promises.push({ promise, id });
  promise.then((value) => {
    send(id, value);
  }).catch((err) => {
    console.error("Error resolving promise for path", err);
    send(id, { error: "promise error", timeoutMs: TIMEOUT });
  });

这是 send 的代码，send函数负责将解析后的数据发送给客户端：

function send(id, value) {
  res.write(JSON.stringify({ i: id, c: normalize(value) }) + "\n");
  promises = promises.filter((p) => p.id !== id);
  if (promises.length === 0) res.end();
}

该 send 函数会向响应中写入一个新的数据块，其中包括占位符 ID 和 normalize 后的值。然后它会从队列中移除已经 resolve 的 Promise。如果没有其他要处理的 Promise，它就会结束响应，从而关闭与客户端的连接。

完整的实现代码点击这里。

最后，我们举一个从服务端发送的对象示例：

const data = {
  user: {
    id: 1,
    name: "John Doe",
    posts: fetchPostsFromDatabase(), // 返回一个 promise
  },
};

async function fetchPostsFromDatabase() {
  const posts = await database.query("SELECT * FROM posts WHERE userId = 1");
  return posts.map((post) => ({
    id: post.id,
    title: post.title,
    content: post.content,
    comments: fetchCommentsForPost(post.id), // 返回一个 promise
  }));
}

每篇文章还有一个评论字段（comments），该字段是一个 Promise 对象。意味着评论数据将在文章数据发送后，作为单独的片段发送。

3. 客户端实现

那客户端该如何实现呢？

在客户端，我们处理传入的数据块，并将占位符替换为实际数据。

我们可以使用 Fetch API 向服务器发送请求，并将响应读取为流。每当遇到占位符时，我们都会将其替换为一个 Promise，该 Promise 将在实际数据到达时解析。

核心逻辑如下：

try {
    const res = await fetch(endpoint);
    const reader = res.body.getReader();
    const decoder = new TextDecoder();

    async function process() {
      let done = false;
      while (!done) {
        const { value, done: readerDone } = await reader.read();
        done = readerDone;
        if (value) {
          try {
            const chunk = JSON.parse(decoder.decode(value, { stream: true }));
            chunk.c = walk(chunk.c);
            if (promises.has(chunk.i)) {
              promises.get(chunk.i)(chunk.c);
              promises.delete(chunk.i);
            }
          } catch (e) {
            console.error(`Error parsing chunk.`, e);
          }
        }
      }
    }
    process();
  } catch (e) {
    console.error(e);
    throw new Error(`Failed to fetch data from Streamson endpoint ${endpoint}`);
  }
}

对流的处理，你可能感到陌生，可以拓展阅读我的这篇文章：《如何用 Next.js v14 实现一个 Streaming 接口？》

process 函数逐块读取响应流。每个数据块都被解析为 JSON，并调用 walk 函数将占位符替换为 Promise。

如果数据块包含先前注册的占位符 ID ，则相应的 Promise 会被解析为接收到的数据。关键在于 await reader.read()，它允许我们等待新数据到来。

walk函数用于将占位符替换为 Promise：

function walk(node) {
  if (isPromisePlaceholder(node)) {
    return new Promise((done) => {
      promises.set(node, done);
    });
  }
  if (Array.isArray(node)) {
    return node.map((item) => walk(item));
  }
  if (node && typeof node === "object") {
    const out = {};
    for (const [key, val] of Object.entries(node)) {
      out[key] = walk(val);
    }
    return out;
  }
  return node;
}
function isPromisePlaceholder(val) {
  return typeof val === "string" && val.match(/^_\$(\d)/);
}

类似于服务端的 normalize 函数。当遇到占位符的时候，它会返回一个新的 Promise，该 Promise 将在实际数据到达时解析。对于数组和对象，它会递归处理它们的元素或属性。原始值则直接返回。当然，ID 必须与服务器端生成的 ID 匹配。

完整的实现代码点击这里。两个文件加起来一共 155 行代码。

4. NPM 包

本篇文章整理翻译自 Streaming JSON in just 200 lines of JavaScript。

作者还将代码整理成了一个 NPM 包：Streamson。

通过 npm 安装：npm intall streamson

服务端上使用：

import { serve } from "streamson";
import express from "express";

const app = express();
const port = 5009;

app.get("/data", async (req, res) => {
  const myData = {
    title: "My Blog",
    description: "A simple blog example using Streamson",
    posts: getBlogPosts(), // this returns a Promise
  };
  serve(res, myData);
});

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

客户端是一个 1KB 的 JavaScript 文件，地址：unpkg.com/streamson@l…

客户端使用如下：

const request = Streamson("/data");

const data = await request.get();
console.log(data.title); // "My Blog"

const posts = await request.get("posts");
console.log(posts); // Array of blog posts

5. 最后

作为准前端开发专家的你，第一时间获取前端资讯、技术干货、AI 课程，那不得关注下我的公众号「冴羽」。

流式传输 JSON 数据是一种提升 Web 应用感知性能的有效方法，尤其适用于处理大型数据集或动态生成数据。

通过在数据可用时立即发送部分数据，我们可以让客户端更早地开始渲染内容，从而带来更佳的用户体验。