概述

Chakra UI 主题系统配置指南。

架构

¥Architecture

Chakra UI 主题系统基于 Panda CSS 的 API 构建。

¥The Chakra UI theming system is built around the API of Panda CSS.

以下是系统如何构建以提供高性能和可扩展的样式系统的简要概述：

¥Here's a quick overview of how the system is structured to provide a performant and extensible styling system:

使用 defineConfig 函数定义样式系统配置
使用 createSystem 函数创建样式引擎
将样式引擎传递给 ChakraProvider 组件

import {
  ChakraProvider,
  createSystem,
  defaultConfig,
  defineConfig,
} from "@chakra-ui/react"

const config = defineConfig({
  theme: {
    tokens: {
      colors: {},
    },
  },
})

const system = createSystem(defaultConfig, config)

export default function App() {
  return (
    <ChakraProvider value={system}>
      <Box>Hello World</Box>
    </ChakraProvider>
  )
}

配置

¥Config

Chakra UI 系统使用 defineConfig 函数进行配置。此函数接受一个配置对象，允许你自定义样式系统的行为。

¥The Chakra UI system is configured using the defineConfig function. This function accepts a configuration object that allows you to customize the styling system's behavior.

定义配置后，它将被传递给 createSystem 函数以创建样式引擎。

¥After a config is defined, it is passed to the createSystem function to create the styling engine.

cssVarsRoot

cssVarsRoot 是将应用 token CSS 变量的根元素。

¥cssVarsRoot is the root element where the token CSS variables will be applied.

theme.ts

const config = defineConfig({
  cssVarsRoot: ":where(:root, :host)",
})

export default createSystem(defaultConfig, config)

cssVarsPrefix

cssVarsPrefix 是用于 token CSS 变量的前缀。

¥cssVarsPrefix is the prefix used for the token CSS variables.

theme.ts

const config = defineConfig({
  cssVarsPrefix: "ck",
})

export default createSystem(defaultConfig, config)

globalCss

globalCss 用于将全局样式应用于系统。

¥globalCss is used to apply global styles to the system.

theme.ts

const config = defineConfig({
  globalCss: {
    "html, body": {
      margin: 0,
      padding: 0,
    },
  },
})

export default createSystem(defaultConfig, config)

preflight

preflight 用于将 CSS 重置样式应用于系统。

¥preflight is used to apply css reset styles to the system.

theme.ts

const config = defineConfig({
  preflight: false,
})

export default createSystem(defaultConfig, config)

或者，你可以使用 preflight 配置属性将 CSS 重置样式应用于系统。如果你想将 CSS 重置样式应用于特定元素，此功能非常有用。

¥Alternatively, you can use the preflight config property to apply css reset styles to the system. This is useful if you want to apply css reset styles to a specific element.

theme.ts

const config = defineConfig({
  preflight: {
    scope: ".chakra-reset",
  },
})

export default createSystem(defaultConfig, config)

theme

使用 theme 配置属性定义系统主题。此属性接受以下属性：

¥Use the theme config property to define the system theme. This property accepts the following properties:

breakpoints：用于定义断点
keyframes：用于定义 CSS 关键帧动画
tokens：用于定义标记
semanticTokens：用于定义语义标记
textStyles：用于定义排版样式
layerStyles：用于定义图层样式
animationStyles：用于定义动画样式
recipes：用于定义组件配方
slotRecipes：用于定义组件插槽配方

theme.ts

const config = defineConfig({
  theme: {
    breakpoints: {
      sm: "320px",
      md: "768px",
      lg: "960px",
      xl: "1200px",
    },
    tokens: {
      colors: {
        red: "#EE0F0F",
      },
    },
    semanticTokens: {
      colors: {
        danger: { value: "{colors.red}" },
      },
    },
    keyframes: {
      spin: {
        from: { transform: "rotate(0deg)" },
        to: { transform: "rotate(360deg)" },
      },
    },
  },
})

export default createSystem(defaultConfig, config)

conditions

使用 conditions 配置属性定义自定义选择器和媒体查询条件，以供系统使用。

¥Use the conditions config property to define custom selectors and media query conditions for use in the system.

theme.ts

const config = defineConfig({
  conditions: {
    cqSm: "@container(min-width: 320px)",
    child: "& > *",
  },
})

export default createSystem(defaultConfig, config)

示例用法：

¥Sample usage:

<Box mt="40px" _cqSm={{ mt: "0px" }}>
  <Text>Hello World</Text>
</Box>

strictTokens

使用 strictTokens 配置属性强制仅使用设计令牌。如果你尝试使用主题中未定义的令牌，这将引发 TS 错误。

¥Use the strictTokens config property to enforce the usage of only design tokens. This will throw a TS error if you try to use a token that is not defined in the theme.

theme.ts

const config = defineConfig({
  strictTokens: true,
})

export default createSystem(defaultConfig, config)

// ❌ This will throw a TS error
<Box color="#4f343e">Hello World</Box>

// ✅ This will work
<Box color="red.400">Hello World</Box>

TypeScript

配置系统属性（例如 colors、space、fonts 等）时，可以使用 CLI 为其生成类型定义。

¥When you configure the system properties (like colors, space, fonts, etc.), the CLI can be used to generate type definitions for them.

npx @chakra-ui/cli typegen ./theme.ts

这将更新 @chakra-ui/react 包中的内部类型，并确保它们与主题同步。为开发者提供类型安全的 API 和愉悦的体验。

¥This will update the internal types in the @chakra-ui/react package, and make sure they are in sync with the theme. Providing a type-safe API and delightful experience for developers.

系统

¥System

