Next.js 中文网

主题

loading.js ​

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

¥The special file loading.js helps you create meaningful Loading UI with React Suspense. With this convention, you can show an instant loading state from the server while the content of a route segment streams in. The new content is automatically swapped in once complete.

tsx
export default function Loading() {
  // Or a custom loading skeleton component
  return <p>Loading...</p>
}

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

¥Inside the loading.js file, you can add any light-weight loading UI. You may find it helpful to use the React Developer Tools to manually toggle Suspense boundaries.

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

¥By default, this file is a Server Component - but can also be used as a Client Component through the "use client" directive.

参考 ​

¥Reference

参数 ​

¥Parameters

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

¥Loading UI components do not accept any parameters.

行为 ​

¥Behavior

¥Navigation

  • Fallback UI 为 prefetched，除非预加载尚未完成，否则导航将立即生效。

    ¥The Fallback UI is prefetched, making navigation is immediate unless prefetching hasn't completed.

  • 导航是可中断的，这意味着更改路由不需要等待路由内容完全加载后再导航到另一条路由。

    ¥Navigation is interruptible, meaning changing routes does not need to wait for the content of the route to fully load before navigating to another route.

  • 加载新路由段时，共享布局保持交互状态。

    ¥Shared layouts remain interactive while new route segments load.

即时加载状态 ​

¥Instant Loading States

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

¥An instant loading state is fallback UI that is shown immediately upon navigation. You can pre-render loading indicators such as skeletons and spinners, or a small but meaningful part of future screens such as a cover photo, title, etc. This helps users understand the app is responding and provides a better user experience.

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

¥Create a loading state by adding a loading.js file inside a folder.

tsx
export default function Loading() {
  // You can add any UI inside Loading, including a Skeleton.
  return <LoadingSkeleton />
}

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

¥In the same folder, loading.js will be nested inside layout.js. It will automatically wrap the page.js file and any children below in a <Suspense> boundary.

SEO ​

  • Next.js 将等待 generateMetadata 内的数据获取完成，然后再将 UI 流式传输到客户端。这保证了流式响应的第一部分包含 <head> 标签。

    ¥Next.js will wait for data fetching inside generateMetadata to complete before streaming UI to the client. This guarantees the first part of a streamed response includes <head> tags.

  • 由于流式是服务器渲染的，因此不会影响 SEO。你可以使用 Google 的 丰富的结果测试 工具查看你的页面在 Google 网络爬虫程序中的显示方式，并查看序列化的 HTML (source)。

    ¥Since streaming is server-rendered, it does not impact SEO. You can use the Rich Results Test tool from Google to see how your page appears to Google's web crawlers and view the serialized HTML (source).

状态代码 ​

¥Status Codes

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

¥When streaming, a 200 status code will be returned to signal that the request was successful.

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

¥The server can still communicate errors or issues to the client within the streamed content itself, for example, when using redirect or notFound. Since the response headers have already been sent to the client, the status code of the response cannot be updated. This does not affect SEO.

浏览器限制 ​

¥Browser limits

一些浏览器 缓冲流响应。在响应超过 1024 字节之前，你可能看不到流式响应。这通常只影响“hello world”应用，而不影响真正的应用。

¥Some browsers buffer a streaming response. You may not see the streamed response until the response exceeds 1024 bytes. This typically only affects “hello world” applications, but not real applications.

平台支持 ​

¥Platform Support

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

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

¥Learn how to configure streaming when self-hosting Next.js.

示例 ​

¥Examples

使用 Suspense 的流式 ​

¥Streaming with Suspense

除了 loading.js 之外，你还可以为自己的 UI 组件手动创建 Suspense Boundaries。App Router 支持使用 悬念 进行流式传输。

¥In addition to loading.js, you can also manually create Suspense Boundaries for your own UI components. The App Router supports streaming with Suspense.

<Suspense> 的工作原理是封装一个执行异步操作（例如获取数据）的组件，在操作发生时显示回退 UI（例如骨架、旋转器），然后在操作完成后交换组件。

¥<Suspense> works by wrapping a component that performs an asynchronous action (e.g. fetch data), showing fallback UI (e.g. skeleton, spinner) while it's happening, and then swapping in your component once the action completes.

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

export default function Posts() {
  return (
    <section>
      <Suspense fallback={<p>Loading feed...</p>}>
        <PostFeed />
      </Suspense>
      <Suspense fallback={<p>Loading weather...</p>}>
        <Weather />
      </Suspense>
    </section>
  )
}

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

¥By using Suspense, you get the benefits of:

  1. 流式服务器渲染 - 逐步将 HTML 从服务器渲染到客户端。

    ¥Streaming Server Rendering - Progressively rendering HTML from the server to the client.

  2. 选择性水合 - React 根据用户交互优先考虑哪些组件首先进行交互。

    ¥Selective Hydration - React prioritizes what components to make interactive first based on user interaction.

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

¥For more Suspense examples and use cases, please see the React Documentation.

版本历史 ​

¥Version History

版本更改
v13.0.0loading 已引入。