sx 属性

sx 属性是一种用于定义可访问主题的自定义样式的快捷方式。

sx 属性提供一个 CSS 超集，除包含所有 CSS 属性和选择器之外，还有 Nex UI 内置的自定义属性和选择器，而 CSS 属性值可以直接使用预定义的主题。如果您不满足于已有的 CSS 自定义属性和选择器以及主题，Nex UI 还提供了扩展能力，在定制主题了解更多信息。

使用 `sx` 属性

下面的例子演示了如何使用 sx 属性。注意，并不是所有的值都是有效的 CSS 属性，这是因为 sx 的键映射到了特定的 Token 类型。接下来将更详细地介绍这个概念。

Nex UI

nexui.dev

Make beautiful websites with ease and efficiency.

Visit source code on GitHub.


import { Box } from '@nex-ui/react'
 
export default function Example() {
  return (
    <Box
      sx={{
        'max-width': 390,
        borderRadius: 'lg',
        boxShadow: 'lg',
      }}
    >
      <Box sx={{ display: 'flex', gap: '3', alignItems: 'center', p: '3' }}>
        <Box as='img' src={logo.src} width={50} height={50} />
        <Box>
          <Box>Nex UI</Box>
          <Box
            sx={{
              fs: 'md',
              color: 'rgb(113, 113, 122)',
            }}
          >
            nexui.dev
          </Box>
        </Box>
      </Box>
      <Box as='hr' sx={{ m: 0, border: 'none', bg: 'gray.200', height: 1 }} />
      <Box sx={{ p: '3' }}>
        Make beautiful websites with ease and efficiency.
      </Box>
      <Box as='hr' sx={{ m: 0, border: 'none', bg: 'gray.200', height: 1 }} />
      <Box
        sx={{
          p: '3',
          display: 'inline-block',
          textDecoration: 'none',
          color: 'blue.600',
        }}
        as='a'
        href='github.com'
      >
        Visit source code on GitHub.
      </Box>
    </Box>
  )
}

具备主题感知能力的属性

通过 Scales 可将 Tokens、SemanticTokens 与 CSS 属性关联，使得 CSS 属性能够映射到相应的 Token 类型，进而允许 CSS 属性能够使用相应类型的 Tokens 作为值。


import { Box, defineTheme, NexUIProvider } from '@nex-ui/react'
 
const theme = defineTheme({
  tokens: {
    colors: {
      primary: 'blue',
    },
    sizes: {
      1: '10px',
    },
  },
  scales: {
    color: 'colors',
    width: 'sizes',
    height: 'sizes',
  },
})
 
export default function Example() {
  return (
    <NexUIProvider theme={theme}>
      <Box
        sx={{
          // 只有在 scales 中定义 color: 'colors', color 才可以使用 tokens.colors.primary
          color: 'primary',
          // 此时 width 属性值会被编译为 tokens.sizes.1,
          width: '1',
          // 当值仅为 string 时才可能映射到 tokens, 此时 width 为 1px
          height: 1,
        }}
      />
    </NexUIProvider>
  )
}

注意，CSS 属性值仅为 string 时才可能映射到 tokens。

上述示例中， width 实际为 10px，而 height 实际为 1px。

在 Scales 了解更多的信息。

Colors

color 和 backgroundColor 等属性可以接收 tokens.colors 和 semanticTokens.colors 中的路径：


<Box sx={{ color: 'blue.400' }} />

backgroundColor 属性还可以通过别名 bg 访问：


<Box sx={{ bg: 'blue.400' }} />

在 Colors 了解更多的信息。

Borders

borderWidth 属性可以接收 tokens.borders 和 semanticTokens.borders 中的路径：


<Box sx={{ border: 'sm', borderColor: 'blue.500' }} />

在 Borders 了解更多的信息。

Sizes

width 和 height 等属性可以接收 tokens.sizes 和 semanticTokens.sizes 中的路径：


<Box sx={{ width: '2', height: '1' }} />

width 和 height 还可以分别通过别名 w 和 h 访问：


<Box sx={{ w: '2', h: '1' }} />

在 Sizes 了解更多的信息。

Spaces

padding 和 margin 等属性可以接收 tokens.spaces 和 semanticTokens.spaces 中的路径：


<Box sx={{ padding: '1', margin: '1' }} />

padding 和 margin 还可以分别通过别名 p 和 m 访问：


<Box sx={{ p: '1', m: '1' }} />

在 Spaces 了解更多的信息。

Radii

borderRadius 属性可以接收 tokens.radii 和 semanticTokens.radii 中的路径：


<Box sx={{ borderRadius: 'sm' }} />

在 Radii 了解更多的信息。

Typography

fontWeight 属性可以接收 tokens.fontWeights 和 semanticTokens.fontWeights 中的路径：


<Box sx={{ fontWeight: 'medium' }} />

fontSize 属性可以接收 tokens.fontSizes 和 semanticTokens.fontSizes 中的路径：


<Box sx={{ fontSize: 'lg' }} />

fontFamily 属性可以接收 tokens.fontFamilies 和 semanticTokens.fontFamilies 中的路径：


<Box sx={{ fontFamily: 'heading' }} />

lineHeight 属性可以接收 tokens.lineHeights 和 semanticTokens.lineHeights 中的路径：


<Box sx={{ lineHeight: 'base' }} />

在 Typography 了解更多的信息。

BorderWidths

borderWidth 属性可以接收 tokens.borderWidths 和 semanticTokens.borderWidths 中的路径：


<Box sx={{ borderWidth: 'sm' }} />

在 BorderWidths 了解更多的信息。

Shadows

boxShadow 属性可以接收 tokens.shadows 和 semanticTokens.shadows 中的路径：


