NNext.js 中文网 GitHub

template.js

template.js 文件的 API 参考。

template 文件类似于 layout,因为它包裹布局或页面。与跨路由持续存在并保持状态的布局不同,模板会被赋予一个唯一的 key,这意味着子 Client Components 会在导航时重置其状态。

当你需要执行以下操作时,它们很有用:

  • 在导航时重新同步 useEffect。
  • 在导航时重置子 Client Component 的状态。例如输入框。
  • 更改框架的默认行为。例如,布局内的 Suspense 边界只在首次加载时显示回退内容,而模板在每次导航时都会显示。

约定#

可以通过从 template.js 文件导出一个默认的 React 组件来定义模板。该组件应接受 children prop。

app/template.tsx
export default function Template({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>
}
app/template.js
export default function Template({ children }) {
  return <div>{children}</div>
}

在嵌套方面,template.js 渲染在布局及其子级之间。以下是一个简化的输出:

Output
<Layout>
  
  <Template key={routeParam}>{children}</Template>
</Layout>

在组件层级中,template.js 渲染在 layout.js 和 error.js 之间。它包裹 error.js、loading.js、not-found.js 和 page.js,但不包裹同一路由段中的 layout.js。

Props#

children(必需)#

模板接受一个 children prop。

Output
<Layout>
  
  <Template key={routeParam}>{children}</Template>
</Layout>

行为#

  • Server Components:默认情况下,模板是 Server Components。
  • 导航时:模板在其自身的路由段层级接收一个唯一的 key。当该路由段(包括其动态参数)发生变化时,它们会重新挂载。更深层级路由段内的导航不会重新挂载更高层级的模板。Search params 不会触发重新挂载。
  • 状态重置:模板内的任何 Client Component 都会在导航时重置其状态。
  • Effect 重新运行:像 useEffect 这样的 Effect 会随着组件重新挂载而重新同步。
  • DOM 重置:模板内的 DOM 元素会被完全重新创建。

导航和重新挂载期间的模板#

本节说明模板在导航期间的行为。它逐步展示每次路由变化时哪些模板会重新挂载以及原因。

使用以下项目结构树:

text
app
├── about
│   ├── page.tsx
├── blog
│   ├── [slug]
│   │   └── page.tsx
│   ├── page.tsx
│   └── template.tsx
├── layout.tsx
├── page.tsx
└── template.tsx

从 / 开始,React 树大致如下所示。

注意:示例中显示的 key 值仅作说明,你的应用中的值可能不同。

Output
<RootLayout>
  
  <Template key="/">
    <Page />
  </Template>
</RootLayout>

导航到 /about(第一段发生变化),根模板的 key 发生变化,它会重新挂载:

Output
<RootLayout>
  
  <Template key="/about">
    <AboutPage />
  </Template>
</RootLayout>

导航到 /blog(第一段发生变化),根模板的 key 发生变化,它会重新挂载,同时 blog 层级的模板会挂载:

Output
<RootLayout>
  
  <Template key="/blog">
    
    <Template key="/blog">
      <BlogIndexPage />
    </Template>
  </Template>
</RootLayout>

在同一第一段内导航到 /blog/first-post(子段发生变化),根模板的 key 不变,但 blog 层级模板的 key 发生变化,它会重新挂载:

Output
<RootLayout>
  
  <Template key="/blog">
    
    
    <Template key="/blog/first-post">
      <BlogPostPage slug="first-post" />
    </Template>
  </Template>
</RootLayout>

导航到 /blog/second-post(第一段相同,子段不同),根模板的 key 不变,但 blog 层级模板的 key 发生变化,它会再次重新挂载:

Output
<RootLayout>
  
  <Template key="/blog">
    
    
    <Template key="/blog/second-post">
      <BlogPostPage slug="second-post" />
    </Template>
  </Template>
</RootLayout>

版本历史#

版本变更
v13.0.0引入 template。
Next.js 中文网