规则

¥Rules

规则定义工具类和生成的 CSS。UnoCSS 有许多内置规则，但也允许轻松添加自定义规则。

¥Rules define utility classes and the resulting CSS. UnoCSS has many built-in rules but also allows for easily adding custom rules.

静态规则

¥Static rules

以此为例：

¥With this example:

rules: [
  ['m-1', { margin: '0.25rem' }],
]

每当在用户的代码库中检测到 m-1 时，就会生成以下 CSS：

¥The following CSS will be generated whenever m-1 is detected in users' codebase:

.m-1 { margin: 0.25rem; }

注意：正文语法遵循 CSS 属性语法，例如。 font-weight 而不是 fontWeight。如果属性名称中有连字符 -，则应将其括起来。

¥Note: The body syntax follows CSS property syntax, eg. font-weight instead of fontWeight. If there is a hyphen - in the property name it should be quoted.

rules: [
  ['font-bold', { 'font-weight': 700 }],
]

动态规则

¥Dynamic rules

为了使其更智能，请将匹配器更改为 RegExp，将主体更改为函数：

¥To make it smarter, change the matcher to a RegExp and the body to a function:

rules: [
  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
  [/^p-(\d+)$/, match => ({ padding: `${match[1] / 4}rem` })],
]

body 函数的第一个参数是 RegExp 匹配结果，可以对其进行解构以获得匹配的组。

¥The first argument of the body function is the RegExp match result that can be destructured to get the matched groups.

例如，使用以下用法：

¥For example, with the following usage:

<div class="m-100">
  <button class="m-3">
    <icon class="p-5" />
    My Button
  </button>
</div>

将会生成相应的 CSS：

¥the corresponding CSS will be generated:

.m-100 { margin: 25rem; }
.m-3 { margin: 0.75rem; }
.p-5 { padding: 1.25rem; }

恭喜！现在你拥有了自己强大的原子 CSS 工具。享受！

¥Congratulations! Now you got your own powerful atomic CSS utilities. Enjoy!

完全受控的规则

¥Full controlled rules

警告

这是一项高级功能，大多数情况下你不需要它。

¥This is an advanced feature, you don't need it in most of the cases.

当你确实需要一些无法通过 动态规则 和 变体 的组合来涵盖的高级规则时，UnoCSS 还提供了一种方法来让你完全控制生成 CSS。

¥When you really need some advanced rules that can't be covered by the combination of Dynamic Rules and Variants, UnoCSS also provide a way to give you full control to generate the CSS.

通过从动态规则的主体函数返回 string，它将直接传递给生成的 CSS。这也意味着你需要处理 CSS 转义、变体应用、CSS 构建等问题。

¥By returning a string from the dynamic rule's body function, it will be directly passed to the generated CSS. That also means you would need to take care of things like CSS escaping, variants applying, CSS constructing, and so on.

// uno.config.ts
import { defineConfig, toEscapedSelector as e } from 'unocss'

export default defineConfig({
  rules: [
    [/^custom-(.+)$/, ([, name], { rawSelector, currentSelector, variantHandlers, theme }) => {
      // discard mismatched rules
      if (name.includes('something'))
        return

      // if you want, you can disable the variants for this rule
      if (variantHandlers.length)
        return
      const selector = e(rawSelector)
      // return a string instead of an object
      return `
${selector} {
  font-size: ${theme.fontSize.sm};
}
/* you can have multiple rules */
${selector}::after {
  content: 'after';
}
.foo > ${selector} {
  color: red;
}
/* or media queries */
@media (min-width: ${theme.breakpoints.sm}) {
  ${selector} {
    font-size: ${theme.fontSize.sm};
  }
}
`
    }],
  ],
})

排序

¥Ordering

UnoCSS 尊重你在生成的 CSS 中定义的规则的顺序。后者具有更高的优先级。

¥UnoCSS respects the order of the rules you defined in the generated CSS. Latter ones come with higher priority.

使用动态规则时，它可能会匹配多个标记。默认情况下，在单个动态规则下匹配的输出将在组内按字母顺序排序。

¥When using dynamic rule, it would likely match multiple tokens. By default, output of those matched under a single dynamic rule will be sorted alphabetically within the group.

规则合并

¥Rules merging

默认情况下，UnoCSS 会将 CSS 规则与同一正文合并，以最小化 CSS 大小。

¥By default, UnoCSS will merge CSS rules with the same body to minimize the CSS size.

例如，<div class="m-2 hover:m2"> 将生成：

¥For example, <div class="m-2 hover:m2"> will generate:

.hover\:m2:hover, .m-2 { margin: 0.5rem; }

而不是两个单独的规则：

¥Instead of two separate rules:

.hover\:m2:hover { margin: 0.5rem; }
.m-2 { margin: 0.5rem; }