logoAnt Design

⌘ K
  • 设计
  • 研发
  • 组件
  • 博客
  • 资源
  • 国内镜像
5.25.0
  • Ant Design of React
  • 更新日志
    v5.25.0
  • 如何使用
    • 快速上手
    • 在 Vite 中使用
    • 在 Next.js 中使用
      Updated
    • 在 Umi 中使用
    • 在 Rsbuild 中使用
    • 在 Farm 中使用
    • 使用 Refine
  • 进阶使用
    • 定制主题
    • 样式兼容
    • 服务端渲染
    • 使用 CSS 变量
      New
    • 使用自定义日期库
    • 国际化
    • 通用属性
    • React 19 兼容
      New
  • 迁移
    • 从 v4 到 v5
    • 从 Less 变量到 Design Token
  • 其他
    • 社区精选组件
    • 贡献指南
    • FAQ

在 Next.js 中使用

相关资源

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-首页模板集
Scaffolds-脚手架市场
Umi-React 应用开发框架
dumi-组件/文档研发工具
qiankun-微前端框架
Ant Motion-设计动效
国内镜像站点 🇨🇳

社区

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design 语雀专栏
Ant Design 知乎专栏
体验科技专栏
seeconf logoSEE Conf-蚂蚁体验科技大会
加入我们

帮助

GitHub
更新日志
常见问题
报告 Bug
议题
讨论区
StackOverflow
SegmentFault

Ant XTech logo更多产品

yuque logo语雀-构建你的数字花园
AntV logoAntV-数据可视化解决方案
Egg logoEgg-企业级 Node.js 框架
Kitchen logoKitchen-Sketch 工具集
Galacean logoGalacean-互动图形解决方案
xtech logo蚂蚁体验科技
主题编辑器
Made with ❤ by
蚂蚁集团和 Ant Design 开源社区
loading

Next.js 是目前世界上最流行的 React 服务端同构框架,本文会尝试在 Next.js 创建的工程中使用 antd 组件。

安装和初始化

在开始之前,你可能需要安装 yarn 或者 pnpm 或者 bun。

npm iconnpm
yarn iconyarn
pnpm iconpnpm
Bun LogoBun
bash
$ npx create-next-app antd-demo

工具会自动初始化一个脚手架并安装项目的各种必要依赖,在安装过程中,有一些配置项需要自行选择,如果在过程中出现网络问题,请尝试配置代理,或使用其他 npm registry,例如,你可以切换到淘宝镜像源:npm config set registry https://registry.npmmirror.com。

初始化完成后,我们进入项目并启动。

bash
$ cd antd-demo
$ npm run dev

此时使用浏览器访问 http://localhost:3000/ ,看到 NEXT 的 logo 就算成功了。

引入 antd

现在从 yarn 或 npm 或 pnpm 或 bun 安装并引入 antd。

npm iconnpm
yarn iconyarn
pnpm iconpnpm
Bun LogoBun
bash
$ npm install antd --save

修改 src/app/page.tsx,引入 antd 的按钮组件。

tsx
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 的官方文档。

细心的朋友可以发现这时引入的 antd 组件在首屏并没有样式,下面就需要根据 Next.js 的模式来选择不同的 SSR 样式处理方式。

使用 App Router Updated

如果你在 Next.js 当中使用了 App Router, 并使用 antd 作为页面组件库,为了让 antd 组件库在你的 Next.js 应用中能够更好的工作,提供更好的用户体验,你可以尝试使用下面的方式将 antd 首屏样式按需抽离并植入到 HTML 中,以避免页面闪动的情况。

  1. 安装 @ant-design/nextjs-registry
npm iconnpm
yarn iconyarn
pnpm iconpnpm
Bun LogoBun
bash
$ npm install @ant-design/nextjs-registry --save
  1. 在 app/layout.tsx 中使用
tsx
import React from 'react';
import { AntdRegistry } from '@ant-design/nextjs-registry';
const RootLayout = ({ children }: React.PropsWithChildren) => (
<html lang="en">
<body>
<AntdRegistry>{children}</AntdRegistry>
</body>
</html>
);
export default RootLayout;
WARNING

注意: Next.js App Router 当前不支持直接使用 . 引入的子组件,如 <Select.Option />、<Typography.Text /> 等,需要从路径引入这些子组件来避免错误。

更多详细的细节可以参考 with-nextjs-app-router-inline-style。

使用 Pages Router

如果你在 Next.js 当中使用了 Pages Router, 并使用 antd 作为页面组件库,为了让 antd 组件库在你的 Next.js 应用中能够更好的工作,提供更好的用户体验,你可以尝试使用下面的方式将 antd 首屏样式按需抽离并植入到 HTML 中,以避免页面闪动的情况。

  1. 安装 @ant-design/cssinjs

开发者注意事项:

请注意,安装 @ant-design/cssinjs 时必须确保版本号跟 antd 本地的 node_modules 中的 @ant-design/cssinjs 版本保持一致,否则会出现多个 React 实例,导致无法正确的读取 ctx。(Tips: 你可以通过 npm ls @ant-design/cssinjs 命令查看本地版本)

image
npm iconnpm
yarn iconyarn
pnpm iconpnpm
Bun LogoBun
bash
$ npm install @ant-design/cssinjs --save
  1. 改写 pages/_document.tsx
tsx
import React from 'react';
import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
import Document, { Head, Html, Main, NextScript } from 'next/document';
import type { DocumentContext } from 'next/document';
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({
enhanceApp: (App) => (props) => (
<StyleProvider cache={cache}>
<App {...props} />
</StyleProvider>
),
});
const initialProps = await Document.getInitialProps(ctx);
const style = extractStyle(cache, true);
return {
...initialProps,
styles: (
<>
{initialProps.styles}
<style dangerouslySetInnerHTML={{ __html: style }} />
</>
),
};
};
export default MyDocument;
  1. 支持自定义主题
ts
// theme/themeConfig.ts
import type { ThemeConfig } from 'antd';
const theme: ThemeConfig = {
token: {
fontSize: 16,
colorPrimary: '#52c41a',
},
};
export default theme;
  1. 改写 pages/_app.tsx
tsx
import React from 'react';
import { ConfigProvider } from 'antd';
import type { AppProps } from 'next/app';
import theme from './theme/themeConfig';
const App = ({ Component, pageProps }: AppProps) => (
<ConfigProvider theme={theme}>
<Component {...pageProps} />
</ConfigProvider>
);
export default App;
  1. 在页面中使用 antd
tsx
import React from 'react';
import { Button } from 'antd';
const Home = () => (
<div className="App">
<Button type="primary">Button</Button>
</div>
);
export default Home;

更多详细的细节可以参考 with-nextjs-inline-style。