rainbow-sprinkles

<h1 align="center">彩虹糖霜 🧁</h1> <p align="center"><i>为 <a href="https://vanilla-extract.style" rel="nofollow">vanilla-extract</a> 提供动态、主题驱动的样式属性</i></p> <div align="center">

</div>

彩虹糖霜的工作方式类似于 @vanilla-extract/sprinkles。与 sprinkles 一样，它在构建时生成自定义 CSS 实用类。而 sprinkles 需要预定义可用值列表，彩虹糖霜使用 CSS 自定义属性，通过内联样式变量分配允许动态值。

与 sprinkles 相比：

彩虹糖霜生成的 CSS 更少。 对于每个属性，Sprinkles 生成的 CSS 量级是 [预定义值] * [可能的条件]。彩虹糖霜生成的 CSS 只随条件数量增加而增加。
支持动态值。 彩虹糖霜使用动态内联样式分配来设置每个属性的值。你仍然可以获得 TypeScript 编辑器的建议，但可以使用该属性的任何有效 CSS 值。

<hr />

function App() {
  return (
    // 使用预定义值
    <Box bg="$blue50" margin="$large">
      {/* 或任何有效的 CSS 值 */}
      <Box textAlign="center" fontSize="30px">
        Hello world!
      </Box>
    </Box>
  );
}

<hr />

在这里查看 Stackblitz 演示！

<hr />

设置

安装彩虹糖霜。

npm install rainbow-sprinkles

创建一个 rainbow-sprinkles.css.ts 文件，然后创建并导出你的 rainbowSprinkles 函数：

// rainbow-sprinkles.css.ts
import { defineProperties, createRainbowSprinkles } from 'rainbow-sprinkles';

// 或导入主题（例如 `createTheme`、`createThemeContract`）
const vars = {
  space: {
    none: '0',
    small: '4px',
    medium: '8px',
    large: '16px',
    // 等等
  },
  colors: {
    blue50: '#eff6ff',
    blue100: '#dbeafe',
    blue200: '#bfdbfe',
    gray700: '#374151',
    gray800: '#1f2937',
    gray900: '#111827',
    // 等等
  },
};

const responsiveProperties = defineProperties({
  conditions: {
    mobile: {},
    tablet: { '@media': 'screen and (min-width: 768px)' },
    desktop: { '@media': 'screen and (min-width: 1024px)' },
  },
  defaultCondition: 'mobile',
  dynamicProperties: {
    // 定义预设值，将自动提示
    color: vars.colors,
    backgroundColor: vars.colors,
    margin: vars.space,
    marginTop: vars.space,
    marginLeft: vars.space,
    marginRight: vars.space,
    marginBottom: vars.space,
    // 可以使用任何 CSS 值
    display: true,
    textAlign: true,
    flexDirection: true,
    justifyContent: true,
    alignItems: true,
  },
  staticProperties: {
    // 构建不使用 CSS 变量的实用类
    display: ['block', 'flex', 'inline-block', 'inline-flex'],
  },
  shorthands: {
    bg: ['backgroundColor'],
    m: ['margin'],
    mr: ['marginRight'],
    ml: ['marginLeft'],
    mt: ['marginTop'],
    mb: ['marginBottom'],
    marginX: ['marginLeft', 'marginRight'],
    marginY: ['marginTop', 'marginBottom'],
    mx: ['marginLeft', 'marginRight'],
    my: ['marginTop', 'marginBottom'],
  },
});

export const rainbowSprinkles = createRainbowSprinkles(responsiveProperties);

export type Sprinkles = Parameters<typeof rainbowSprinkles>[0];

然后在你的"宿主"组件中进行设置（在这个例子中是一个 Box 组件）：

// Box.tsx
import { rainbowSprinkles, Sprinkles } from './rainbow-sprinkles.css';

interface BoxProps extends Sprinkles {
  children?: React.ReactNode;
}

export const Box = ({ children, ...props }: BoxProps) => {
  const { className, style, otherProps } = rainbowSprinkles(props);

  return (
    <div className={className} style={style} {...otherProps}>
      {children}
    </div>
  );
};

🎉 准备就绪！

// App.tsx
import { Box } from './Box';

function App() {
  return (
    // 使用预定义值
    <Box bg="$blue50" margin="$medium $large">
      {/* 或任何有效的 CSS 值 */}
      <Box textAlign="center" fontSize={{ mobile: '16px', desktop: '32px' }}>
        Hello world!
      </Box>
    </Box>
  );
}

CSS 层

你可以为给定的属性集定义一个 CSS 层。

// rainbow-sprinkles.css.ts
import { layer } from '@vanilla-extract/css';
import { defineProperties } from 'rainbow-sprinkles';

export const sprinklesLayer = layer();

const properties = defineProperties({
  '@layer': sprinklesLayer
  // 等等
});

`dynamicProperties` 与 `staticProperties`

支持动态值的一个代价是我们必须增加文档的大小。不是仅仅向元素添加一个类来添加样式，而是同时添加一个实用类和内联样式分配。虽然这种设置在许多情况下仍会产生更小的整体包大小，但一些大型应用可能会观察到特定 CSS 属性和值组合的频繁重复出现。在这些情况下，可以在初始配置中将这些组合设置在 staticProperties 中。staticProperties 将生成典型的 CSS 实用类。Rainbow Sprinkles 的运行时部分将优先使用 staticProperties 创建的 CSS 类，而不应用任何内联样式分配。

这里有一个可能有价值的场景示例。你的组织设置了 Rainbow Sprinkles 并得到了广泛采用。你的指标显示最常用的属性/值组合是 display="flex" 和使用应用主题变量的 margin。你可以运行一个实验来评估将这些属性/值组合设为静态是否能改善包大小。

createRainbowSprinkles({
  dynamicProperties: {
    // 仍然支持任意值
    display: true,
    margin: true,
  },
  staticProperties: {
    // 同时生成固定的 CSS 类
    display: ['flex'],
    margin: vars.space,
  },
});