定义配置后，它将被传递给 createSystem 函数以创建样式引擎。返回的 system 是一个与框架无关的 JavaScript 样式引擎，可用于设置组件的样式。

¥After a config is defined, it is passed to the createSystem function to create the styling engine. The returned system is framework-agnostic JavaScript styling engine that can be used to style components.

const system = createSystem(defaultConfig, config)

系统包含以下属性：

¥The system includes the following properties:

token

token 函数用于获取原始 token 值或 CSS 变量。

¥The token function is used to get a raw token value, or css variable.

const system = createSystem(defaultConfig, config)

// raw token
system.token("colors.red.200")
// => "#EE0F0F"

// token with fallback
system.token("colors.pink.240", "#000")
// => "#000"

使用 token.var 函数获取 css 变量：

¥Use the token.var function to get the css variable:

// css variable
system.token.var("colors.red.200")
// => "var(--chakra-colors-red-200)"

// token with fallback
system.token.var("colors.pink.240", "colors.red.200")
// => "var(--chakra-colors-red-200)"

需要注意的是，无论你使用 token 还是 token.var，semanticTokens 始终返回一个 CSS 变量。这是因为语义 token 会根据主题而变化。

¥It's important to note that semanticTokens always return a css variable, regardless of whether you use token or token.var. This is because semantic tokens change based on the theme.

// semantic token
system.token("colors.danger")
// => "var(--chakra-colors-danger)"

system.token.var("colors.danger")
// => "var(--chakra-colors-danger)"

tokens

const system = createSystem(defaultConfig, config)

system.tokens.getVar("colors.red.200")
// => "var(--chakra-colors-red-200)"

system.tokens.expandReferenceInValue("3px solid {colors.red.200}")
// => "3px solid var(--chakra-colors-red-200)"

system.tokens.cssVarMap
// => Map { "colors": Map { "red.200": "var(--chakra-colors-red-200)" } }

system.tokens.flatMap
// => Map { "colors.red.200": "var(--chakra-colors-red-200)" }

css

css 函数用于将 Chakra 样式对象转换为 CSS 样式对象，该对象可以传递给 emotion、styled-components 或任何其他样式库。

¥The css function is used to convert chakra style objects to CSS style object that can be passed to emotion or styled-components or any other styling library.

const system = createSystem(defaultConfig, config)

system.css({
  color: "red.200",
  bg: "blue.200",
})

// => { color: "var(--chakra-colors-red-200)", background: "var(--chakra-colors-blue-200)" }

cva

cva 函数用于创建组件配方。它会返回一个函数，当使用一组 props 调用该函数时，会返回一个样式对象。

¥The cva function is used to create component recipes. It returns a function that, when called with a set of props, returns a style object.

const system = createSystem(defaultConfig, config)

const button = system.cva({
  base: {
    color: "white",
    bg: "blue.500",
  },
  variants: {
    outline: {
      color: "blue.500",
      bg: "transparent",
      border: "1px solid",
    },
  },
})

button({ variant: "outline" })
// => { color: "blue.500", bg: "transparent", border: "1px solid" }

sva

sva 函数用于创建组件插槽配方。它会返回一个函数，当使用一组 props 调用该函数时，会为每个 slot 返回一个样式对象。

¥The sva function is used to create component slot recipes. It returns a function that, when called with a set of props, returns a style object for each slot.

const system = createSystem(defaultConfig, config)

const alert = system.sva({
  slots: ["title", "description", "icon"],
  base: {
    title: { color: "white" },
    description: { color: "white" },
    icon: { color: "white" },
  },
  variants: {
    status: {
      info: {
        title: { color: "blue.500" },
        description: { color: "blue.500" },
        icon: { color: "blue.500" },
      },
    },
  },
})

alert({ status: "info" })
// => { title: { color: "blue.500" }, description: { color: "blue.500" }, icon: { color: "blue.500" } }

isValidProperty

isValidProperty 函数用于检查属性是否有效。

¥The isValidProperty function is used to check if a property is valid.

const system = createSystem(defaultConfig, config)

system.isValidProperty("color")
// => true

system.isValidProperty("background")
// => true

system.isValidProperty("invalid")
// => false

splitCssProps

splitCssProps 函数用于将属性拆分为 CSS 属性和非 CSS 属性。

¥The splitCssProps function is used to split the props into css props and non-css props.

const system = createSystem(defaultConfig, config)

system.splitCssProps({
  color: "red.200",
  bg: "blue.200",
  "aria-label": "Hello World",
})
// => [{ color: "red.200", bg: "blue.200" }, { "aria-label": "Hello World" }]

breakpoints

breakpoints 属性用于查询断点。

¥The breakpoints property is used to query breakpoints.

const system = createSystem(defaultConfig, config)

system.breakpoints.up("sm")
// => "@media (min-width: 320px)"

system.breakpoints.down("sm")
// => "@media (max-width: 319px)"

system.breakpoints.only("md")
// => "@media (min-width: 320px) and (max-width: 768px)"

system.breakpoints.keys()
// => ["sm", "md", "lg", "xl"]

令牌

¥Tokens

要了解有关令牌的更多信息，请参阅 tokens 部分。

¥To learn more about tokens, please refer to the tokens section.

秘诀

¥Recipes

要了解有关配方的更多信息，请参阅 recipes 部分。

¥To learn more about recipes, please refer to the recipes section.

排版

令牌

概述

.css-vfo6uh{color:var(--chakra-colors-fg);-webkit-text-decoration:underline;text-decoration:underline;text-underline-offset:3px;text-decoration-thickness:2px;text-decoration-color:var(--chakra-colors-border-emphasized);font-weight:500;}架构

架构