UnoCSS 中文网

Appearance

Vite 插件 ​

¥Vite Plugin

Vite 插件随 unocss 包一起提供。

¥The Vite plugin ships with the unocss package.

安装 ​

¥Installation

bash
pnpm add -D unocss
bash
yarn add -D unocss
bash
npm install -D unocss

安装插件：

¥Install the plugin:

ts
// vite.config.ts
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS(),
  ],
})

创建 uno.config.ts 文件：

¥Create a uno.config.ts file:

ts
// uno.config.ts
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS options
})

将 virtual:uno.css 添加到你的主入口中：

¥Add virtual:uno.css to your main entry:

ts
// main.ts
import 'virtual:uno.css'

模式 ​

¥Modes

Vite 插件附带了一组可实现不同行为的模式。

¥The Vite plugin comes with a set of modes that enable different behaviors.

global（默认） ​

¥global (default)

这是插件的默认模式：在此模式下，你需要在入口点添加 uno.css 的导入。

¥This is the default mode for the plugin: in this mode you need to add the import of uno.css on your entry point.

此模式为 build 和 dev 启用一组 Vite 插件，并支持 HMR。

¥This mode enables a set of Vite plugins for build and for dev with HMR support.

生成的 css 将是注入到 index.html 上的全局样式表。

¥The generated css will be a global stylesheet injected on the index.html.

vue-scoped ​

此模式会将生成的 CSS 注入到 Vue SFC <style scoped> 中以进行隔离。

¥This mode will inject generated CSS to Vue SFCs <style scoped> for isolation.

svelte-scoped ​

svelte-scoped 模式已移至其自己的包中，请参阅 @unocss/svelte-scoped/vite。

¥svelte-scoped mode has been moved to its own package, see @unocss/svelte-scoped/vite.

shadow-dom ​

由于 Web Components 使用 Shadow DOM，因此无法直接从全局样式表设置内容样式（除非你使用 CSS custom properties，否则这些内容会渗透到 Shadow DOM），你需要将插件生成的 CSS 内联到 Shadow DOM 样式中。

¥Since Web Components uses Shadow DOM, there is no way to style content directly from a global stylesheet (unless you use CSS custom properties, those will penetrate the Shadow DOM), you need to inline the generated CSS by the plugin into the Shadow DOM style.

要内联生成的 CSS，你只需将插件模式配置为 shadow-dom，并在每个 Web 组件样式 CSS 块上包含 @unocss-placeholder 魔术占位符。如果你在 Vue SFC 中定义 Web 组件，并希望与 UnoCSS 一起定义自定义样式，则可以将占位符包含在 CSS 注释中，以避免 IDE 中出现语法错误。

¥To inline the generated CSS, you only need to configure the plugin mode to shadow-dom and include @unocss-placeholder magic placeholder on each web component style CSS block. If you are defining your Web Components in Vue SFCs and want to define custom styles alongside UnoCSS, you can wrap placeholder in a CSS comment to avoid syntax errors in your IDE.

per-module（实验性） ​

¥per-module (experimental)

此模式将为每个模块生成一个 CSS 表，可以限定作用域。

¥This mode will generate a CSS sheet for each module, can be scoped.

dist-chunk（实验性） ​

¥dist-chunk (experimental)

此模式将为构建时的每个代码块生成一个 CSS 表，非常适合 MPA。

¥This mode will generate a CSS sheet for each code chunk on build, great for MPA.

在 DevTools 中编辑类 ​

¥Edit classes in DevTools

由于 "on-demand" 的限制，DevTools 不知道那些你尚未在源代码中使用过的内容。因此，如果你想通过直接更改 DevTools 中的类来尝试事情是如何工作的，只需将以下行添加到你的主入口中即可。

¥Because of limitation of "on-demand" where the DevTools don't know those you haven't used in your source code yet. So if you want to try how things work by directly changing the classes in DevTools, just add the following lines to your main entry.

ts
import 'uno.css'
import 'virtual:unocss-devtools'

警告

请谨慎使用它，在幕后我们使用 MutationObserver 来检测类更改。这意味着不仅你的手动更改，而且你的脚本所做的更改都将被检测到并包含在样式表中。当你根据脚本标记中的某些逻辑添加动态类时，这可能会导致开发和生产构建之间出现一些不一致。如果可能，我们建议将动态部件添加到 safelist 或为你的生产版本设置 UI 回归测试。

