概览

配置 Chakra UI 主题系统的指南。

架构

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

以下是该系统如何构建以提供高性能和可扩展样式系统的快速概览

使用以下函数定义样式系统配置：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>
  )
}

配置

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

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

cssVarsRoot

cssVarsRoot 是应用令牌 CSS 变量的根元素。

theme.ts

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

export default createSystem(defaultConfig, config)

cssVarsPrefix

cssVarsPrefix 是令牌 CSS 变量使用的前缀。

theme.ts

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

export default createSystem(defaultConfig, config)

globalCss

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

theme.ts

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

export default createSystem(defaultConfig, config)

preflight

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

theme.ts

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

export default createSystem(defaultConfig, config)

或者，您可以使用 preflight 配置属性向系统应用 CSS 重置样式。如果您想将 CSS 重置样式应用于特定元素，这将很有用。

theme.ts

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

export default createSystem(defaultConfig, config)

theme

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

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 配置属性定义系统要使用的自定义选择器和媒体查询条件。

theme.ts

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

export default createSystem(defaultConfig, config)

用法示例

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

strictTokens

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

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 可用于为其生成类型定义。

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

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

系统

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

const system = createSystem(defaultConfig, config)

该系统包含以下属性：

token

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

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 变量

// 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)"

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

// 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 或任何其他样式库。

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，会返回一个样式对象。

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，会为每个插槽返回一个样式对象。

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 函数用于检查属性是否有效。

const system = createSystem(defaultConfig, config)

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

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

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

splitCssProps

splitCssProps 函数用于将 props 分割为 CSS props 和非 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 属性用于查询断点。

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"]

令牌

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

配方

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

排版

令牌

概览

.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;}架构

架构