升级至 v1

Chakra UI v1.0 专注于改进 v0.8 中的思想和概念，使创建、主题化和扩展组件变得更加简便。

尽管我们添加了相当多的新功能，但我们的重点是使 Chakra UI 成为一个稳定的基础，以构建您自己的设计系统。最终，我们希望让您在生产环境中更加自信地使用 Chakra UI。

亮点

主题化 API：Chakra UI 现在提供了一个新的主题化 API，使得从主题中轻松样式化组件及其修饰符（大小、变体和颜色方案）变得更加简便。

颜色模式改进：我们修复了与颜色模式相关的错误，并使持久化颜色模式、设置初始颜色模式以及将特定组件锁定到特定颜色模式成为可能。

更好的 TypeScript 支持：这意味着所有组件都具有非常好的 TypeScript 支持，大多数低级组件（如 Box、Flex）将支持 as 属性，并能够正确提取类型。

主题感知的 sx 属性：与 theme-ui 类似，我们添加了对 sx 属性的支持，以帮助您直接在任何 Chakra 组件上添加主题感知的样式。如果您不喜欢样式属性，而更喜欢将所有样式传递给一个对象，则这是非常有用的。

废弃 PseudoBox：我们移除了 PseudoBox，并将其所有属性与 Box 合并，这样您就可以在任何 Chakra 组件中使用伪样式属性，如 _hover、_active。

不再支持 IE11：我们不再支持 IE11 的原因。

升级步骤

以下是将您的项目迁移到 v1 的步骤列表。如果您的样式不完全相同，不用担心，这是可以预期的，按照这些步骤操作将会修复它。

1. 更新依赖项

  • 安装 framer-motion 包。我们使用它来管理组件内的动画和过渡效果。
  • 移除 emotion-theming 包。由于在 emotion v11 中，emotion-theming 已被移除，并且所有功能已迁移到 @emotion/react。
  • 将 @emotion/core 包重命名为 @emotion/react。@emotion/core 最近在 emotionjs 团队发布 v11 版本后更名为 @emotion/react。
  • 将 @chakra-ui/core 包重命名为 @chakra-ui/react。
  • 将 @emotion/styled 包更新至 v11。
  1. "dependencies": {
  2. - "@chakra-ui/core": "^0.8.0",
  3. + "@chakra-ui/react": "^1.0.0",
  4.   "framer-motion": "^4.0.0",
  5. - "@emotion/core": "^10.0.10",
  6. + "@emotion/react": "^11.0.0",
  7.   "@emotion/styled": "^11.0.0",
  8. - "emotion-theming": "10.0.10"
  9. }

请注意，在 TypeScript 项目中使用 Chakra UI 时，需要至少 TypeScript 版本 4.1.0。

关于图标的注意事项

Chakra 将所有图标移动到一个单独的包 @chakra-ui/icons 中。我们建议在您的项目中使用 react-icons，因为它具有强大的图标集。然而，您仍然可以安装 @chakra-ui/icons 这个包。

2. 更新 ThemeProvider

将 ThemeProvider 替换为 ChakraProvider 以使设置更清晰。ChakraProvider 会自动为您添加以下提供者：

  • ThemeProvider：为所有组件提供主题上下文。
  • ColorModeProvider：为所有组件提供颜色模式（明亮或暗黑）上下文。
  • GlobalStyle：将主题中定义的全局样式应用到您的应用程序中。

可选地通过属性：

  • CSSReset：要省略建议的 CSSReset，传递 resetCSS={false}。
  • PortalManager：在应用程序中管理 portals 和嵌套 portals，而无需使用 z-index。传递 portalZIndex 属性。
  1. -  <ThemeProvider>
  2. +    <ChakraProvider>
  3. -     <CSSReset />
  4.       <App />
  5. +    </ChakraProvider>
  6. -  </ThemeProvider>

3. 将 variantColor 重命名为 colorScheme

在您的 VSCode 或 IntelliJ 中启动 “查找和替换” 工具。查找 variantColor 并替换为 colorScheme。

原因：我们将这个属性重命名为 colorScheme，以使人们更容易理解这个属性代表的是一种视觉颜色方案，而不是 CSS 颜色属性。

4. 更新布局大小属性

将 size 属性更改为 width 或 w 以及 height 或 h。如果您希望只使用一个属性来管理这些，可以将其重命名为 boxSize。

  1. - <Box size="40px" />
  2. + <Box w="40px" h="40px" />
  3. # or
  4. + <Box boxSize="40px" />