跳到主要内容

loading.js

特殊文件 loading.js 帮助你使用 React Suspense 创建有意义的加载 UI。通过此约定，你可以在路由段的内容流式传输时从服务器显示即时加载状态。一旦完成，新内容会自动交换进来。

加载 UI加载 UI
app/feed/loading.tsx
export default function Loading() {
  // 或者自定义加载骨架组件
  return <p>加载中...</p>
}

在 loading.js 文件内，你可以添加任何轻量级的加载 UI。你可能会发现使用 React Developer Tools 手动切换 Suspense 边界很有帮助。

默认情况下，此文件是一个服务端组件 - 但也可以通过 "use client" 指令用作客户端组件。

参考​

参数​

加载 UI 组件不接受任何参数。

行为​

导航​

  • 回退 UI 是预取的，使导航立即生效，除非预取尚未完成。
  • 导航是可中断的，这意味着更改路由不需要等待路由内容完全加载就可以导航到另一个路由。
  • 共享布局在新路由段加载时保持交互性。

即时加载状态​

即时加载状态是在导航时立即显示的回退 UI。你可以预渲染加载指示器，如骨架屏和旋转器，或未来屏幕的小但有意义的部分，如封面照片、标题等。这有助于用户理解应用程序正在响应并提供更好的用户体验。

通过在文件夹内添加 loading.js 文件来创建加载状态。

loading.js 特殊文件loading.js 特殊文件
app/dashboard/loading.tsx
export default function Loading() {
  // 你可以在 Loading 内添加任何 UI，包括骨架屏。
  return <LoadingSkeleton />
}

在同一文件夹中，loading.js 将嵌套在 layout.js 内。它将自动将 page.js 文件和下面的任何子项包装在 <Suspense> 边界中。

loading.js 概览loading.js 概览

SEO​

  • Next.js 将等待 generateMetadata 内的数据获取完成，然后再将 UI 流式传输到客户端。这保证了流式响应的第一部分包括 <head> 标签。
  • 由于流式传输是服务器渲染的，它不会影响 SEO。你可以使用 Google 的 Rich Results Test 工具来查看你的页面如何出现在 Google 的网络爬虫面前，并查看序列化的 HTML（来源）。

状态码​

流式传输时，将返回 200 状态码以表示请求成功。

服务器仍然可以在流式内容本身内向客户端传达错误或问题，例如，当使用 redirect 或 notFound 时。由于响应头已经发送到客户端，响应的状态码无法更新。这不影响 SEO。

浏览器限制​

某些浏览器会缓冲流式响应。在响应超过 1024 字节之前，你可能看不到流式响应。这通常只影响"hello world"应用程序，但不影响真实应用程序。

平台支持​

部署选项支持
Node.js 服务器是
Docker 容器是
静态导出否
适配器平台特定

了解如何配置流式传输当自托管 Next.js 时。

示例​

使用 Suspense 进行流式传输​

除了 loading.js，你还可以为你的 UI 组件手动创建 Suspense 边界。App 路由支持使用 Suspense 进行流式传输。

<Suspense> 通过包装执行异步操作的组件（例如获取数据）来工作，在操作进行时显示回退 UI（例如骨架屏、旋转器），然后在操作完成后交换你的组件。

app/dashboard/page.tsx
import { Suspense } from 'react'
import { PostFeed, Weather } from './Components'

export default function Posts() {
  return (
    <section>
      <Suspense fallback={<p>加载动态...</p>}>
        <PostFeed />
      </Suspense>
      <Suspense fallback={<p>加载天气...</p>}>
        <Weather />
      </Suspense>
    </section>
  )
}

通过使用 Suspense，你可以获得以下好处：

  1. 流式服务器渲染 - 从服务器到客户端逐步渲染 HTML。
  2. 选择性水合 - React 根据用户交互优先考虑首先使哪些组件具有交互性。

有关更多 Suspense 示例和用例，请参阅 React 文档。

版本历史​

版本变更
v13.0.0引入 loading。
最后于 更新