<Box sx={{ boxShadow: 'sm' }} />

在 Shadows 了解更多的信息。

Transitions

transition 属性可以接收 tokens.transitions 和 semanticTokens.transitions 中的路径：


<Box sx={{ transition: 'all' }} />

在 Transitions 了解更多的信息。

Z-Indices

zIndex 属性可以接收 tokens.zIndices 和 semanticTokens.zIndices 中的路径：


<Box sx={{ zIndex: 'min' }} />

在 Z-Indices 了解更多的信息。

响应式值

与 sx 属性相关的所有 CSS 属性也都支持针对特定断点的响应式值，sx 属性可以简化定义和实现响应式断点的过程。

在响应式设计了解更多信息。

深色模式

与 sx 属性相关的所有 CSS 属性也都支持深色模式。sx 属性搭配 Nex UI 提供的 Color Mode 系统，只需使用 _dark 即可为组件设置深色模式的样式，_light 为组件设置浅色模式的样式。_DEFAULT为组件的默认样式。

下面的例子演示了如何对不同模式下的组件设置相应的样式：

Color Mode


<Box
  sx={{
    bg: {
      _dark: 'white',
      _light: '#27272a',
      _DEFAULT: '#27272a',
    },
    color: {
      _dark: '#27272a',
      _light: 'white',
      _DEFAULT: 'white',
    },
    width: 300,
    textAlign: 'center',
  }}
>
  深色模式
</Box>

在深色模式了解更多信息。

ColorPalette 属性

colorPalette 属性可以创建一个颜色占位符，以便更好地进行主题设置和自定义。使用 colorPalette 的基本要求是，使用的颜色必须有一致的命名规范。默认情况下，Nex UI 会为每种颜色提供 50 到 900 的颜色值。这会让你更容易创建和使用 colorPalette。

假设我们需要从头开始创建一个可应用主题样式的按钮。

Hello World


<Box
  sx={{
    colorPalette: 'blue',
    bg: {
      _DEFAULT: 'colorPalette.500',
      _hover: 'colorPalette.400',
      _active: 'colorPalette.600',
    },
    p: '5px 15px',
    color: '#fff',
    borderRadius: 'md',
    textAlign: 'center',
  }}
>
  Hello World
</Box>

Token 引用语法

通常情况下，只有在 scales 中定义 CSS 属性与 Token 类型之间的映射关系才可以在定义 CSS 时引用相应类型的 Tokens。Nex UI 默认设置 Scales：


{
  color: 'colors',
  backgroundColor: 'colors',
  ...
}

因此在 sx 属性中可使用：


<Box
  sx={{
    color: 'gray.100',
    bg: 'blue.500',
  }}
>
  Box
</Box>

然而，在诸如 border、padding 这类特殊的简写 CSS 属性中，无法通过上述方式引用 Tokens。为此 Nex UI 提供了 Token 引用语法，使得您可以在简写属性中引用 Tokens：


<Box
  sx={{
    border: '{borderWidths.sm} solid {colors.blue.500}',
  }}
>
  Box
</Box>

不仅如此，您还可以在 Token 引用语法使用 colorPalette ：


<Box
  sx={{
    border: '{borderWidths.sm} solid {colors.colorPalette.500}',
    colorPalette: 'blue',
  }}
>
  Box
</Box>

此时，border 将应用borderWidths.sm 和 colors.colorPalette.500 对应的值。

Color Opacity 修饰符

当在 scales 中将 CSS 属性定义为 colors 类型时，无论是直接使用颜色值，还是引用 ColorToken，均可通过 opacity 修饰符灵活设置颜色透明度。这一特性同样适用于 Token 引用语法，在引用 ColorToken 时也能便捷地运用 opacity 修饰符，实现多样化的视觉效果调整。

例如 color: 'blue.500/50' 设置透明度为 50%。


<Box
  sx={{
    color: 'blue.500/50',
    bg: 'orange/50',
    border: '1px solid {colors.colorPalette.500/50}',
    borderTopColor: 'colorPalette.primary/90',
    colorPalette: 'red',
  }}
>
  Box
</Box>
 
/**
 * {
 *   color: color-mix(in srgb, var(--nui-colors-blue-500) 50%, transparent);
 *   background-color: color-mix(in srgb, orange 50%, transparent);
 *   border: 1px solid color-mix(in srgb, var(--nui-colors-red-500) 50%, transparent);
 *   border-top-color: color-mix(in srgb, var(--nui-colors-red-primary) 90%, transparent);
 * }
 **/

数组类型

当您想部分覆盖前一个索引中的某些样式时，数组类型会很有用。


<Box
  sx={[
    {
      '&:hover': {
        color: 'red',
        backgroundColor: 'white',
      },
    },
    foo && {
      '&:hover': { backgroundColor: 'grey' },
    },
    bar && {
      '&:hover': { backgroundColor: 'yellow' },
    },
  ]}
/>

当你悬浮到元素时，color:red; backgroundColor: white 将被应用。

如果 foo: true ，那么 color: red; backgroundColor: grey; 将在悬浮状态应用。

如果 bar: true ，那么 color: red; backgroundColor: yellow; 将在悬浮状态应用，无需关心 foo 的值，因为在数组中更高的索引具有更高的优先级。

Aliases

您可以通过 Aliases 定义 CSS 属性的别名，从而简化 CSS 属性名并支持组合 CSS 属性。


<Box sx={{ bg: 'blue.400', px: '2' }} />

Selector

当您想组合 CSS 选择器，例如 '&:not(:disabled):not([data-disabled=true]):hover', 您可以通过 Selectors 自定义更多的选择器，并解锁额外的使用方式。

在 Selectors 了解更多信息。