¥Please use it with caution, under the hood we use MutationObserver to detect the class changes. Which means not only your manual changes but also the changes made by your scripts will be detected and included in the stylesheet. This could cause some misalignment between dev and the production build when you add dynamic classes based on some logic in script tags. We recommended adding your dynamic parts to the safelist or setup UI regression tests for your production build if possible.

构架 ​

¥Frameworks

某些 UI/应用框架有一些警告，必须修复这些警告才能使其正常工作，如果你使用以下框架之一，只需应用建议即可。

¥Some UI/App frameworks have some caveats that must be fixed to make it work, if you're using one of the following frameworks, just apply the suggestions.

VanillaJS / TypeScript ​

使用 VanillaJS 或 TypeScript 时，需要添加 js 和 ts 文件扩展名以允许 UnoCSS 读取和解析内容，默认情况下排除 js 和 ts 文件，请查看 从构建工具管道中提取 部分。

¥When using VanillaJS or TypeScript, you need to add js and ts files extensions to allow UnoCSS read and parse the content, by default js and ts files are excluded, check out the Extracting from Build Tools Pipeline section.

React ​

如果你使用的是 @vitejs/plugin-react：

¥If you're using @vitejs/plugin-react:

ts
// vite.config.js
import UnoCSS from 'unocss/vite'
import React from '@vitejs/plugin-react'

export default {
  plugins: [
    React(),
    UnoCSS(),
  ],
}

如果你使用的是 @unocss/preset-attributify，则应从 build 脚本中删除 tsc。

¥If you're using @unocss/preset-attributify you should remove tsc from the build script.

如果你将 @vitejs/plugin-react 与 @unocss/preset-attributify 一起使用，则必须在 @vitejs/plugin-react 之前添加该插件。

¥If you are using @vitejs/plugin-react with @unocss/preset-attributify, you must add the plugin before @vitejs/plugin-react.

ts
// vite.config.js
import UnoCSS from 'unocss/vite'
import React from '@vitejs/plugin-react'

export default {
  plugins: [
    UnoCSS(),
    React(),
  ],
}

你在 examples/vite-react 目录下有一个使用这两个插件的 React 示例项目，请检查 package.json 上的脚本及其 Vite 配置文件。

¥You have a React example project on examples/vite-react directory using both plugins, check the scripts on package.json and its Vite configuration file.

Preact ​

如果你使用的是 @preact/preset-vite：

¥If you're using @preact/preset-vite:

ts
// vite.config.js
import Preact from '@preact/preset-vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Preact(),
  ],
}

或者如果你使用的是 @prefresh/vite：

¥or if you're using @prefresh/vite:

ts
// vite.config.js
import Prefresh from '@prefresh/vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Prefresh(),
  ],
}

如果你使用的是 @unocss/preset-attributify，则应从 build 脚本中删除 tsc。

¥If you're using @unocss/preset-attributify you should remove tsc from the build script.

你在 examples/vite-preact 目录下有一个使用这两个插件的 Preact 示例项目，请检查 package.json 上的脚本及其 Vite 配置文件。

¥You have a Preact example project on examples/vite-preact directory using both plugins, check the scripts on package.json and its Vite configuration file.

Svelte ​

你必须在 @sveltejs/vite-plugin-svelte 之前添加该插件。

¥You must add the plugin before @sveltejs/vite-plugin-svelte.

要支持 class:foo 和 class:foo={bar}，请添加插件并在 extractors 选项上配置 extractorSvelte。

¥To support class:foo and class:foo={bar} add the plugin and configure extractorSvelte on extractors option.

你可以将简单规则与 class: 一起使用，例如 class:bg-red-500={foo} 或使用 shortcuts 来包含多个规则，请参阅下面链接示例项目中的 src/App.svelte。

¥You can use simple rules with class:, for example class:bg-red-500={foo} or using shortcuts to include multiples rules, see src/App.svelte on linked example project below.

ts
// vite.config.js
import { svelte } from '@sveltejs/vite-plugin-svelte'
import UnoCSS from 'unocss/vite'
import extractorSvelte from '@unocss/extractor-svelte'

export default {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* more options */
    }),
    svelte(),
  ],
}

Sveltekit ​

要支持 class:foo 和 class:foo={bar}，请添加插件并在 extractors 选项上配置 extractorSvelte。

¥To support class:foo and class:foo={bar} add the plugin and configure extractorSvelte on extractors option.

你可以将简单规则与 class: 一起使用，例如 class:bg-red-500={foo} 或使用 shortcuts 来包含多个规则，请参阅下面链接示例项目中的 src/routes/+layout.svelte。

