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。 |