Chakra UI 安装配置 #

安装要求 #

在安装 Chakra UI 之前，请确保你的开发环境满足以下要求：

要求	版本
Node.js	>= 14.x
React	>= 18.x
npm/yarn/pnpm	最新稳定版

方式一：创建新项目（推荐） #

使用 Vite 创建项目 #

bash

# 创建项目
npm create vite@latest my-app -- --template react-ts

# 进入项目目录
cd my-app

# 安装依赖
npm install

# 安装 Chakra UI
npm i @chakra-ui/react @emotion/react @emotion/styled framer-motion

使用 Create React App #

bash

# 创建项目
npx create-react-app my-app --template typescript

# 进入项目目录
cd my-app

# 安装 Chakra UI
npm i @chakra-ui/react @emotion/react @emotion/styled framer-motion

方式二：现有项目安装 #

安装核心依赖 #

bash

# 使用 npm
npm install @chakra-ui/react @emotion/react @emotion/styled framer-motion

# 使用 yarn
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion

# 使用 pnpm
pnpm add @chakra-ui/react @emotion/react @emotion/styled framer-motion

依赖说明 #

包名	说明
`@chakra-ui/react`	Chakra UI 核心组件库
`@emotion/react`	CSS-in-JS 引擎
`@emotion/styled`	样式化组件支持
`framer-motion`	动画库

配置 Provider #

安装完成后，需要在应用根组件包裹 ChakraProvider：

基本配置 #

jsx

import { ChakraProvider } from '@chakra-ui/react'

function App() {
  return (
    <ChakraProvider>
      <App />
    </ChakraProvider>
  )
}

export default App

TypeScript 配置 #

tsx

import { ChakraProvider } from '@chakra-ui/react'

function App(): JSX.Element {
  return (
    <ChakraProvider>
      <App />
    </ChakraProvider>
  )
}

export default App

Next.js 集成 #

安装依赖 #

bash

npx create-next-app@latest my-app --typescript
cd my-app
npm i @chakra-ui/react @emotion/react @emotion/styled framer-motion

配置 Provider #

创建 providers.tsx 文件：

tsx

'use client'

import { ChakraProvider } from '@chakra-ui/react'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ChakraProvider>
      {children}
    </ChakraProvider>
  )
}

在 layout.tsx 中使用：

tsx

import { Providers } from './providers'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

App Router 配置 #

tsx

import { ChakraProvider } from '@chakra-ui/react'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <ChakraProvider>
          {children}
        </ChakraProvider>
      </body>
    </html>
  )
}

自定义主题配置 #

创建主题文件 #

jsx

import { extendTheme } from '@chakra-ui/react'

const theme = extendTheme({
  colors: {
    brand: {
      50: '#e3f2fd',
      100: '#bbdefb',
      200: '#90caf9',
      300: '#64b5f6',
      400: '#42a5f5',
      500: '#2196f3',
      600: '#1e88e5',
      700: '#1976d2',
      800: '#1565c0',
      900: '#0d47a1',
    },
  },
  fonts: {
    heading: `'Heading Font', sans-serif`,
    body: `'Body Font', sans-serif`,
  },
  styles: {
    global: {
      body: {
        bg: 'gray.50',
      },
    },
  },
})

export default theme

应用主题 #

jsx

import { ChakraProvider } from '@chakra-ui/react'
import theme from './theme'

function App() {
  return (
    <ChakraProvider theme={theme}>
      <App />
    </ChakraProvider>
  )
}

安装图标库（可选） #

bash

npm install react-icons

使用图标：

jsx

import { Button } from '@chakra-ui/react'
import { EmailIcon, ArrowForwardIcon } from '@chakra-ui/icons'

function App() {
  return (
    <>
      <Button leftIcon={<EmailIcon />}>Email</Button>
      <Button rightIcon={<ArrowForwardIcon />}>Continue</Button>
    </>
  )
}

项目结构建议 #

text

my-app/
├── src/
│   ├── components/
│   │   └── Header.tsx
│   ├── theme/
│   │   ├── index.ts
│   │   ├── colors.ts
│   │   └── components.ts
│   ├── pages/
│   │   └── Home.tsx
│   ├── App.tsx
│   └── main.tsx
├── package.json
└── tsconfig.json

验证安装 #

创建一个简单的组件验证安装是否成功：

jsx

import {
  Box,
  Button,
  Flex,
  Heading,
  Text,
  VStack,
} from '@chakra-ui/react'

function App() {
  return (
    <Box p={8}>
      <VStack spacing={4}>
        <Heading>Chakra UI 安装成功!</Heading>
        <Text>欢迎使用 Chakra UI</Text>
        <Flex gap={4}>
          <Button colorScheme="blue">Primary</Button>
          <Button colorScheme="green">Success</Button>
          <Button colorScheme="red">Danger</Button>
        </Flex>
      </VStack>
    </Box>
  )
}

export default App

常见问题 #

1. 样式不生效 #

确保正确包裹了 ChakraProvider：

jsx

import { ChakraProvider } from '@chakra-ui/react'

function App() {
  return (
    <ChakraProvider>
      {/* 你的组件 */}
    </ChakraProvider>
  )
}

2. TypeScript 类型错误 #

确保安装了正确的类型定义：

bash

npm install --save-dev @types/react @types/react-dom

3. 服务器端渲染问题 #

Next.js 项目确保使用 'use client' 指令：

tsx

'use client'

import { ChakraProvider } from '@chakra-ui/react'

4. 版本兼容问题 #

确保所有依赖版本兼容：

json

{
  "dependencies": {
    "@chakra-ui/react": "^2.8.0",
    "@emotion/react": "^11.11.0",
    "@emotion/styled": "^11.11.0",
    "framer-motion": "^10.16.0",
    "react": "^18.2.0"
  }
}

开发工具配置 #

VS Code 插件推荐 #

插件	说明
Chakra UI Snippets	代码片段
ES7+ React Snippets	React 代码片段
Prettier	代码格式化
ESLint	代码检查

ESLint 配置 #

json

{
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    "react/react-in-jsx-scope": "off"
  }
}

下一步 #

安装完成后，接下来学习第一个应用，开始构建你的第一个 Chakra UI 应用！