自定义文档
自定义 Document
可以更新用于渲染页面的 <html>
和 <body>
标签。
要覆盖默认的 Document
,请按如下所示创建 pages/_document
文件:
pages/_document.tsx
TypeScript
import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
<Html lang="en">
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
值得注意的是:
_document
仅在服务器端渲染,因此不能在此文件中使用onClick
等事件处理程序。<Html>
、<Head />
、<Main />
和<NextScript />
对于正确渲染页面是必需的。
注意事项
- 在
_document
中使用的<Head />
组件与next/head
不同。这里使用的<Head />
组件只应用于所有页面通用的<head>
代码。对于其他情况,如<title>
标签,我们建议在页面或组件中使用next/head
。 - 位于
<Main />
外的 React 组件不会被浏览器初始化。不要在此处添加应用程序逻辑或自定义 CSS(如styled-jsx
)。如果需要在所有页面中共享组件(如菜单或工具栏),请阅读布局。 Document
目前不支持 Next.js 数据获取方法,如getStaticProps
或getServerSideProps
。
自定义 renderPage
自定义 renderPage
是高级用法,仅在需要像 CSS-in-JS 这样的库支持服务器端渲染时使用。对于内置的 styled-jsx
支持,这是不需要的。
**我们不建议使用这种模式。**相反,考虑渐进式采用 App Router,它可以更轻松地为页面和布局获取数据。
pages/_document.tsx
TypeScript
import Document, {
Html,
Head,
Main,
NextScript,
DocumentContext,
DocumentInitialProps,
} from 'next/document'
class MyDocument extends Document {
static async getInitialProps(
ctx: DocumentContext
): Promise<DocumentInitialProps> {
const originalRenderPage = ctx.renderPage
// 同步运行 React 渲染逻辑
ctx.renderPage = () =>
originalRenderPage({
// 用于包装整个 React 树
enhanceApp: (App) => App,
// 用于按页面基础包装
enhanceComponent: (Component) => Component,
})
// 运行父级 `getInitialProps`,现在包含自定义 `renderPage`
const initialProps = await Document.getInitialProps(ctx)
return initialProps
}
render() {
return (
<Html lang="en">
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
}
export default MyDocument
值得注意的是:
- 在
_document
中的getInitialProps
在客户端转换期间不会被调用。_document
的ctx
对象等同于在getInitialProps
中接收的对象,另外还有renderPage
。