2023-06-12 16:42:06 +08:00
|
|
|
|
---
|
2023-08-04 19:27:38 +08:00
|
|
|
|
group:
|
|
|
|
|
|
title: 如何使用
|
2024-05-07 15:30:29 +08:00
|
|
|
|
order: 3
|
2023-06-12 16:42:06 +08:00
|
|
|
|
title: 在 Next.js 中使用
|
2023-12-29 11:55:11 +08:00
|
|
|
|
tag: Updated
|
2023-06-12 16:42:06 +08:00
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
[Next.js](https://nextjs.org/) 是目前世界上最流行的 React 服务端同构框架，本文会尝试在 Next.js 创建的工程中使用 `antd` 组件。
|
|
|
|
|
|
|
|
|
|
|
|
## 安装和初始化
|
|
|
|
|
|
|
2024-04-05 18:27:10 +08:00
|
|
|
|
在开始之前，你可能需要安装 [yarn](https://github.com/yarnpkg/yarn/) 或者 [pnpm](https://pnpm.io/zh/) 或者 [bun](https://bun.sh/)。
|
2023-06-12 16:42:06 +08:00
|
|
|
|
|
2024-04-05 18:27:10 +08:00
|
|
|
|
<InstallDependencies npm='$ npx create-next-app antd-demo' yarn='$ yarn create next-app antd-demo' pnpm='$ pnpm create next-app antd-demo' bun='$ bun create next-app antd-demo'></InstallDependencies>
|
2023-06-12 16:42:06 +08:00
|
|
|
|
|
2024-02-25 11:45:22 +08:00
|
|
|
|
工具会自动初始化一个脚手架并安装项目的各种必要依赖，在安装过程中，有一些配置项需要自行选择，如果在过程中出现网络问题，请尝试配置代理，或使用其他 npm registry，例如，你可以切换到淘宝镜像源：`npm config set registry https://registry.npmmirror.com`。
|
2023-06-12 16:42:06 +08:00
|
|
|
|
|
|
|
|
|
|
初始化完成后，我们进入项目并启动。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
$ cd antd-demo
|
|
|
|
|
|
$ npm run dev
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
此时使用浏览器访问 http://localhost:3000/ ，看到 NEXT 的 logo 就算成功了。
|
|
|
|
|
|
|
|
|
|
|
|
## 引入 antd
|
|
|
|
|
|
|
2024-04-05 18:27:10 +08:00
|
|
|
|
现在从 yarn 或 npm 或 pnpm 或 bun 安装并引入 antd。
|
2023-06-12 16:42:06 +08:00
|
|
|
|
|
2024-04-05 18:27:10 +08:00
|
|
|
|
<InstallDependencies npm='$ npm install antd --save' yarn='$ yarn add antd' pnpm='$ pnpm install antd --save' bun='$ bun add antd'></InstallDependencies>
|
2023-06-12 16:42:06 +08:00
|
|
|
|
|
|
|
|
|
|
修改 `src/app/page.tsx`，引入 antd 的按钮组件。
|
|
|
|
|
|
|
2023-10-29 14:51:39 +08:00
|
|
|
|
```tsx
|
2023-06-12 16:42:06 +08:00
|
|
|
|
import React from 'react';
|
|
|
|
|
|
import { Button } from 'antd';
|
|
|
|
|
|
|
|
|
|
|
|
const Home = () => (
|
|
|
|
|
|
<div className="App">
|
|
|
|
|
|
<Button type="primary">Button</Button>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
|
|
export default Home;
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
好了，现在你应该能看到页面上已经有了 `antd` 的蓝色按钮组件，接下来就可以继续选用其他组件开发应用了。其他开发流程你可以参考 Next.js 的[官方文档](https://nextjs.org/)。
|
|
|
|
|
|
|
2023-12-29 11:55:11 +08:00
|
|
|
|
细心的朋友可以发现这时引入的 antd 组件在首屏并没有样式，下面就需要根据 Next.js 的模式来选择不同的 SSR 样式处理方式。
|
2023-07-16 12:13:22 +08:00
|
|
|
|
|
2023-12-29 11:55:11 +08:00
|
|
|
|
## 使用 App Router <Badge>Updated</Badge>
|
2023-10-29 14:51:39 +08:00
|
|
|
|
|
|
|
|
|
|
如果你在 Next.js 当中使用了 App Router, 并使用 antd 作为页面组件库，为了让 antd 组件库在你的 Next.js 应用中能够更好的工作，提供更好的用户体验，你可以尝试使用下面的方式将 antd 首屏样式按需抽离并植入到 HTML 中，以避免页面闪动的情况。
|
|
|
|
|
|
|
2023-12-29 11:55:11 +08:00
|
|
|
|
1. 安装 `@ant-design/nextjs-registry`
|
2023-11-16 20:14:27 +08:00
|
|
|
|
|
2024-04-05 18:27:10 +08:00
|
|
|
|
<InstallDependencies npm='$ npm install @ant-design/nextjs-registry --save' yarn='$ yarn add @ant-design/nextjs-registry' pnpm='$ pnpm install @ant-design/nextjs-registry --save' bun='$ bun add @ant-design/nextjs-registry'></InstallDependencies>
|
2023-10-29 14:51:39 +08:00
|
|
|
|
|
2023-12-29 11:55:11 +08:00
|
|
|
|
2. 在 `app/layout.tsx` 中使用
|
2023-10-29 14:51:39 +08:00
|
|
|
|
|
|
|
|
|
|
```tsx
|
|
|
|
|
|
import React from 'react';
|
2023-12-29 11:55:11 +08:00
|
|
|
|
import { AntdRegistry } from '@ant-design/nextjs-registry';
|
2023-10-29 14:51:39 +08:00
|
|
|
|
|
|
|
|
|
|
const RootLayout = ({ children }: React.PropsWithChildren) => (
|
|
|
|
|
|
<html lang="en">
|
2023-12-29 11:55:11 +08:00
|
|
|
|
<body>
|
|
|
|
|
|
<AntdRegistry>{children}</AntdRegistry>
|
2023-10-29 14:51:39 +08:00
|
|
|
|
</body>
|
|
|
|
|
|
</html>
|
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
|
|
export default RootLayout;
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2023-12-29 11:55:11 +08:00
|
|
|
|
<!-- prettier-ignore -->
|
|
|
|
|
|
:::warning
|
|
|
|
|
|
注意: Next.js App Router 当前不支持直接使用 `.` 引入的子组件，如 `<Select.Option />`、`<Typography.Text />` 等，需要从路径引入这些子组件来避免错误。
|
|
|
|
|
|
:::
|
2023-10-29 14:51:39 +08:00
|
|
|
|
|
|
|
|
|
|
更多详细的细节可以参考 [with-nextjs-app-router-inline-style](https://github.com/ant-design/ant-design-examples/tree/main/examples/with-nextjs-app-router-inline-style)。
|
|
|
|
|
|
|
2023-09-01 10:51:21 +08:00
|
|
|
|
## 使用 Pages Router
|
2023-07-19 16:56:08 +08:00
|
|
|
|
|
|
|
|
|
|
如果你在 Next.js 当中使用了 Pages Router, 并使用 antd 作为页面组件库，为了让 antd 组件库在你的 Next.js 应用中能够更好的工作，提供更好的用户体验，你可以尝试使用下面的方式将 antd 首屏样式按需抽离并植入到 HTML 中，以避免页面闪动的情况。
|
|
|
|
|
|
|
|
|
|
|
|
1. 安装 `@ant-design/cssinjs`
|
|
|
|
|
|
|
2023-11-16 20:14:27 +08:00
|
|
|
|
> 开发者注意事项：
|
|
|
|
|
|
>
|
|
|
|
|
|
> 请注意，安装 `@ant-design/cssinjs` 时必须确保版本号跟 `antd` 本地的 `node_modules` 中的 `@ant-design/cssinjs` 版本保持一致，否则会出现多个 React 实例，导致无法正确的读取 ctx。（Tips: 你可以通过 `npm ls @ant-design/cssinjs` 命令查看本地版本）
|
2023-11-17 09:49:54 +08:00
|
|
|
|
>
|
|
|
|
|
|
> <img width="514" alt="image" src="https://github.com/ant-design/ant-design/assets/49217418/aad6e9e2-62cc-4c89-a0b6-38c592e3c648">
|
2023-11-16 20:14:27 +08:00
|
|
|
|
|
2024-04-05 18:27:10 +08:00
|
|
|
|
<InstallDependencies npm='$ npm install @ant-design/cssinjs --save' yarn='$ yarn add @ant-design/cssinjs' pnpm='$ pnpm install @ant-design/cssinjs --save' bun='$ bun add @ant-design/cssinjs'></InstallDependencies>
|
2023-07-19 16:56:08 +08:00
|
|
|
|
|
|
|
|
|
|
2. 改写 `pages/_document.tsx`
|
|
|
|
|
|
|
|
|
|
|
|
```tsx
|
2023-07-22 21:43:13 +08:00
|
|
|
|
import React from 'react';
|
2023-09-03 00:22:34 +08:00
|
|
|
|
import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
|
2023-07-22 21:43:13 +08:00
|
|
|
|
import Document, { Head, Html, Main, NextScript } from 'next/document';
|
|
|
|
|
|
import type { DocumentContext } from 'next/document';
|
2023-07-19 18:43:44 +08:00
|
|
|
|
|
|
|
|
|
|
const MyDocument = () => (
|
|
|
|
|
|
<Html lang="en">
|
|
|
|
|
|
<Head />
|
|
|
|
|
|
<body>
|
|
|
|
|
|
<Main />
|
|
|
|
|
|
<NextScript />
|
|
|
|
|
|
</body>
|
|
|
|
|
|
</Html>
|
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
|
|
MyDocument.getInitialProps = async (ctx: DocumentContext) => {
|
|
|
|
|
|
const cache = createCache();
|
|
|
|
|
|
const originalRenderPage = ctx.renderPage;
|
|
|
|
|
|
ctx.renderPage = () =>
|
|
|
|
|
|
originalRenderPage({
|
2023-07-22 21:43:13 +08:00
|
|
|
|
enhanceApp: (App) => (props) => (
|
|
|
|
|
|
<StyleProvider cache={cache}>
|
|
|
|
|
|
<App {...props} />
|
|
|
|
|
|
</StyleProvider>
|
|
|
|
|
|
),
|
2023-07-19 18:43:44 +08:00
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
|
|
const initialProps = await Document.getInitialProps(ctx);
|
|
|
|
|
|
const style = extractStyle(cache, true);
|
|
|
|
|
|
return {
|
|
|
|
|
|
...initialProps,
|
|
|
|
|
|
styles: (
|
|
|
|
|
|
<>
|
|
|
|
|
|
{initialProps.styles}
|
2023-07-22 21:43:13 +08:00
|
|
|
|
<style dangerouslySetInnerHTML={{ __html: style }} />
|
2023-07-19 18:43:44 +08:00
|
|
|
|
</>
|
|
|
|
|
|
),
|
|
|
|
|
|
};
|
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
export default MyDocument;
|
2023-07-19 16:56:08 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
3. 支持自定义主题
|
|
|
|
|
|
|
2023-07-20 00:24:57 +08:00
|
|
|
|
```ts
|
|
|
|
|
|
// theme/themeConfig.ts
|
|
|
|
|
|
import type { ThemeConfig } from 'antd';
|
2023-07-19 16:56:08 +08:00
|
|
|
|
|
2023-07-20 00:24:57 +08:00
|
|
|
|
const theme: ThemeConfig = {
|
|
|
|
|
|
token: {
|
|
|
|
|
|
fontSize: 16,
|
|
|
|
|
|
colorPrimary: '#52c41a',
|
|
|
|
|
|
},
|
|
|
|
|
|
};
|
2023-07-19 16:56:08 +08:00
|
|
|
|
|
2023-07-20 00:24:57 +08:00
|
|
|
|
export default theme;
|
2023-07-19 16:56:08 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
4. 改写 `pages/_app.tsx`
|
|
|
|
|
|
|
|
|
|
|
|
```tsx
|
2023-07-22 21:43:13 +08:00
|
|
|
|
import React from 'react';
|
2023-07-20 00:24:57 +08:00
|
|
|
|
import { ConfigProvider } from 'antd';
|
2023-07-19 16:56:08 +08:00
|
|
|
|
import type { AppProps } from 'next/app';
|
2023-09-03 00:22:34 +08:00
|
|
|
|
|
2023-10-08 19:41:34 +08:00
|
|
|
|
import theme from './theme/themeConfig';
|
2023-07-20 00:24:57 +08:00
|
|
|
|
|
|
|
|
|
|
const App = ({ Component, pageProps }: AppProps) => (
|
|
|
|
|
|
<ConfigProvider theme={theme}>
|
|
|
|
|
|
<Component {...pageProps} />
|
|
|
|
|
|
</ConfigProvider>
|
|
|
|
|
|
);
|
2023-07-19 16:56:08 +08:00
|
|
|
|
|
2023-07-20 00:24:57 +08:00
|
|
|
|
export default App;
|
2023-07-19 16:56:08 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
5. 在页面中使用 antd
|
|
|
|
|
|
|
|
|
|
|
|
```tsx
|
2023-07-22 21:43:13 +08:00
|
|
|
|
import React from 'react';
|
2023-07-19 16:56:08 +08:00
|
|
|
|
import { Button } from 'antd';
|
|
|
|
|
|
|
2023-07-20 00:24:57 +08:00
|
|
|
|
const Home = () => (
|
|
|
|
|
|
<div className="App">
|
|
|
|
|
|
<Button type="primary">Button</Button>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
|
|
export default Home;
|
2023-07-19 16:56:08 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
更多详细的细节可以参考 [with-nextjs-inline-style](https://github.com/ant-design/ant-design-examples/tree/main/examples/with-nextjs-inline-style)。
|
