Ant Design

用于在 Next.js 应用中构建企业级 UI 的 Ant Design 指南。

快速开始

# 核心依赖
pnpm add antd @ant-design/nextjs-registry @ant-design/icons

// app/layout.tsx - 必需配置
import { AntdRegistry } from "@ant-design/nextjs-registry";
import { ConfigProvider, theme } from "antd";
import zhCN from "antd/locale/zh_CN";

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>
        <AntdRegistry>
          <ConfigProvider locale={zhCN} theme={{ token: { colorPrimary: "#006aff" } }}>
            {children}
          </ConfigProvider>
        </AntdRegistry>
      </body>
    </html>
  );
}

导入模式

// 组件
import { Button, Table, Form, Modal, message, Space, Tag, Select, Input } from "antd";

// 图标
import { UserOutlined, PlusOutlined, DeleteOutlined, SearchOutlined } from "@ant-design/icons";

// 类型 - 从子模块导入
import type { ColumnsType } from "antd/es/table";
import type { FormInstance } from "antd/es/form";
import type { MenuProps } from "antd";

常用组件速查

组件	用法
Button	`<Button type="primary" icon={<PlusOutlined />}>添加</Button>`
Tag	`<Tag color="success">成功</Tag>`
Modal	`Modal.confirm({ title: "确认删除", onOk })`
message	`message.success("操作成功")`
Input.Search	`<Input.Search placeholder="搜索..." onSearch={handleSearch} />`

CRUD 模板

function UserManagement() {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(false);
  const [isModalOpen, setIsModalOpen] = useState(false);
  const [editingRecord, setEditingRecord] = useState(null);
  const [form] = Form.useForm();

  const fetchData = async () => {
    setLoading(true);
    // 获取数据
    setLoading(false);
  };

  const handleAdd = () => {
    setEditingRecord(null);
    form.resetFields();
    setIsModalOpen(true);
  };

  const handleEdit = (record) => {
    setEditingRecord(record);
    form.setFieldsValue(record);
    setIsModalOpen(true);
  };

  const handleDelete = (record) => {
    Modal.confirm({
      title: "确认删除",
      content: `确定要删除 "${record.name}" 吗？`,
      okButtonProps: { danger: true },
      onOk: async () => {
        // 删除逻辑
        message.success("删除成功");
        fetchData();
      },
    });
  };

  const handleSubmit = async (values) => {
    // 提交逻辑
    message.success(editingRecord ? "更新成功" : "创建成功");
    setIsModalOpen(false);
    fetchData();
  };

  return (
    <div>
      <div style={{ marginBottom: 16 }}>
        <Button type="primary" icon={<PlusOutlined />} onClick={handleAdd}>
          添加
        </Button>
      </div>
      <Table columns={columns} dataSource={data} loading={loading} rowKey="id" />
      <Modal
        title={editingRecord ? "编辑" : "添加"}
        open={isModalOpen}
        onOk={() => form.submit()}
        onCancel={() => setIsModalOpen(false)}
      >
        <Form form={form} onFinish={handleSubmit} layout="vertical">
          {/* 表单项 */}
        </Form>
      </Modal>
    </div>
  );
}

重要注意事项

类型导入: ColumnsType 必须从 antd/es/table 导入，不能从 antd 导入
图标名称: ShieldOutlined 不存在，应使用 SafetyOutlined
SSR 兼容: Next.js App Router 必须使用 AntdRegistry 包裹
中文本地化: 从 antd/locale/zh_CN 导入 zhCN
图标混用: lucide-react 图标可与 antd 图标混用，注意 props 差异：
- antd: style={{ fontSize: 24 }}
- lucide-react: size={24}
语义化 DOM: 使用 classNames 和 styles props 进行样式定制
Hydration 安全: 避免在组件渲染中使用 Math.random()

查询组件文档

当需要查询特定组件的详细 API 时，搜索本地文档：

LOCAL_DOCS.md - 本地文档路径和搜索方法