五、核心组件
Chakra UI 3.x提供了超过100个高质量的组件，覆盖了从基础布局到复杂交互的所有场景。以下是最常用的核心组件及其详细用法。
5.1 布局组件
Box和Flex：最基础的布局组件，Box是div的封装，Flex是Flexbox布局的便捷组件。
import { Box, Flex, Spacer, Center, Container, Stack } from '@chakra-ui/react'
// Box - 通用容器
<Box bg="gray.100" p={4} borderRadius="md" shadow="sm">
基础容器
</Box>
// Flex - Flexbox布局
<Flex align="center" justify="space-between" wrap="wrap" gap={4}>
<Box>项目1</Box>
<Box>项目2</Box>
<Box>项目3</Box>
</Flex>
// Spacer - 弹性空间
<Flex>
<Box>左侧内容</Box>
<Spacer />
<Box>右侧内容</Box>
</Flex>
// Center - 居中容器
<Center h="200px" bg="gray.100">
<Box>居中内容</Box>
</Center>
// Container - 响应式容器
<Container maxW="container.lg">
固定最大宽度的容器
</Container>
// Stack - 间距布局（垂直/水平）
<Stack direction="row" spacing={4}>
<Box>项目1</Box>
<Box>项目2</Box>
</Stack>
Grid和SimpleGrid：网格布局组件。
import { Grid, GridItem, SimpleGrid } from '@chakra-ui/react'
// Grid - 自定义网格
<Grid templateColumns="repeat(3, 1fr)" gap={6}>
<GridItem bg="blue.500" p={4}>1</GridItem>
<GridItem bg="green.500" p={4}>2</GridItem>
<GridItem bg="red.500" p={4}>3</GridItem>
</Grid>
// SimpleGrid - 响应式网格（推荐）
<SimpleGrid columns={
{ base: 1, sm: 2, md: 3, lg: 4 }} spacing={4}>
{items.map(item => (
<Box key={item.id} p={4} borderWidth="1px" borderRadius="lg">
{item.content}
</Box>
))}
</SimpleGrid>
5.2 数据展示组件
Text和Heading：文本和标题组件。
import { Text, Heading, Highlight, Mark } from '@chakra-ui/react'
// Text - 文本组件
<Text fontSize="lg" fontWeight="medium" color="gray.700">
普通文本
</Text>
// Heading - 标题组件
<Heading as="h1" size="2xl" mb={4}>
一级标题
</Heading>
// Highlight - 高亮文本
<Highlight query={["Chakra", "UI"]} styles={
{ bg: "yellow.200" }}>
Chakra UI是一个优秀的React组件库
</Highlight>
Card组件：内容卡片容器。
import { Card, CardHeader, CardBody, CardFooter, Image, Stack, Heading, Text, Button } from '@chakra-ui/react'
<Card maxW="sm">
<CardBody>
<Image src="image.jpg" alt="卡片图片" borderRadius="lg" />
<Stack mt="6" spacing="3">
<Heading size="md">卡片标题</Heading>
<Text>卡片内容描述，可以包含多行文本。</Text>
</Stack>
</CardBody>
<CardFooter>
<Button variant="solid" colorScheme="blue">
查看详情
</Button>
</CardFooter>
</Card>
5.3 表单组件
Input系列：各种输入组件。
import { Input, Textarea, Select, Checkbox, Radio, Switch, Slider } from '@chakra-ui/react'
// 基础输入框
<Input placeholder="请输入用户名" size="lg" variant="filled" />
// 密码输入框
<Input type="password" placeholder="请输入密码" />
// 文本域
<Textarea placeholder="请输入详细描述" size="sm" resize="vertical" />
// 选择框
<Select placeholder="请选择角色">
<option value="admin">管理员</option>
<option value="user">普通用户</option>
</Select>
// 复选框
<Checkbox size="lg" colorScheme="blue">
同意用户协议
</Checkbox>
// 单选框
<Radio value="option1">选项一</Radio>
// 开关
<Switch size="lg" colorScheme="green" />
// 滑块
<Slider defaultValue={50} min={0} max={100} step={10}>
<SliderTrack bg="red.100">
<SliderFilledTrack bg="tomato" />
</SliderTrack>
<SliderThumb boxSize={6} />
</Slider>
Field组件：表单字段容器，提供标签、帮助文本和错误提示。
import { Field, Input } from '@chakra-ui/react'
<Field.Root>
<Field.Label>邮箱地址</Field.Label>
<Input type="email" placeholder="请输入邮箱" />
<Field.HelpText>我们将不会分享您的邮箱</Field.HelpText>
<Field.ErrorMessage>邮箱格式不正确</Field.ErrorMessage>
</Field.Root>
5.4 反馈组件
Alert：提示框组件。
import { Alert, AlertIcon, AlertTitle, AlertDescription } from '@chakra-ui/react'
<Alert status="success" variant="solid" borderRadius="md">
<AlertIcon />
<AlertTitle>操作成功！</AlertTitle>
<AlertDescription>您的数据已保存</AlertDescription>
</Alert>
Toast：轻提示通知。
import { useToast, Button } from '@chakra-ui/react'
function ToastExample() {
const toast = useToast()
const showToast = () => {
toast({
title: '操作成功',
description: '数据已保存',
status: 'success',
duration: 3000,
isClosable: true,
position: 'top-right',
})
}
return <Button onClick={showToast}>显示提示</Button>
}
Dialog和Drawer：模态框和抽屉组件。
import { Dialog, Drawer, Button } from '@chakra-ui/react'
// Dialog模态框
<Dialog.Root>
<Dialog.Trigger asChild>
<Button>打开模态框</Button>
</Dialog.Trigger>
<Dialog.Content>
<Dialog.Header>对话框标题</Dialog.Header>
<Dialog.Body>这是对话框的内容</Dialog.Body>
<Dialog.Footer>
<Button>取消</Button>
<Button colorScheme="blue">确认</Button>
</Dialog.Footer>
</Dialog.Content>
</Dialog.Root>
5.5 导航组件
Tabs：标签页组件。
import { Tabs } from '@chakra-ui/react'
<Tabs.Root defaultValue="tab1">
<Tabs.List>
<Tabs.Trigger value="tab1">标签页1</Tabs.Trigger>
<Tabs.Trigger value="tab2">标签页2</Tabs.Trigger>
<Tabs.Trigger value="tab3">标签页3</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="tab1">内容1</Tabs.Content>
<Tabs.Content value="tab2">内容2</Tabs.Content>
<Tabs.Content value="tab3">内容3</Tabs.Content>
</Tabs.Root>
5.6 新增组件（v3.x）
Chakra UI v3.x版本引入了多个重要新组件：
Rich Text Editor（富文本编辑器）：基于Tiptap构建的完整富文本编辑器，支持气泡菜单、工具栏、键盘快捷键等。
Date Picker（日期选择器）：支持单日期、日期范围和月份选择。
Marquee（跑马灯）：创建平滑的无限滚动内容展示，适用于客户Logo墙、滚动推荐语等场景。
Action Bar（操作栏）：底部操作栏组件，支持bottom、bottom-start、bottom-end等位置变体。
Carousel（轮播）：用于循环展示一系列视觉内容的轮播组件。
六、性能优化
6.1 按需导入
Chakra UI提供了两种按需导入方式，有效减小打包体积。
方式一：主包按需导入（Tree Shaking）
// ❌ 全量导入（不推荐）
import { Button, Input, Modal } from '@chakra-ui/react'
// ✅ 按需导入（Tree Shaking有效）
import { Button } from '@chakra-ui/react'
import { Input } from '@chakra-ui/react'
import { Modal } from '@chakra-ui/react'
方式二：模块化导入（极致优化）
// ✅ 模块化导入（直接导入组件模块）
import { Button } from '@chakra-ui/react/button'
import { Input } from '@chakra-ui/react/input'
import { Modal } from '@chakra-ui/react/modal'
6.2 模块化Recipe导入
Chakra UI v3中的Recipe（组件配方）默认全部导入，可能导致包体积增大。可以通过创建自定义系统仅导入需要的Recipe：
// ❌ 全量Recipe导入
import { defaultSystem } from '@chakra-ui/react'
// ✅ 按需导入Recipe
import { createSystem, defaultBaseConfig } from '@chakra-ui/react'
import { buttonRecipe, inputRecipe } from '@chakra-ui/react/theme'
const system = createSystem(defaultBaseConfig, {
theme: {
recipes: {
button: buttonRecipe,
input: inputRecipe,
},
},
})
6.3 动态组件导入
对于非首屏组件（如模态框、复杂表单），可以使用React.lazy实现动态导入：
import { Suspense, lazy } from 'react'
const Modal = lazy(() =>
import('@chakra-ui/react/modal').then((mod) => ({
default: mod.Modal,
})),
)
function App() {
return (
<Suspense fallback={<div>Loading...</div>}>
<Modal.Root>...</Modal.Root>
</Suspense>
)
}
6.4 优化效果
通过实施以上优化策略，可以显著减小应用包体积：
建议：在实施优化前后运行npm run build对比包体积，验证优化效果。
七、迁移指南（v2 → v3）
7.1 主要变更
Chakra UI v3引入了多项重大变更，主要包括：
- 组件API重构
v3重构了30+组件的API，包括Accordion、Alert、Button、Dialog、Drawer、Menu、Select、Tabs等。
// v2写法
<Button leftIcon={<Icon />}>按钮</Button>
// v3写法
<Button>
<Icon />
按钮
</Button>
- 主题系统变更
extendTheme替换为新的createSystemAPI。
- Props重命名
colorScheme → colorPalette
forwardRef → 移除（v3组件直接支持ref）
7.2 使用Codemod自动迁移
Chakra UI提供了官方的迁移工具，可一键完成v2到v3的迁移：
npx @chakra-ui/codemod upgrade
Codemod覆盖范围：
组件重命名和API重构
移除的API替换（如useColorMode、forwardRef、StyleConfig等）
Props迁移（colorScheme → colorPalette等）
主题配置转换
TypeScript类型更新
迁移选项：
交互式运行，自动检查git树状态
--dry模式：预览更改而不实际应用
八、最佳实践
8.1 组件组合模式
Chakra UI采用复合组件模式，将复杂组件拆分为多个子组件，提供更大的灵活性。
// 复合组件示例 - Menu
<Menu.Root>
<Menu.Trigger asChild>
<Button>打开菜单</Button>
</Menu.Trigger>
<Menu.Portal>
<Menu.Content>
<Menu.Item value="edit">编辑</Menu.Item>
<Menu.Item value="delete" color="red.500">删除</Menu.Item>
</Menu.Content>
</Menu.Portal>
</Menu.Root>
8.2 自定义组件封装
基于Chakra UI封装业务组件：
import { Button, forwardRef } from '@chakra-ui/react'
// 使用forwardRef传递ref
const CustomButton = forwardRef(({ children, ...props }, ref) => (
<Button ref={ref} colorScheme="brand" size="lg" {...props}>
{children}
</Button>
))
8.3 使用样式属性而非CSS
优先使用Style Props而非编写自定义CSS：
// ✅ 推荐
<Box p={4} bg="blue.500" borderRadius="md" shadow="lg">
// ❌ 不推荐（除非必要）
<Box className="custom-box" />
8.4 TypeScript集成
Chakra UI提供完整的TypeScript类型定义，建议充分利用：
import { Box, BoxProps } from '@chakra-ui/react'
interface CardProps extends BoxProps {
title: string
}
function Card({ title, children, ...props }: CardProps) {
return (
<Box borderWidth="1px" borderRadius="lg" p={4} {...props}>
<Text fontWeight="bold" mb={2}>{title}</Text>
{children}
</Box>
)
}
Chakra UI作为React生态中增长最快的组件库之一，凭借其出色的开发者体验、原生深色模式支持和一流可访问性，已成为现代React应用开发的首选方案。
来源：
https://yyvgt.cn/
