我们最近发布了 Chakra UI v3 版本，带来了大量的改动、改进和新功能。

面对如此重大的更新，你可能想知道，到底有哪些变化？新功能是什么？以及迁移是否真的值得？

在本文中，我们将深入探讨版本 2 和版本 3 之间的关键区别。目的是帮助你更好地理解版本 3，并决定是否是时候迁移你的项目了。

简化安装

安装过程是首批显著差异之一。以前，你必须安装多个包才能在你的项目中启用 Chakra。

• @chakra-ui/react
• @emotion/react
• @emotion/styled
• framer-motion

但现在有了v3，事情变得简单多了。你只需要

• @chakra-ui/react
• @emotion/react

这减少了依赖项的数量，并带来了更快的设置。

版本 2

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

版本 3

npm install @chakra-ui/react @emotion/react

新的 Provider 设置

在之前的版本中，你必须使用 ChakraProvider 包裹你的应用程序，以访问 Chakra 的默认主题。然而，我们现在已经用 Provider 组件取代了 ChakraProvider。

Provider 包含以下组件：

• 用于样式系统的 ChakraProvider from @chakra-ui/react
• 用于颜色模式的 ThemeProvider from next-themes

版本 2

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

function App() {
  return <ChakraProvider>{/* the rest of your app */}</ChakraProvider>
}

版本 3

import { Provider } from "@/components/ui/provider"

function App() {
  return <Provider>{/* the rest of your app */}</Provider>
}

组件代码片段

开发者常见的一个痛点是重复构建常用 UI 组件。为了解决这个问题，我们引入了组件代码片段（Component Snippets）。

代码片段是预构建组件，旨在加速你的开发过程。

通过新的 Chakra CLI，你只需一个命令即可将预制组件即时添加到你的项目中。

# Add all snippets
chakra snippet add

# Add a specific snippet
chakra snippet add button

运行命令后，你会在 src 目录下的 /components/ui 文件夹中找到组织整齐的组件。

然后你可以直接从 components 文件夹导入你想要的组件代码片段

import { Button } from "@/components/ui/button"

新组件

我们倾听了社区的声音，在此版本中，我们添加了 25+ 个新组件，以提升你的开发工作流程。

部分新组件包括：

• 文件上传
• 剪贴板
• 时间线
• 密码输入
• 分段控制器
• 切换提示
• 自定义选择器
• 以及更多

在此处查看所有组件。每个新组件都秉承了 Chakra UI 一贯的对可访问性和设计一致性的关注。

引入状态机

此版本中最大的更新之一是逻辑组件采用了状态机。Chakra UI v3 现在使用 Ark UI 作为这些组件的基础。

状态机为 Chakra UI 组件带来了新的稳定性水平，特别是对于需要复杂交互式用户界面的应用程序。

虽然这不是用户会直接交互的内容，但重要的是要知道，底层使用状态机显著提高了模态框、菜单、弹出框等复杂 UI 元素的性能。

现在，你可以期待 Chakra UI 组件之间更一致的行为。

精简组件导入

在之前的版本中，你必须将多个组件和组件部分导入到你的项目中。

例如，你必须手动单独导入 List 和 ListItem

版本 2

import { List, ListItem } from "@chakra-ui/react"

function App() {
  return (
    <List>
      <ListItem>Item 1</ListItem>
    </List>
  )
}

版本 3 提供了一个更具内聚性的 API，将相关组件整合在一起。我们引入了一种更有序的组件导入方法，减少了多重导入的需要，并使你的代码库更易于维护。

版本 3

import { List } from "@chakra-ui/react"

function App() {
  return (
    <List.Root>
      <List.Item>Item 1</List.Item>
    </List.Root>
  )
}

现在，你只需导入 List 并使用对象表示法来组合其他组件。

这种将主组件嵌套在“Root”主容器下，以及将相关子组件嵌套在主容器下的模式，简化了 Chakra 的 API 并使你的导入更加整洁。

增强主题设置

我们重新构想了主题设置，以实现更好的模块化。在之前的版本中，主题通常使用 extendTheme 函数进行扩展

版本 2

const theme = extendTheme({
  colors: {
    brand: {
      100: "#f7fafc",
      900: "#1a202c",
    },
  },
})

在 v3 中，新方法利用 createSystem 函数，其中令牌在你的系统配置中的 theme 键下定义。

版本 3

import { createSystem } from "@chakra-ui/react"

export const system = createSystem(defaultConfig, {
  theme: {
    tokens: {
      fonts: {
        heading: { value: `'Figtree', sans-serif` },
        body: { value: `'Figtree', sans-serif` },
      },
    },
  },
})

这种新设置使定制和扩展你的设计系统变得更加容易。

增强设计令牌

在版本 3 中，我们还更新了设计令牌。你会注意到以下变化：

• 颜色：调色板已扩展并经过精细调整，以提高活力和多功能性。这确保了你的设计更具视觉吸引力且更易于访问。
• 动画：我们增加了对使用原生 CSS 实现动画的支持，使你的应用程序性能更佳。
• 设计令牌：改进了更强大的令牌，以实现更好的设计一致性。
• 引入语义令牌：我们添加了内置的语义令牌，以便更轻松地将你的设计系统映射到浅色和深色模式。

更新的 Props

Props 在此版本中也进行了重大更新。一个很好的例子是 gap prop，它现在取代了 Stack 和类似组件的 spacing prop。

版本 2

<Stack spacing={4}>
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</Stack>

版本 3

<Stack gap={4}>
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</Stack>

这一更改更符合现代 CSS 实践，并有助于开发者更有效地管理间距，尤其是在 flex 和 grid 布局中。

不仅如此，在 v2 中，布尔类型 props 通常以 is 作为前缀，例如 isDisabled。在 v3 中，通过移除 is 前缀，这已被简化。

版本 2

<Button isDisabled>Click Me</Button>

版本 3

<Button disabled>Click Me</Button>

这一更改使 prop 名称更直观、易读，并与标准 HTML 实践保持一致。

我们告别了 chakra-icons

为了追求简洁，v3 已移除了 chakra-icons 包。相反，我们鼓励开发者使用 lucide-react 或 react-icons 等库来满足他们的图标需求。

这一转变减少了依赖项冗余，并允许你利用 React 生态系统中更广泛的图标选项。

使用 Chakra v3，更快上手

如果你目前正在使用 Chakra UI v2，现在是考虑迁移到版本 3 的绝佳时机。

新功能，例如组件代码片段、增强的设计令牌以及状态机驱动的组件，旨在简化你的开发过程并提升你的整体开发体验。

试用 Chakra v3，并告诉我们你的想法。