¥You can use simple rules with class:, for example class:bg-red-500={foo} or using shortcuts to include multiples rules, see src/routes/+layout.svelte on linked example project below.

ts
// vite.config.js
import { sveltekit } from '@sveltejs/kit/vite'
import UnoCSS from 'unocss/vite'
import extractorSvelte from '@unocss/extractor-svelte'

/** @type {import('vite').UserConfig} */
const config = {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* more options */
    }),
    sveltekit(),
  ],
}

Web Components ​

要使用 Web 组件，你需要在插件上启用 shadow-dom 模式。

¥To work with web components you need to enable shadow-dom mode on the plugin.

不要忘记删除 uno.css 的导入，因为 shadow-dom 模式不会公开它并且应用将无法工作。

¥Don't forget to remove the import for uno.css since the shadow-dom mode will not expose it and the application will not work.

ts
// vite.config.js
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
      /* more options */
    }),
  ],
}

在每个 web component 上，只需将 @unocss-placeholder 添加到其样式 CSS 块中：

¥On each web component just add @unocss-placeholder to its style CSS block:

ts
const template = document.createElement('template')
template.innerHTML = `
<style>
:host {...}
@unocss-placeholder
</style>
<div class="m-1em">
...
</div>
`

如果你使用的是 Lit：

¥If you're using Lit:

ts
@customElement('my-element')
export class MyElement extends LitElement {
  static styles = css`
    :host {...}
    @unocss-placeholder
  `
  // ...
}

你在 examples/vite-lit 目录中有一个 Web Components 示例项目。

¥You have a Web Components example project on examples/vite-lit directory.

::part 内置支持 ​

¥::part built-in support

你可以使用 ::part，因为该插件通过 shortcuts 支持它并使用 preset-mini 中的 part-[<part-name>]:<rule|shortcut> 规则，例如将其与 part-[<part-name>]:bg-green-500 等简单规则一起使用或使用某些 shortcut：检查下面链接的示例项目中的 src/my-element.ts。

¥You can use ::part since the plugin supports it via shortcuts and using part-[<part-name>]:<rule|shortcut> rule from preset-mini, for example using it with simple rules like part-[<part-name>]:bg-green-500 or using some shortcut: check src/my-element.ts on linked example project below.

part-[<part-name>]:<rule|shortcut> 仅适用于使用 shadow-dom 模式的此插件。

¥The part-[<part-name>]:<rule|shortcut> will work only with this plugin using the shadow-dom mode.

该插件使用 nth-of-type 来避免与同一 Web 组件中的多个部分发生冲突，并且对于不同 Web 组件上的相同部分，你无需担心它，该插件会照顾你。

¥The plugin uses nth-of-type to avoid collisions with multiple parts in the same web component and for the same parts on distinct web components, you don't need to worry about it, the plugin will take care for you.

ts
// vite.config.js
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
      shortcuts: [
        { 'cool-blue': 'bg-blue-500 text-white' },
        { 'cool-green': 'bg-green-500 text-black' },
      ],
      /* more options */
    }),
  ],
}

然后在你的 web components 中：

¥then in your web components:

ts
// my-container-wc.ts
const template = document.createElement('template')
template.innerHTML = `
<style>
@unocss-placeholder
</style>
<my-wc-with-parts class="part-[cool-part]:cool-blue part-[another-cool-part]:cool-green">...</my-wc-with-parts>
`
ts
// my-wc-with-parts.ts
const template = document.createElement('template')
template.innerHTML = `
<style>
@unocss-placeholder
</style>
<div>
  <div part="cool-part">...</div>
  <div part="another-cool-part">...</div>
</div>
`

Solid ​

你需要在 UnoCSS 插件之后添加 vite-plugin-solid 插件。

¥You need to add the vite-plugin-solid plugin after UnoCSS's plugin.

ts
// vite.config.js
import solidPlugin from 'vite-plugin-solid'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      /* options */
    }),
    solidPlugin(),
  ],
}

Elm ​

你需要在 UnoCSS 插件之前添加 vite-plugin-elm 插件。

¥You need to add the vite-plugin-elm plugin before UnoCSS's plugin.

ts
// vite.config.js
import { defineConfig } from 'vite'
import Elm from 'vite-plugin-elm'
import UnoCSS from 'unocss/vite'

export default defineConfig({
  plugins: [
    Elm(),
    UnoCSS(),
  ],
})

许可 ​

¥License