From 20b5babd9e8faf03a143e4c15cb2643e243a0129 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?kiner-tang=28=E6=96=87=E8=BE=89=29?= <1127031143@qq.com> Date: Wed, 19 Jul 2023 16:56:08 +0800 Subject: [PATCH] docs: update docs about nextjs pages router (#43651) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: update docs about nextjs pages router * Update docs/react/use-with-next.en-US.md Co-authored-by: afc163 Signed-off-by: kiner-tang(文辉) <1127031143@qq.com> * docs: update docs --------- Signed-off-by: kiner-tang(文辉) <1127031143@qq.com> Co-authored-by: afc163 --- docs/react/use-with-next.en-US.md | 120 +++++++++++++++++++++++++++++- docs/react/use-with-next.zh-CN.md | 120 +++++++++++++++++++++++++++++- 2 files changed, 232 insertions(+), 8 deletions(-) diff --git a/docs/react/use-with-next.en-US.md b/docs/react/use-with-next.en-US.md index d2b7935fd3..b320dbd7c8 100644 --- a/docs/react/use-with-next.en-US.md +++ b/docs/react/use-with-next.en-US.md @@ -31,8 +31,6 @@ Now we install `antd` from yarn or npm or pnpm. Modify `src/app/page.tsx`, import Button component from `antd`. ```jsx -'use client'; - import React from 'react'; import { Button } from 'antd'; @@ -49,6 +47,120 @@ OK, you should now see a blue primary button displayed on the page. Next you can We are successfully running antd components now, go build your own application! +## Use the Pages Router of Next.js + +If you are using the Pages Router in Next.js and using antd as your component library, to make the antd component library work better in your Next.js application and provide a better user experience, you can try using the following method to extract and inject antd's first-screen styles into HTML to avoid page flicker. + +1. Install `@ant-design/cssinjs` + + + +2. Rewrite `pages/_document.tsx` + +```tsx +import Document, { Html, Head, Main, NextScript, DocumentContext } from 'next/document'; +import { StyleProvider, createCache, extractStyle } from '@ant-design/cssinjs'; +export default class MyDocument extends Document { + static async getInitialProps(ctx: DocumentContext) { + const cache = createCache(); + const originalRenderPage = ctx.renderPage; + ctx.renderPage = () => + originalRenderPage({ + enhanceApp: (App) => (props) => ( + + + + ), + }); + + const initialProps = await Document.getInitialProps(ctx); + // 1.1 extract style which had been used + const style = extractStyle(cache, true); + return { + ...initialProps, + styles: ( + <> + {initialProps.styles} + {/* 1.2 inject css */} + + + ), + }; + } + + render() { + return ( + + + +
+ + + + ); + } +} +``` + +3. Supports custom themes + +```tsx +import React from 'react'; +import { ConfigProvider } from 'antd'; + +const withTheme = (node: JSX.Element) => ( + <> + + + {node} + + + +); + +export default withTheme; +``` + +4. Rewrite `pages/_app.tsx` + +```tsx +import '../styles/globals.css'; +import type { AppProps } from 'next/app'; +import withTheme from '../theme'; + +export default function App({ Component, pageProps }: AppProps) { + return withTheme(); +} +``` + +5. Use antd in page component + +```tsx +import { Button } from 'antd'; + +export default function Home() { + return ( +
+ +
+ ); +} +``` + +For more detailed information, please refer to [with-nextjs-inline-style](https://github.com/ant-design/ant-design-examples/tree/main/examples/with-nextjs-inline-style). + ## Using Next.js App Router If you are using the App Router in Next.js and using antd as your component library, to make the antd component library work better in your Next.js application and provide a better user experience, you can try using the following method to extract and inject antd's first-screen styles into HTML to avoid page flicker. @@ -122,8 +234,6 @@ export default theme; 5. Use in page ```tsx -'use client'; - import { Button, ConfigProvider } from 'antd'; import React from 'react'; import theme from './themeConfig'; @@ -139,4 +249,6 @@ const HomePage: React.FC = () => ( export default HomePage; ``` +> Tips: The above method does not use sub-components such as `Select.Option` and `Typography.text` in the page, so it can be used normally. However, if you use a sub-component like this in your page, you will currently see the following warning in next.js: `Error: Cannot access .Option on the server. You cannot dot into a client module from a server component. You can only pass the imported name through.`, currently need to wait for Next.js official solution. Before again, if you use the above sub-components in your page, you can add "use client" to the first line of the page component to avoid warnings. See examples for more details: [with-sub-components](https://github.com/ant-design/ant-design-examples/blob/main/examples/with-nextjs-app-router-inline-style/src/app/with-sub-components/page.tsx). + For more detailed information, please refer to [with-nextjs-app-router-inline-style](https://github.com/ant-design/ant-design-examples/tree/main/examples/with-nextjs-app-router-inline-style)。 diff --git a/docs/react/use-with-next.zh-CN.md b/docs/react/use-with-next.zh-CN.md index fd2e79ef0f..564e473a2a 100644 --- a/docs/react/use-with-next.zh-CN.md +++ b/docs/react/use-with-next.zh-CN.md @@ -49,6 +49,120 @@ export default Home; 我们现在已经把 antd 组件成功运行起来了，开始开发你的应用吧！ +## 使用 Next.js 的 Pages Router + +如果你在 Next.js 当中使用了 Pages Router, 并使用 antd 作为页面组件库，为了让 antd 组件库在你的 Next.js 应用中能够更好的工作，提供更好的用户体验，你可以尝试使用下面的方式将 antd 首屏样式按需抽离并植入到 HTML 中，以避免页面闪动的情况。 + +1. 安装 `@ant-design/cssinjs` + + + +2. 改写 `pages/_document.tsx` + +```tsx +import Document, { Html, Head, Main, NextScript, DocumentContext } from 'next/document'; +import { StyleProvider, createCache, extractStyle } from '@ant-design/cssinjs'; +export default class MyDocument extends Document { + static async getInitialProps(ctx: DocumentContext) { + const cache = createCache(); + const originalRenderPage = ctx.renderPage; + ctx.renderPage = () => + originalRenderPage({ + enhanceApp: (App) => (props) => ( + + + + ), + }); + + const initialProps = await Document.getInitialProps(ctx); + // 1.1 extract style which had been used + const style = extractStyle(cache, true); + return { + ...initialProps, + styles: ( + <> + {initialProps.styles} + {/* 1.2 inject css */} + + + ), + }; + } + + render() { + return ( + + + +
+ + + + ); + } +} +``` + +3. 支持自定义主题 + +```tsx +import React from 'react'; +import { ConfigProvider } from 'antd'; + +const withTheme = (node: JSX.Element) => ( + <> + + + {node} + + + +); + +export default withTheme; +``` + +4. 改写 `pages/_app.tsx` + +```tsx +import '../styles/globals.css'; +import type { AppProps } from 'next/app'; +import withTheme from '../theme'; + +export default function App({ Component, pageProps }: AppProps) { + return withTheme(); +} +``` + +5. 在页面中使用 antd + +```tsx +import { Button } from 'antd'; + +export default function Home() { + return ( +
+ +
+ ); +} +``` + +更多详细的细节可以参考 [with-nextjs-inline-style](https://github.com/ant-design/ant-design-examples/tree/main/examples/with-nextjs-inline-style)。 + ## 使用 Next.js 的 App Router 如果你在 Next.js 当中使用了 App Router, 并使用 antd 作为页面组件库，为了让 antd 组件库在你的 Next.js 应用中能够更好的工作，提供更好的用户体验，你可以尝试使用下面的方式将 antd 首屏样式按需抽离并植入到 HTML 中，以避免页面闪动的情况。 @@ -60,8 +174,6 @@ export default Home; 2. 创建 `lib/AntdRegistry.tsx` ```tsx -'use client'; - import { StyleProvider, createCache, extractStyle } from '@ant-design/cssinjs'; import { useServerInsertedHTML } from 'next/navigation'; import React from 'react'; @@ -122,8 +234,6 @@ export default theme; 5. 在页面中使用 ```tsx -'use client'; - import { Button, ConfigProvider } from 'antd'; import React from 'react'; import theme from './themeConfig'; @@ -139,4 +249,6 @@ const HomePage: React.FC = () => ( export default HomePage; ``` +> 注意: 上述方式没有在页面中使用如：`Select.Option` 、 `Typography.Text` 等子组件，因此可以正常使用。但如果你的页面中有使用类似这样的子组件，目前在 Next.js 中会看到如下警告：`Error: Cannot access .Option on the server. You cannot dot into a client module from a server component. You can only pass the imported name through.`，目前需等待 Next.js 官方解决。再次之前，如果你的页面中使用了上述子组件，可在页面组件第一行加上 `"use client";` 来避免警告。更多细节可以参考示例：[with-sub-components](https://github.com/ant-design/ant-design-examples/blob/main/examples/with-nextjs-app-router-inline-style/src/app/with-sub-components/page.tsx)。 + 更多详细的细节可以参考 [with-nextjs-app-router-inline-style](https://github.com/ant-design/ant-design-examples/tree/main/examples/with-nextjs-app-router-inline-style)。