GitHub
/
ant-design
6
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

docs: update docs about nextjs pages router (#43651) 

* docs: update docs about nextjs pages router

* Update docs/react/use-with-next.en-US.md

Co-authored-by: afc163 <afc163@gmail.com>
Signed-off-by: kiner-tang(文辉) <1127031143@qq.com>

* docs: update docs

---------

Signed-off-by: kiner-tang(文辉) <1127031143@qq.com>
Co-authored-by: afc163 <afc163@gmail.com>
pull/43657/head
kiner-tang(文辉) 1 year ago
committed by GitHub
parent
5eb9f5db9b
commit
20b5babd9e
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 232 additions and 8 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 120
      docs/react/use-with-next.en-US.md
  2. 120
      docs/react/use-with-next.zh-CN.md

120
docs/react/use-with-next.en-US.md
View File

@ -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`
<InstallDependencies npm='$ npm install @ant-design/cssinjs --save' yarn='$ yarn add @ant-design/cssinjs' pnpm='$ pnpm install @ant-design/cssinjs --save'></InstallDependencies>
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) => (
<StyleProvider cache={cache}>
<App {...props} />
</StyleProvider>
),
});
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 */}
<style dangerouslySetInnerHTML={{ __html: style }}></style>
</>
),
};
}
render() {
return (
<Html lang="en">
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
}
```
3. Supports custom themes
```tsx
import React from 'react';
import { ConfigProvider } from 'antd';
const withTheme = (node: JSX.Element) => (
<>
<ConfigProvider
theme={{
token: {
colorPrimary: '#52c41a',
},
}}
>
<ConfigProvider
theme={{
token: {
borderRadius: 16,
},
}}
>
{node}
</ConfigProvider>
</ConfigProvider>
</>
);
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(<Component {...pageProps} />);
}
```
5. Use antd in page component
```tsx
import { Button } from 'antd';
export default function Home() {
return (
<div className="App">
<Button type="primary">Button</Button>
</div>
);
}
```
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)。

120
docs/react/use-with-next.zh-CN.md
View File

@ -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`
<InstallDependencies npm='$ npm install @ant-design/cssinjs --save' yarn='$ yarn add @ant-design/cssinjs' pnpm='$ pnpm install @ant-design/cssinjs --save'></InstallDependencies>
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) => (
<StyleProvider cache={cache}>
<App {...props} />
</StyleProvider>
),
});
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 */}
<style dangerouslySetInnerHTML={{ __html: style }}></style>
</>
),
};
}
render() {
return (
<Html lang="en">
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
}
```
3. 支持自定义主题
```tsx
import React from 'react';
import { ConfigProvider } from 'antd';
const withTheme = (node: JSX.Element) => (
<>
<ConfigProvider
theme={{
token: {
colorPrimary: '#52c41a',
},
}}
>
<ConfigProvider
theme={{
token: {
borderRadius: 16,
},
}}
>
{node}
</ConfigProvider>
</ConfigProvider>
</>
);
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(<Component {...pageProps} />);
}
```
5. 在页面中使用 antd
```tsx
import { Button } from 'antd';
export default function Home() {
return (
<div className="App">
<Button type="primary">Button</Button>
</div>
);
}
```
更多详细的细节可以参考 [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)。

Write Preview
Loading…
Cancel
Save