# weapp-tailwindcss 文档索引

> Tailwind CSS 小程序适配方案，覆盖 uni-app、taro、rax、mpx、原生等场景的官方文档合集。

完整文档合辑，适合离线或单文件加载：
- quick-start/* 给出接入步骤与常见框架示例，options/*、api* 提供配置与 API 细节，ai/* 收录提示词与工作流。
- 内容按上手优先排序，并保留关键 frontmatter 供模型摘要与索引。

## 简介


<!-- :::tip
自从 `2.3.3` 版本开始，我发布了一个额外的包叫 [`weapp-tailwindcss`](https://www.npmjs.com/package/weapp-tailwindcss),它和 [`weapp-tailwindcss-webpack-plugin`](https://www.npmjs.com/package/weapp-tailwindcss-webpack-plugin) 代码版本完全一致，且保持发布版本的同步。以后可以都去安装那个包(当然安装现在这个包也行)。为什么要这么做的原因，主要是因为 `weapp-tailwindcss-webpack-plugin` 这个名字，已经不适合现在这种，多插件并存的状态了，为了以后的发展改个名字。
::: -->

## 总览

由于小程序运行时，本身有自己的一套 **独特的** 技术规范标准。这导致你无法使用 `web` 开发中的很多的特性，

你也无法 **直接** 使用像 [`tailwindcss`](https://www.tailwindcss.com/) 这种原子化 `css` 生成器来提升你的开发效率。

而 `weapp-tailwindcss` 就能让你，在小程序开发中使用 `tailwindcss` **大部分** 特性。

它支持目前上所有使用 `webpack` 和 `vite` 的主流多端小程序框架和使用 `webpack` / `gulp` 的原生小程序打包方式。

你可以很容易在各个框架，或原生开发中集成 `tailwindcss`。

现在，就让我们开始使用吧！

:::info
从本质上讲，它是一个字符串转义器。它负责把 `tailwindcss` 中，所采集的类名，以及生成的结果，转化成小程序中可以接受的方式。
:::

## Why `weapp-tailwindcss`?

- ✅ 自动处理所有文件：以微信小程序为例，不但可以处理和转义 `wxml` / `wxss`，还能处理 `js` 和 `wxs` 产物
- ✅ 支持最原生的小程序开发，也支持许多框架如 `taro` , `uni-app` , `mpx` , `rax` 等等..
- ✅ 提供多种使用方式，方便项目集成：包括 `webpack` / `vite` / `gulp` 插件和直接的 `nodejs api`
- ✅ 生态好，解决方案丰富，提供大量现成模板，可以利用许多 `tailwindcss` 现有的生态来构建小程序。
- ✅ 高效的解析和缓存机制，热更新响应时间快
- ✅ 贴合 `tailwindcss` 的设计思路，智能提示友好

## 快速开始 :rocket:

### 🔥 Tailwind CSS @3.x

`weapp-tailwindcss` 主要提供了 `3` 种使用方式:

#### 👉 [1. 框架类( `taro` , `uni-app` , `mpx` )小程序开发的快速开始](/docs/quick-start/install)

#### 👉 [2. 原生小程序开发的快速开始](/docs/quick-start/native/install)

#### 👉 [3. 可直接使用的各个框架的小程序模板](/docs/community/templates)

### 🧪 Tailwind CSS @4.x

#### 👉 [Tailwindcss@4.x 快速开始](/docs/quick-start/v4)

## 演示视频

<iframe src="//player.bilibili.com/player.html?aid=835925684&bvid=BV1fg4y1D7xx&cid=1398844948&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

## 另外特别感谢 [舜岳同学](https://space.bilibili.com/475498258) 为 `weapp-tailwindcss` 制作的视频

<iframe src="//player.bilibili.com/player.html?aid=1850100366&bvid=BV1kp421Z7HL&cid=1428939742&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

---

## 小程序多主题方案


## 自由的 web 方案

对于 `web` 来说，多主题色的需求是非常常见的，比如 `暗黑模式` 就是一个极其常见的需求，

`web` 上的解决方案无非就是，通过动态切换 `css` 变量的值达成效果，或者通过 `.dark / [data-theme]` 选择器，包裹暗黑模式下页面和组件的样式，通过增加选择器的优先级，来覆盖默认的样式等等...

那么小程序的方案应该怎么去实现呢？

答案就是有 [page-meta 页面属性配置节点](https://developers.weixin.qq.com/miniprogram/dev/component/page-meta.html) 的情况下，优先使用它的 `page-style` 属性，进行 `css` 变量的切换

没有 `page-meta` 页面属性配置节点的情况下，我们只能通过配置单个 `view` 组件的样式变量，来进行主题色的切换

<!-- ## 目前小程序存在的限制

首先，小程序中是没有 `:root/html` 选择器的，取而代之的是 `page` 标签选择器，因为小程序中 `page` 才是每个页面的根节点。

其次小程序本身都是多页面的，而我们经常写的 `vue/react` 等等`spa`应用都是单页应用(可以做多页，我只是举个大多数的情况，不要钻牛角尖哈)。

而且 `web` 中我们可以通过 `element.style.setProperty` 这样的 `js api` 轻而易举的修改 `css` 变量的值，但是小程序不行，

我们以微信小程序中选取 `wxml` 的 `api`: `wx.createSelectorQuery` 为例，它甚至都无法选中 `page` 标签，更何况即使选中了，目前也没有能力动态的通过 `js api` 的方式去设置`css` 变量的值。

那么我们究竟应该怎么设计方案呢？ -->

## 方案的设计和实现

切换多主题主要依赖 `css` 变量切换，所以我们只要依照这个设计去实现即可

### 1. 页面属性配置节点 page-meta

利用 `page-meta` 页面属性配置节点的 `page-style` 属性，来进行 `css` 变量的切换

另外我们也可以通过 `page-meta` 组件的，来切换一些原生的样式

[page-meta 页面属性配置节点](https://developers.weixin.qq.com/miniprogram/dev/component/page-meta.html)

### 2. 自己实现 css 变量切换组件

首先既然我们无法利用**根**节点的变量切换来达成效果，但是我们可以通过组件的特性，即数据的响应式和插槽来达成效果。

我们可以设计一个 `ConfigProvider` 组件，它拥有一个`dom`节点，内部是一个插槽

其中那个`dom`节点就是我们主题相关变量寄居在的节点，而这个组件往往会作为一个根组件，在每个页面中被使用，去包裹我们真正的业务页面

甚至我们可以再设计一个 `BaseLayout` 这样的组件，去包含每个页面公共的部分，再在其中去引用 `ConfigProvider`，然后做一层插槽的透传即可。

#### 实现

> 这里我以 `vue` 的语法作为示例，因为我个人认为它比 `react` 和 `原生` 更容易让新手看懂

`ConfigProvider`的实现：

```html
<template>
  <view :class="[mode]" :style="styleObj">
    <slot></slot>
  </view>
</template>

<script lang="ts">

// import store from '@/store'
export default defineComponent({
  props: {
    vars: {
      type: [Object]
    },
    mode: {
      type: [String] as PropType<'light' | 'dark'>,
      default: 'light' // 这里你可以使用 store.state.mode 这样的值来获取用户的配置
    }
  },
  setup(props) {
    const styleObj = computed(() => {
      return Object.assign({}, props.vars)
    })
    return {
      styleObj
    }
  }
})
</script>
```

其中，`mode` 这个 `prop` 用来模拟实现了 `<html data-theme="<theme>" class="<theme>"></html>` 的效果，而 `vars` 则用来模拟实现 `js api` 设置 `css` 变量的效果。

通过这 `2` 个 `props`，你既可以通过 `mode` 的切换，把多个主题以及对应的变量值全部给写在你自己的 `css`中，然后通过切换`mode`，触发样式的覆盖来切换主题，这种是为静态的切换。

又可以通过设置 `vars`的值去动态的覆盖和切换，比如从服务端获取`css`变量的值，然后`set`进组件中，这显然是非常灵活的，这种是为动态的切换。

现在有了这个组件，我们就可以用它去包裹每一个页面了。

然后下一步，自然是要我们的页面和组件，都去应用那些我们设计的 `css` 变量了。

这一块可以参考下方链接中的`动态调整系统主题色(4)`中的`CssVar`方案，里面也有和 `tailwindcss` 相结合的部分，也欢迎阅读`动态调整web系统主题` 系列文章，并与在下进行探讨。

## 动态调整主题参考链接

1. [动态调整web系统主题? 看这一篇就够了](https://icebreaker.top/articles/2021/12/18-flexible-theme)
2. [动态调整web主题(2) 萃取篇](https://icebreaker.top/articles/2022/1/15-custom-theme-2)
3. [动态调整web主题(3): 基于tailwindcss插件的主题色生成方案](https://icebreaker.top/articles/2022/9/26-custom-theme-3)
4. [动态调整系统主题色(4): CssVar 与 Variant 方案的探索](https://icebreaker.top/articles/2023/10/5-custom-theme-4)

## 参考示例

微信上搜索 `tailwind`（未交 `30` 元个人资质费用，已无法搜索），进入小程序即可，小程序码：

![tailwind](./frameworks/img/tailwind-mp-qrcode.jpg)

实现源代码详见: [weapp-tailwindcss/tailwindcss-weapp](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/tailwindcss-weapp)

---

## 构建以及引入外部组件


## 前言

我们在日常的开发中，经常会去使用和封装各种各样的组件库。有些是开源的，第三方开发的UI库，有些是我们开发人员给自己的特定的业务封装的UI库。其中很多情况其实是以流行的 `开源UI库(或者fork的改版)` + `自己封装的业务组件为主的`

`开源UI库` 它们的样式相对来说是独立于整套系统的，比如它们的样式都是 `ant-`，`el-` 开头的，一般引入之后不会和原先系统里的样式产生冲突。而 `自己封装的业务组件`，由于往往和系统高度绑定也没有这样的问题。

那么如何用 `tailwindcss` 来构建/发布和引入自己封装的业务组件呢？

## 构建组件

### 核心思想

首先我必须重点把本篇文章的核心思想预先抛出：

`tailwindcss` 只是一个`css`生成器，它只是帮你按照一定的规则，从你的源代码中匹配字符串去生成`css`。所以在用它去构建组件的时候，一定要去思考你用 `tailwindcss` 生成的 `css` 的影响范围，因为大部分用 `tailwindcss` 都是默认全局应用的。但是你在组件里面的自定义样式很多情况下，是没有必要的。

根据这个核心思想，我们就可以知道在封装组件时可行和不可行的方式了，大致如下:

### 可行方案

1. `custom css selector` + `Functions & Directives`
2. `add prefix` (添加前缀)
3. `add scoped` (像 `vue` 的 `scoped` 一样添加 data-v-[hash] 类似的自定义属性，然后去修改css选择器)
4. 不打包方案 (不构建产物，直接发布，然后在项目里安装，再提取 `node_modules` 里制定的文本重新生成。)

### 不可行方案

1. module css 这会去修改 css 选择器。

## 可行方案详解

这里我写了2个`demo`分别是 `react` 和 `vue`，其中下方代码以 `vue` 为示例，`react`示例见下方的 `构建demo链接`

### custom css selector + Functions & Directives

这种方案其实非常的传统，仅仅使用到了 `tailwindcss` 中 `@apply` 和 `theme` 等等指令的功能。

比如我们有个组件 `ApplyButton.vue`，它的模板，样式和独立的 `tailwind.config.js` 分别如下所示:

```html
<script setup lang="ts">
</script>

<template>
  <button class="apply-button">ApplyButton</button>
</template>

<style src="./index.css"></style>
```

```css
@config 'tailwind.config.js';
@tailwind utilities;

.apply-button {
  @apply text-white p-4 rounded;
  background-color: theme("colors.sky.600")
}
```

```js
const path = require('node:path')

/** @type {import('tailwindcss').Config} */
export default {
  content: [path.resolve(__dirname, './index.vue')],
  // ...
}
```

然后在打包的时候，以这个文件或者导出文件(`index.ts`) 为打包入口即可。

这样它的产物css中，选择器由于是你自己定义的，就能尽可能保证它是独一无二的。

它对应的`css`产物为:

```css
.apply-button {
  border-radius: 0.25rem;
  --tw-bg-opacity: 1;
  background-color: rgb(2 132 199 / var(--tw-bg-opacity));
  padding: 1rem;
  --tw-text-opacity: 1;
  color: rgb(255 255 255 / var(--tw-text-opacity));
}
```

### add prefix

这个也很好理解，前缀嘛，各个UI库都是这样搞的，我们就可以创建出以下的代码:

```html
<script setup lang="ts">
</script>

<template>
  <button class="ice-bg-sky-600 ice-text-white ice-p-4 ice-rounded">PrefixButton</button>
</template>

<style>
@config 'tailwind.config.js';
@tailwind utilities;
</style>
```

```js
const path = require('node:path')

/** @type {import('tailwindcss').Config} */
export default {
  prefix: 'ice-',
  content: [path.resolve(__dirname, './index.vue')],
}
```

它对应的`css`产物为:

```css
.ice-rounded {
  border-radius: 0.25rem;
}
.ice-bg-sky-600 {
  --tw-bg-opacity: 1;
  background-color: rgb(2 132 199 / var(--tw-bg-opacity));
}
.ice-p-4 {
  padding: 1rem;
}
.ice-text-white {
  --tw-text-opacity: 1;
  color: rgb(255 255 255 / var(--tw-text-opacity));
}
```

### add scoped

这个就是通过同时添加html标签属性和修改css选择器来做的了:

```html
<script setup lang="ts">
</script>

<template>
  <button class="bg-sky-600 text-white p-4 rounded">ScopedButton</button>
</template>

<style scoped>
@config 'tailwind.config.js';
@tailwind utilities;
</style>
```

这里仅仅给 `style` 加了一个 `scoped` 属性

```js
const path = require('node:path')

/** @type {import('tailwindcss').Config} */
export default {
  content: [path.resolve(__dirname, './index.vue')],
}
```

`css` 生成结果为:

```css
.rounded[data-v-10205a53] {
  border-radius: 0.25rem;
}
.bg-sky-600[data-v-10205a53] {
  --tw-bg-opacity: 1;
  background-color: rgb(2 132 199 / var(--tw-bg-opacity));
}
.p-4[data-v-10205a53] {
  padding: 1rem;
}
.text-white[data-v-10205a53] {
  --tw-text-opacity: 1;
  color: rgb(255 255 255 / var(--tw-text-opacity));
}
```

### 不打包

以上三种方式总结一下，都是通过在选择器上下功夫来制作组件库的，而且它们都有一个打包的过程，即 `src`->`dist` 然后发布 `dist`

可是这第四种方案就不怎么一样了: 核心就是 `不打包`

即我们写好组件之后，直接把 `npm`的入口文件，指向 `src` ，然后直接把里面的组件发布(比如直接发布 `vue`组件)

这种情况下，你需要让你在 `node_modules` 里的组件再次经受一遍 `js` 的处理，比如 `vue sfc compiler`,`babel`,`swc`等等。

同时你也需要配置你项目里的 `tailwind.config.js` 去提取你 `node_modules` 里的组件源代码内容:

```diff
module.exports = {
  content: [
    './index.html',
    './src/**/*.{html,js,ts,jsx,tsx,vue}',
+   './node_modules/mypkg/src/components/**/*.{html,js,ts,jsx,tsx,vue}'
  ]
}
```

这样才能重新提取生成 `css` 在项目主`css chunk`里。

## 构建demo链接

<https://github.com/sonofmagic/weapp-tailwindcss/tree/main/how-to-build-components-by-tailwindcss>

## 相关 issues

<https://github.com/sonofmagic/weapp-tailwindcss/issues/247>

---

## CSS 单位转化


## rem 转 rpx (或 px)

在 [rem 转 rpx (或 px)](/docs/quick-start/rem2rpx) 章节，我们做了 `CSS` 中 `rem` 转化成 `px` / `rpx` 的方式。

但是除了 [rem 转 rpx (或 px)](/docs/quick-start/rem2rpx)，我们可能也有 `px 转 rpx` 的需求，这种情况实际上也很容易就能做到。

## px 转 rpx

### 4.3.0 以后

从 `weapp-tailwindcss@4.3.0` 开始，我们内置了 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 插件，提供了开箱即用的 `px` 转 `rpx` 的方式。

只需传入配置项:

```js
// vite

UnifiedViteWeappTailwindcssPlugin({
  // ...other-options
  px2rpx: true
})
// webpack
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
new UnifiedWebpackPluginV5({
  // ...other-options
  px2rpx: true
})
```

只需传入一个 `true`，你写的所有的 `px` 都会被 `1:1` 的转换成 `rpx`，比如 `10px` -> `10rpx`

当然这个选项也可以传入一个 `object`, 这个默认值和参数，可以参考 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 插件。

### 4.3.0 以前

这里我们使用 [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 这个 `postcss` 插件来做。

> [`postcss-pxtransform`](https://www.npmjs.com/package/postcss-pxtransform) 由京东团队出品，应该是目前质量最高的 `px` 转 `rpx` 插件，而且已经被内置在了 `tarojs` 框架内

#### 安装插件

```bash npm2yarn
npm i -D postcss-pxtransform
```

#### 注册到 postcss 配置中

```js title="postcss.config.js"
module.exports = {
  plugins: {
    'tailwindcss': {},
    'autoprefixer': {},
    // highlight-start
    // 下方为 px 转 rpx 区域
    'postcss-pxtransform': {
      platform: 'weapp',
      // 根据你的设计稿宽度进行配置
      // 可以传入一个 function
      // designWidth (input) {
      //   if (input.file.replace(/\\+/g, '/').indexOf('@nutui/nutui-taro') > -1) {
      //     return 375
      //   }
      //   return 750
      // },
      designWidth: 750, // 可以设置为 375 等等来应用下方的规则,
      deviceRatio: {
        640: 2.34 / 2,
        // 此时应用到的规则，代表 1px = 1rpx
        750: 1,
        828: 1.81 / 2,
        // 假如你把 designWidth 设置成 375 则使用这条规则 1px = 2rpx
        375: 2 / 1,
      },
    },
    // highlight-end
  },
}

```

这样就能进行转化了，此时假如你写 `w-[20px]` 这种 `class` 它最终生效的样式会经过 `postcss-pxtransform` 转化，转变为 `width: 20rpx`, 当然这取决于你传入插件的配置，比如设计稿宽度 (`designWidth`)

你可以在 [taro 官网的设计稿及尺寸单位章节内](https://docs.taro.zone/docs/size) 查看这个插件的所有用法。

另外，假如你要禁止单个文件 `px` 转 `rpx`，可以在样式表文件内头部，添加 `/*postcss-pxtransform disable*/` 这样的注视，禁用该文件 `px` 转 `rpx`。

---

## Nodejs API


> 版本 2.11.0+ , 此为高阶 `api`，使用起来有难度，不适合新手，假如你不清楚你在做什么，请使用 `webpack/vite/gulp` 插件

有时候,我们不一定会使用 `webpack/vite/gulp`，可能是直接使用 `nodejs` 去构建应用，或者封装更高阶的工具，这时候可以使用`api`去转义你的应用。

## 如何使用

```js
// mjs or

// cjs
const { createContext } = require('weapp-tailwindcss/core')

async function main(){
  // createContext 可传入参数，类型为 UserDefinedOptions
  const ctx = createContext()
  // 3.1.0 开始 api 都是异步的，为 rust 工具链做准备
  const wxssCode = await ctx.transformWxss(rawWxssCode)
  const wxmlCode = await ctx.transformWxml(rawWxmlCode)
  const jsCode = await ctx.transformJs(rawJsCode)
  // 传入参数和输出结果均为 字符串 string

  // 然后你就可以根据结果去复写你的文件了
}

main()
```

:::tip
有一点要特别注意，在使用 `ctx.transformJs` 的时候，一定要确保 `tailwindcss` 已经执行完毕了！也就是说对应的 `postcss` 执行完毕。

因为 `js` 的转义依赖 `tailwindcss` 的执行结果，然后根据它，再去从你的代码中找到 `tailwindcss` 提取出的字符串，再进行处理的。

假如此时 `tailwindcss` 还没有执行，则插件就只能获取到一个 **空的** 提取字符串集合，这就无法进行匹配，从而导致你写在 `js` 里的类名转义失效。

比如这种情况:

```js
// index.js
const classNames = ['mb-[1.5rem]']
```

另外使用此种方式，编译缓存需要自行处理，且暂时没有类名的压缩与混淆功能
:::

---

## uni-app HbuilderX 使用方式


## 默认使用方式

> 配置会稍微复杂一些，这里推荐直接使用或者参考模板: [uni-app-vue3-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue3-tailwind-hbuilder-template) 或者 [若依移动端 (Gitee 地址)](https://gitee.com/sonofmagic/RuoYi-App)

### tailwind.config.js

注意: 在使用 `hbuilderx` 进行开发时，由于目录结构和启动项的不同，你必须要给你 `tailwind.config.js` 传入**绝对路径**:

```js title="tailwind.config.js"
const path = require("path");

const resolve = (p) => {
  return path.resolve(__dirname, p);
};
/** @type {import('tailwindcss').Config} */
module.exports = {
  // 注意此处，一定要 `path.resolve` 一下, 传入绝对路径
  // 你要有其他目录，比如 components，也必须在这里，添加一下
  content: ["./index.html", "./pages/**/*.{html,js,ts,jsx,tsx,vue}"].map(resolve),
  // ...
  corePlugins: {
    // 跨多端可以 h5 开启，小程序关闭
    preflight: false,
  },
};
```

### vite.config.[tj]s

另外使用 `vite.config.[tj]s` 中注册 `tailwindcss` 时，也要传入绝对路径:

```js title="vite.config.[tj]s"

// 注意： 打包成 h5 和 app 都不需要开启插件配置
const isH5 = process.env.UNI_PLATFORM === "h5";
const isApp = process.env.UNI_PLATFORM === "app";
const WeappTailwindcssDisabled = isH5 || isApp;

const resolve = (p) => {
  return path.resolve(__dirname, p);
};

export default defineConfig({
  plugins: [
    uni(),
    uvwt({
      rem2rpx: true,
      disabled: WeappTailwindcssDisabled,
      // 由于 hbuilderx 会改变 process.cwd 所以这里必须传入当前目录的绝对路径
      tailwindcssBasedir: __dirname
    })
  ],
  css: {
    postcss: {
      plugins: [
        require("tailwindcss")({
          // 注意此处，手动传入你 `tailwind.config.js` 的绝对路径
          config: resolve("./tailwind.config.js"),
        }),
        require("autoprefixer"),
      ],
    },
  },
});
```

`hbuilderx` 正式版本的 `vue2` 项目,由于使用 `webpack4` 和 `postcss7`，所以只能使用本插件的 `weapp-tailwindcss/webpack4` 版本， 详见[uni-app-vue2-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue2-tailwind-hbuilder-template)

或者下方也有一种 `Hack hbuilderx vue2 Way` 来在 `hbuilderx` `vue2` 项目中，使用 `webpack5` 和 `postcss8`

<!-- 另外出于开发体验的角度，还是推荐使用 `vscode` 作为你的开发工具，`hbuilderx` 只用于进行原生发布调试与 `ucloud` 部署用。 -->

## Hbuilderx 与 uni-app cli 环境汇总

首先，你需要知道你的项目究竟使用的是什么打包工具，截止今天 `2023/12/18` 目前如下所示:

|                  | webpack  | vite | postcss  |
| ---------------- | -------- | ---- | -------- |
| hbuilderx vue2   | webpack4 | x    | postcss7 |
| uni-app cli vue2 | webpack5 | x    | postcss8 |
| hbuilderx vue3   | x        | √    | postcss8 |
| uni-app cli vue3 | x        | √    | postcss8 |

也就是说，目前 `hbuilderx vue2` 的项目是最老的，无法使用最新版本的 `tailwindcss`，其他都可以使用。

## hbuilderx vue2 webpack4 postcss7 版本模板

如果你实在必须在 `hbuilderx vue2` 的项目中使用 `tailwindcss`，那么你可以使用下面的方法来使用 `tailwindcss`

详见 [uni-app-vue2-tailwind-hbuilder-template](https://github.com/icebreaker-trash/uni-app-vue2-tailwind-hbuilder-template)

## Hack hbuilderx vue2 Way

:::caution
以下方式为全局 Hack, 可能会在 `hbuilderx` 升级后出现问题
:::

`hbuilderx` 和 `hbuilderx alpha` 新建的 `vue2` 项目，发现它们的 `webpack` 版本被锁死在了 **`4`** ，我又用 `cli` 创建了一个 `vue2` 项目，发现已经是 `webpack5` 了，看起来只有 `cli` 创建的项目，会被默认升级 `webpack5`。

当然这并不意味着 `hbuilderx` 创建的 `vue2` 项目无法使用最新的这个插件，我们可以强行升级 `HBuilderX/plugins/uniapp-cli` 中的依赖，使得它适配 `webpack5`

> Macos uniapp-cli 路径在 /Applications/HBuilderX.app/Contents/HBuilderX/plugins/uniapp-cli
>
> Windows 的路径应该也在类似的地方，记得要先下载 vue2 的编译器，这个文件夹才有

来到 `uniapp-cli` 这个项目路径，执行 `yarn upgradeInteractive --latest` 升级项目依赖，重点升级 `@vue/cli-*` 相关包到 `5`

这时候 `webpack` 已经被升级到 `5` 版本了，然后你升级其他的 `loader` 到适配 `webpack5` 的版本(通常是最新版本)

再安装 `postcss` 和 `postcss-loader` 的最新版本，这时候你就把整个 `uni-app vue2` 项目的 `hbuilderx` 内置 `cli` 从 `webpack4`,`postcss7`变为了 `webpack5`,`postcss8` 了

不过代价是什么呢？那就是，这项改动是全局的！

你要想恢复设置，那只有重新安装 `uni-app vue2` 编译插件，或者重新安装整个 `hbuilderx`，所以这里还是推荐使用 `cli` 方式去创建项目，保证一个项目一个编译模式，你要节省空间就用 `pnpm`, 想用什么版本编译就用什么版本。

## 视频演示

<iframe src="//player.bilibili.com/player.html?aid=411561123&bvid=BV1EV41197Ps&cid=1413438914&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

---

## mpx (原生增强)


<ExternalClassesReminder framework="mpx" />

在 `vue.config.js` 中注册：

```js title="vue.config.js"
const { defineConfig } = require('@vue/cli-service')
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')

module.exports = defineConfig({
  // other options
  configureWebpack(config) {
    config.plugins.push(
      new UnifiedWebpackPluginV5({
        rem2rpx: true,
      })
    )
  }
})

```

## 引入 Tailwind CSS 样式

Tailwind 的底层样式需要显式导入。不同主版本的包结构略有差异：

### Tailwind CSS v3.x

仍然可以直接引用 Tailwind 提供的底层样式文件（带 `.css` 扩展名）：

```html title="src/app.mpx"
<style lang="scss">
  @import 'tailwindcss/base.css';
  @import 'tailwindcss/components.css';
  @import 'tailwindcss/utilities.css';
</style>
```

### Tailwind CSS v4.x

v4 官方改用了全新的 CSS 包结构，推荐直接引入 `weapp-tailwindcss` 提供的聚合样式文件：

```html title="src/app.mpx"
<style lang="scss">
  @import 'weapp-tailwindcss/index.css';
</style>
```

这样即可获得预置的 base / components / utilities，同时避免 `postcss-import` 误解析到 JS 入口导致构建报错。

## mpx 中的 vscode tailwindcss 智能提示缺失设置

我们知道 `tailwindcss` 最佳实践，是要结合 `vscode`/`webstorm`提示插件一起使用的。

假如你遇到了，在 `vscode` 的 `mpx` 文件中，编写 `class` 没有出智能提示的情况，可以参考以下步骤。

这里我们以 `vscode` 为例:

接着找到 `Tailwind CSS IntelliSense` 的 `扩展设置`

在 `include languages`,手动标记 `mpx` 的类型为 `html`

![如图所示](./img/vscode-tailwindcss.png)

保存设置，再去`mpx`文件里写`class`的时候，智能提示就出来啦。

---

## 原生开发(打包方案)


:::warning
注意！这是原生开发(**打包方案**)，假如你需要纯原生方案，请查看 [快速开始(纯原生)](/docs/quick-start/native/install)
:::

> 由于原生小程序没有 `webpack/vite/gulp` 工具链暴露出来，所以我们要添加这一套机制，来整个前端社区接轨，以此来实现更强大的功能。

:::tip
给原生小程序加入编译时这块 `webpack/vite/gulp` 等等工具，思路都是一样的，然而实现起来比较复杂，损耗精力，在此不提及原理。

更改模板工具链流程前，请确保你比较熟悉工具链开发（到我这样的水平就差不多了）。

另外这些模板，只需要稍微改一下产物后缀，添加 `tailwind.config.js` 的 `content` 就可以适配百度，头条，京东...各个平台。
:::

## gulp 模板

模板项目 [weapp-tailwindcss-gulp-template(gulp打包)](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/tree/main/demo/gulp-app)

## webpack5 模板

模板项目 [weapp-native-mina-tailwindcss-template(webpack打包)](https://github.com/sonofmagic/weapp-native-mina-tailwindcss-template)

## 组件样式的隔离性

:::tip
发现很多用户，在使用原生开发的时候，经常会问，为什么样式不生效。

这可能有以下几个原因:

1. 代码文件不在 `tailwind.config.js` 的 `content` 配置内
2. 原生小程序组件是默认开启 **组件样式隔离** 的，默认情况下，自定义组件的样式只受到自定义组件 wxss 的影响。而 `tailwindcss` 生成的工具类，都在 `app.wxss` 这个全局样式文件里面。不属于组件内部，自然不生效。

这时候可以使用:

```js
/* 组件 custom-component.js */
Component({
  options: {
    addGlobalClass: true,
  }
})
```

来让组件应用到 `app.wxss` 里的样式。

[微信小程序相关开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)

:::

## vscode tailwindcss 智能提示设置

我们知道 `tailwindcss` 最佳实践，是要结合 `vscode`/`webstorm`提示插件一起使用的。

假如你遇到了，在 `vscode` 的 `wxml` 文件中，编写 `class` 没有出智能提示的情况，可以参考以下步骤。

这里我们以 `vscode` 为例:

1. 安装 [`WXML - Language Services 插件`](https://marketplace.visualstudio.com/items?itemName=qiu8310.minapp-vscode)(一搜 wxml 下载量最多的就是了)

2. 安装 [`Tailwind CSS IntelliSense 插件`](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)

接着找到 `Tailwind CSS IntelliSense` 的 `扩展设置`

在 `include languages`,手动标记 `wxml` 的类型为 `html`

![如图所示](./img/vscode-setting.png)

智能提示就出来了:

![智能提示](./img/wxml-i.png)

---

## Rax (react)


在根目录下创建一个 `build.plugin.js` 文件，然后在 `build.json` 中注册：

```json title="build.json"
{
  "plugins": [
    "./build.plugin.js"
  ],
}
```

回到 `build.plugin.js`

```js title="build.plugin.js"
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
module.exports = ({ context, onGetWebpackConfig }) => {
  onGetWebpackConfig((config) => {
    config.plugin('UnifiedWebpackPluginV5').use(UnifiedWebpackPluginV5, [
      {
        rem2rpx: true,
      },
    ]);
  });
};

```

---

## Taro (所有框架)


目前 Taro v4 同时支持了 `Webpack` 和 `Vite` 进行打包编译，`weapp-tailwindcss` 这 `2` 者都支持，但是配置有些许的不同

:::caution
假如你写了 `tailwindcss` 工具类不生效，可能是由于微信开发者工具默认开启了 `代码自动热重载` 功能，关闭它即可生效。

假如你和 `NutUI` 一起使用，或者启用了 `@tarojs/plugin-html` 插件，请一定要查看这个[注意事项](/docs/issues/use-with-nutui)!

<!-- 有群友遇到了转义特殊字符失败，之后变成了空格的文件，结果 `node_modules` 删了重新安装就好了。 -->

:::

下列配置同时支持 `taro` 的 `react` / `preact` / `vue2` / `vue3` 所有框架

## 使用 Webpack 作为打包工具

### 注册插件

在项目的配置文件 `config/index` 中注册:

```js title="config/index.[jt]s"
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
// 假如你使用 ts 配置，则使用下方 import 的写法
// import { UnifiedWebpackPluginV5 } from 'weapp-tailwindcss/webpack'

{
  // 找到 mini 这个配置
  mini: {
    // postcss: { /*...*/ },
    // 中的 webpackChain, 通常紧挨着 postcss
    webpackChain(chain, webpack) {
      // 复制这块区域到你的配置代码中 region start
      // highlight-start
      chain.merge({
        plugin: {
          install: {
            plugin: UnifiedWebpackPluginV5,
            args: [{
              // 这里可以传参数
              rem2rpx: true,
            }]
          }
        }
      })
      // highlight-end
      // region end
    }
  }
}
```

然后正常运行项目即可，相关的配置可以参考模板 [taro-react-tailwind-vscode-template](https://github.com/sonofmagic/taro-react-tailwind-vscode-template)

:::info
`weapp-tailwindcss/webpack` 对应的插件 `UnifiedWebpackPluginV5` 对应 `webpack@5`

`weapp-tailwindcss/webpack4` 对应的插件 `UnifiedWebpackPluginV4` 对应 `webpack@4`

在使用 `Taro` 时，检查一下 `config/index` 文件的配置项 `compiler`，来确认你的 `webpack` 版本，推荐使用 `'webpack5'`

另外假如你使用了 [`taro-plugin-compiler-optimization`](https://www.npmjs.com/package/taro-plugin-compiler-optimization) 记得把它干掉。因为和它一起使用时，它会使整个打包结果变得混乱。详见 [issues/123](https://github.com/sonofmagic/weapp-tailwindcss/issues/123) [issues/131](https://github.com/sonofmagic/weapp-tailwindcss/issues/131)

<!-- 还有不要和 `terser-webpack-plugin` 一起注册使用，这会导致转义功能失效 详见 [**常见问题**](/docs/issues#taro-webpack5-环境下这个插件和-terser-webpack-plugin-一起使用会导致插件转义功能失效) 和 [issues/142](https://github.com/sonofmagic/weapp-tailwindcss/issues/142) -->

还有 `taro` 的 `prebundle` 功能老是出错，最近更新之后，由于 `prebundle` 默认开启，有时候连 `taro cli` 初始化的模板项目都跑不起来，假如遇到问题找不到原因，可以尝试关闭这个配置。

<!--
**另外不要开启二次编译缓存!**

```js
// 禁止二次编译缓存
cache: {
  enable: false
},
```

开启它会导致二次编译时，直接跳过插件的转义。另外还有一个 -->

<!-- `taro` 开发时热更新的问题，开发中保存 `tailwind.config.js` 文件，触发热更新会导致所有样式挂掉，此时重新保存任意 `jsx/tsx` 文件恢复正常。 -->

:::

## 使用 Vite 作为打包工具

<!-- :::danger
Taro Vite 目前存在一些 bug 还没有修复，不推荐使用!

下方注册方式会存在部分样式丢失的情况
::: -->

由于 `taro@4` 的 `vite` 版本，目前加载 `postcss.config.js` 配置是失效的，所以我们目前暂时只能使用内联 `postcss` 插件的写法

### 在 `config/index.ts` 中注册插件

```ts title="config/index.[jt]s"

const baseConfig: UserConfigExport<'vite'> = {
  // ... 其他配置
  // highlight-start
  compiler: {
    type: 'vite',
    vitePlugins: [
      {
        // 通过 vite 插件加载 postcss,
        name: 'postcss-config-loader-plugin',
        config(config) {
          // 加载 tailwindcss
          if (typeof config.css?.postcss === 'object') {
            config.css?.postcss.plugins?.unshift(tailwindcss())
          }
        },
      },
      uvtw({
        // rem转rpx
        rem2rpx: true,
        // 除了小程序这些，其他平台都 disable
        disabled: process.env.TARO_ENV === 'h5' || process.env.TARO_ENV === 'harmony' || process.env.TARO_ENV === 'rn',
        // 由于 taro vite 默认会移除所有的 tailwindcss css 变量，所以一定要开启这个配置，进行css 变量的重新注入
        injectAdditionalCssVarScope: true,
      })
    ] as Plugin[] // 从 vite 引入 type, 为了智能提示
  },
  // highlight-end
  // ... 其他配置
}
```

`tailwindcss` 即可注册成功，正常使用了

这段代码的意思为，在 `vite` 里注册 `postcss` 插件和 `vite` 插件

> `vite.config.ts` 只有在运行小程序的时候才会加载，`h5` 不会，所以只能通过这种方式进行 `小程序` + `h5` 双端兼容

## 视频演示

<iframe src="//player.bilibili.com/player.html?aid=966499437&bvid=BV1UW4y1w7VM&cid=1411385502&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

---

## uni-app cli vue3 vite


:::warning
这是 `uni-app cli` 创建的项目的注册方式，如果你使用 `HbuilderX`，应该查看 [uni-app HbuilderX 使用方式](/docs/quick-start/frameworks/hbuilderx)
:::

## 注册插件

创建完成后，快速上手中的准备工作都完成之后，就可以便捷的注册了：

```js title="vite.config.[jt]s"

export default defineConfig({
  // uni 是 uni-app 官方插件， uvtw 一定要放在 uni 后，对生成文件进行处理
  plugins: [uni(),uvwt()],
  css: {
    postcss: {
      plugins: [
        // require('tailwindcss')() 和 require('tailwindcss') 等价的，表示什么参数都不传，如果你想传入参数
        // require('tailwindcss')({} <- 这个是postcss插件参数)
        require('tailwindcss'),
        require('autoprefixer')
      ],
    },
  },
});

```

这里只列举了插件的注册，包括`postcss`配置完整的注册方式，参考配置项文件链接: <https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template>

## 创建项目参考

`uni-app vite` 版本是 `uni-app` 最新的升级，它使用 `vue3` 的语法。

你可以通过 `cli` 命令创建项目 ([参考官网文档](https://uniapp.dcloud.net.cn/quickstart-cli.html)):

- 创建以 javascript 开发的工程（如命令行创建失败，请直接访问 gitee 下载模板）

```bash
npx degit dcloudio/uni-preset-vue#vite my-vue3-project
```

- 创建以 typescript 开发的工程（如命令行创建失败，请直接访问 gitee 下载模板）

```bash
npx degit dcloudio/uni-preset-vue#vite-ts my-vue3-project
```

> gitee 地址见上方的 `参考官网文档` 链接，点击跳转到 uni-app 官网即可

## 视频演示

<iframe src="//player.bilibili.com/player.html?aid=326378691&bvid=BV14w411773C&cid=1409199088&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

---

## 🔥 uni-app x


目前 `weapp-tailwindcss` 从 `4.2.0` 版本开始，插件已经支持 `uni-app-x` 同时构建包括 `web`,`小程序`, `安卓`,`IOS`,`鸿蒙` 五端项目

## 创建工具类

在项目中创建 `shared.js` 文件，用于存放一些工具函数：

```js title="shared.js"
const path = require('node:path')

function r(...args) {
  return path.resolve(__dirname, ...args)
}

module.exports = {
  r,
}
```

## 注册插件

创建 `vite.config.ts` 文件，注册插件：

> 这里特别注意 `uniAppX` 是从 `weapp-tailwindcss/presets` 这个预设中导出的

```js title="vite.config.[jt]s"

export default defineConfig({
    plugins: [
        uni(),
        UnifiedViteWeappTailwindcssPlugin(
            uniAppX({
                base: __dirname,
                rem2rpx: true,
            }),
        ),
    ],
    css: {
        postcss: {
            plugins: [
                tailwindcss({
                    config: r('./tailwind.config.js'),
                }),
            ]
        }
    }
});
```

## 更改 tailwindcss 配置

使用绝对路径，包括所有的提取文件

```js title="tailwind.config.js"
const { r } = require('./shared')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    r('./pages/**/*.{uts,uvue}'),
    r('./components/**/*.{uts,uvue}') 
  ],
  corePlugins: {
    preflight: false,
  },
}

```

## 现成模板可以直接使用或者参考

https://github.com/icebreaker-template/uni-app-x-hbuilderx

使用方式详见项目中的 `README.md`

---

## uni-app cli vue2 webpack


:::warning
这是 `uni-app cli` 创建的项目的注册方式，如果你使用 `HbuilderX`，应该查看 [uni-app HbuilderX 使用方式](/docs/quick-start/frameworks/hbuilderx)
:::

<ExternalClassesReminder framework="uni-app" />

:::tip
截止到 (2023/09/08)，目前所有的 `uni-app vue2 cli` 项目的 `webpack` 版本，已经切换到了 `webpack@5`，`@vue/cli@5`，`postcss@8` 了

另外如果你有旧有的 `uni-app webpack4` 项目需要迁移到 `webpack5`，可以看这篇 [旧有uni-app项目升级webpack5指南](/docs/upgrade/uni-app)
:::

```js title="vue.config.js"
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
/**
 * @type {import('@vue/cli-service').ProjectOptions}
 */
const config = {
  // some option...
  // highlight-start
  configureWebpack: (config) => {
    config.plugins.push(
      new UnifiedWebpackPluginV5({
        rem2rpx: true,
      })
    )
  }
  // highlight-end
  // other option...
}

module.exports = config
```

这样所有的配置便完成了！赶紧启动你的项目试试吧！

---

## tailwindcss 多上下文与独立分包


你看过动漫《百兽王》吗？《百兽王》的主人公是五个飞行员，他们分别驾驶黑、红、青、黄、绿五头机器狮，它们平时可以单独进行作战，遇到强敌时，也能进行五狮合体，成为巨大机器人“百兽王”。

同样，在日常开发中，我们经常遇到这样的问题，一个很大的程序，它有很多个独立的部分组成，每一个部分可以单独运行，也有独立的入口，相互之间没有任何的依赖，但是它们在同一个项目/任务里进行构建。

在这种场景下，去使用 `tailwindcss` 就往往需要去创建多个上下文，让这些上下文各自去管理我们程序中的指定的一块区域。

当然我写到这，相信大家也啥都没看懂，于是我搬出一个小程序中，独立分包的示例，来让大家理解这种思想。

## 什么是独立分包

独立分包是小程序中一种特殊类型的分包，可以独立于主包和其他分包运行。从独立分包中页面进入小程序时，不需要下载主包。当用户进入普通分包或主包内页面时，主包才会被下载。

独立分包属于分包的一种。普通分包的所有限制都对独立分包有效。独立分包中插件、自定义组件的处理方式同普通分包。此外，使用独立分包时要注意：

1. 独立分包中不能依赖主包和其他分包中的内容，包括 js 文件、template、wxss、自定义组件、插件等（使用 分包异步化 时 js 文件、自定义组件、插件不受此条限制）
2. 主包中的 `app.wxss` 对独立分包无效，应避免在独立分包页面中使用 `app.wxss` 中的样式；
3. App 只能在主包内定义，独立分包中不能定义 App，会造成无法预期的行为；
4. 独立分包中暂时不支持使用插件。

> 更多信息详见 [微信独立分包官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/independent.html)

---

这里要特别注意第二条: **主包中的 `app.wxss` 对独立分包是无效的!!!**

在我之前提供的`tailwindcss`小程序模板的示例中，所有 `tailwindcss` 生成的 `wxss` 工具类都是在主包里共用的 (`app.wxss`)，这在大部分情况下运转良好，然而这在独立分包场景下，是不行的！因为主包的样式无法影响到独立分包。

那么应该怎么做才能解决这个问题呢？

## 创建与配置示例

这里笔者先以 `taro@3.6.7` 和 `weapp-tailwindcss@2.5.2` 版本的项目作为示例。

首先配置好 `weapp-tailwindcss` 的配置，然后在 `config/index.js` 中关闭 `prebundle` 功能，因为这在独立分包场景下会报一些未知的错误:

```js
const config = {
  compiler: {
    prebundle: {
      enable: false,
    },
    type: 'webpack5'
  },
  // .....
}
```

其次关闭插件对 `tailwindcss css var` 主块的寻址行为：

```js
chain.merge({
  plugin: {
    install: {
      plugin: UnifiedWebpackPluginV5,
      args: [{
        // 方法1: 不要传 appType
        // 注释掉 appType : 'taro'
        // 或者方法2: 让所有css chunk 都是 main chunk
        // mainCssChunkMatcher: ()=> true
        // 2 种选其一即可
      }]
    }
  }
})
```

接下来我们就可以创建一个独立分包 `moduleA`，在里面新建一个 `"pages/index"` 页面，并写入一个只属于 `moduleA` 的独一无二的 `tailwindcss class`，然后在 `app.config.ts` 里注册它:

```js
  subpackages: [
    {
      root: "moduleA",
      pages: [
        "pages/index",
      ],
      // 下方这个标志位，声明独立分包
      independent: true
    },
  ]
```

到这里，准备工作就完成了，接下来就可以设计方案了。

## 单 `tailwindcss` 上下文的方案（不完美不推荐）

这个方案是一个不完美的方案，在这里写出来是为了促进大家对 `tailwindcss` 的理解。

首先在独立分包中，也创建一个 `index.scss` 内容为:

```css
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';
```

然后在所有独立分包中的页面引用它，这样打包之后，独立分包里的 `tailwindcss` 样式也就生效了。

然而这种方式有一个巨大的问题，就是它会带来严重的 `css` 冗余。

因为此时 `tailwindcss` 上下文有且仅有一个，它会把在这个项目中，所有提取出来的 `css` 工具类，全部注入到所有的 `@tailwind` 指令里去。`@import 'tailwindcss/utilities'` 这个引入(本质实际上是`@tailwind`指令)一下子膨胀了起来。

这导致了，主包里的 `app.wxss` 里，会包含主包里所有的 `class` + 独立分包里所有的 `class`，而独立分包里的 `index.scss` 里，也包含主包里所有的 `class` + 独立分包里所有的 `class`!

这显然是不可接受的，因为主包是没有必要包含独立分包的 `class`，而独立分包里，也没有必要包含主包里的 `class`! 这只会白白增大打包后`wxss`文件的体积。

所以这个方案需要改进!

## 多 `tailwindcss` 上下文的方案

由于上面那个方案的问题，我们开始改进，就必须要创建多个 `tailwindcss` 上下文。

那么第一步就是要 **`↓`**

### 创建多个 `tailwind.config.js`

比如说我们只有一个独立分包，所以我们创建了2个 `tailwind.config.js`:

1. `tailwind.config.js` 用于主包以及相互依赖的子包
2. `tailwind.config.sub.js` 用于 `moduleA` 这个独立分包

内容如下:

#### 独立分包的上下文配置

```js
// `moduleA` 这个独立分包的 tailwind.config.sub.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  // 这里只提取 moduleA 这个独立分包下的文件内容
  content: ["./src/moduleA/**/*.{html,js,ts,jsx,tsx}"],
  // ....
  corePlugins: {
    preflight: false
  }
}
```

#### 主包以及相互依赖的子包的上下文配置

```js
// 主包以及相互依赖的子包的 tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  // https://github.com/mrmlnc/fast-glob
  // 这里需要限定范围，不去提取 moduleA 这个独立分包下的文件内容
  // 所以后面跟了一个 `!` 开头的路径
  content: [
    "./src/**/*.{html,js,ts,jsx,tsx}",
    // 不提取独立分包里的 class
    "!./src/moduleA/**/*.{html,js,ts,jsx,tsx}"],
  // ....
  corePlugins: {
    preflight: false
  }
}
```

这样 `2` 个配置文件创建好了，接下来就要通过配置让它们各自在打包中生效。

### `postcss.config.js` 配置

这是非常重要的一块配置，我们需要把 `postcss.config.js` 的配置变成一个函数，这样才能把构建时的上下文传入进来：

```js
const path = require('path')

module.exports = function config(loaderContext) {
  // moduleA 下面的所有 scss 文件，都是独立模块的，应用不同的 tailwindcss 配置
  const isModuleA = /moduleA[/\\](?:\w+[/\\])*\w+\.scss$/.test(
    loaderContext.file
  )
  // 多个独立子包同理，加条件分支即可
  if (isModuleA) {
    return {
      plugins: {
        tailwindcss: {
          config: path.resolve(__dirname, 'tailwind.config.sub.js')
        },
        autoprefixer: {},
      }
    }
  }

  return {
    plugins: {
      // 不传默认取 tailwind.config.js
      tailwindcss: {},
      autoprefixer: {},
    }
  }
}
```

通过这种方式，我们成功的创建了 `2` 个不同的 `tailwindcss` 上下文，此时你进行打包之后，会发现

主包里的 `app.wxss` 和独立分包里的 `index.wxss`，里面的内容就已经各归各了，不再相互包含了。

## 尾言

当然，上面只是一种方案，达到这样的目的方式有很多种，比如你可以在运行时去修改 `postcss-loader` 对它进行劫持，或者拆成多个项目，分开构建。

我这篇文章只是抛砖引玉，相信聪明的你们一定可以举一反三的。

## 参考示例

示例见:<https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/taro-app>

---

## 1. 安装与配置 tailwindcss


> 请确保你的 `nodejs` 版本 `^18.17.0 || >=20.5.0`。目前低于 `18` 的长期维护版本(`偶数版本`) 都已经结束了生命周期，建议安装 `nodejs` 的 `LTS` 版本，详见 [nodejs/release](https://github.com/nodejs/release)。
>
> 假如你安装的 `nodejs` 太新，可能会出现安装包不兼容的问题，这时候可以执行安装命令时，使用 `--ignore-engines` 参数进行 `nodejs` 版本的忽略 。

首先安装本插件前，我们需要把 `tailwindcss` 对应的环境和配置安装好。

这里我们参考 `tailwindcss` 官网中 `postcss` 的使用方式进行安装 ([参考链接](https://tailwindcss.com/docs/installation/using-postcss))

## 1. 使用包管理器安装 `tailwindcss`

```bash npm2yarn
# 安装 tailwindcss@3 版本的依赖
npm i -D tailwindcss@3 postcss autoprefixer
```

```bash npm2yarn
# 初始化 tailwind.config.js 文件
npx tailwindcss init
```

:::info
`tailwindcss` 最新版本(`3.x`)对应的 `postcss` 大版本为 `8`，假如你使用像 `uni-app` 或 `taro` 这样的跨端框架，大概率已经内置了 `postcss` 和 `autoprefixer`
:::

## 2. 在项目目录下创建 `postcss.config.js` 并注册 `tailwindcss`

> 注意：这只是比较普遍的注册方式，各个框架很有可能是不同的! 比如 `uni-app vue3 vite` 项目就必须要内联注册 `postcss` 选项! 详见下方的注意事项

```js title="postcss.config.js"
// 假如你使用的框架/工具不支持 postcss.config.js 配置文件，则可以使用内联的写法
module.exports = {
  plugins: {
    tailwindcss: {},
    // 假如框架已经内置了 `autoprefixer`，可以去除下一行
    autoprefixer: {},
  }
}
```

:::tip 注意事项
`uni-app vite vue3` 项目，必须在`vite.config.ts` 文件中，使用 `postcss` 内联的写法注册插件。相关写法可以参考我的这个模板项目: [uni-app-vite-vue3-tailwind-vscode-template](https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template)。

而 `uni-app vue webpack5` 项目中的 `postcss.config.js`，在默认情况下，已经预置很多插件在里面，配置比较繁杂，可以参考这个文件 [uni-app-webpack5/postcss.config.js](https://github.com/sonofmagic/weapp-tailwindcss/blob/main/demo/uni-app-webpack5/postcss.config.js)
:::

## 3. 配置 `tailwind.config.js`

`tailwind.config.js` 是 `tailwindcss` 的配置文件，我们可以在里面配置 `tailwindcss` 的各种行为。

```js title="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
  // 这里给出了一份 uni-app /taro 通用示例，具体要根据你自己项目的目录结构进行配置
  // 不在 content 包括的文件内，你编写的 class，是不会生成对应的css工具类的
  content: ['./public/index.html', './src/**/*.{html,js,ts,jsx,tsx,vue}'],
  // 其他配置项
  // ...
  corePlugins: {
    // 小程序不需要 preflight，因为这主要是给 h5 的，如果你要同时开发小程序和 h5 端，你应该使用环境变量来控制它
    preflight: false
  }
}
```

## 4. 引入 `tailwindcss`

在你的项目入口引入 `tailwindcss` 使它在小程序全局生效

### uni-app

比如 `uni-app` 的 `App.vue` 文件:

```html title="App.vue"
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
/* 使用 scss */
/* @import 'tailwindcss/base'; */
/* @import 'tailwindcss/utilities'; */
/* @import 'tailwindcss/components'; */
</style>
```

:::warning

千万不要在 `uni.scss` 中去引入 `tailwindcss`, `uni.scss` 本质上走的是 `scss.additionalData`, 它会在每一个 `scss` 文件的开头，都去添加 `uni.scss` 里的文件内容

所以这相当于你每个 `scss`/ `vue` 文件里面，都加了 `tailwindcss` 引入，那 `css` 体积就爆炸了

:::

### Taro

又或者 `Taro` 的 `app.scss` 文件:

```scss title="app.scss"
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

// sass 版本1.25+ 使用 @use
// @use 'tailwindcss/base';
// @use 'tailwindcss/components';
// @use 'tailwindcss/utilities';

// 非 scss 的纯 css 文件，下列写法也是可以生效的
// @tailwind base;
// @tailwind components;
// @tailwind utilities;
```

然后在 `app.ts` 里引入这个样式文件即可。

这样 `tailwindcss` 的安装与配置就完成了，接下来让我们进入第二个环节：安装 `weapp-tailwindcss`。

## 参考链接

[`tailwindcss` 官方配置项](https://tailwindcss.com/docs/configuration)

---

## IDE 智能提示设置


## VS Code

> 首先，确保你已经安装 [`Tailwind CSS IntelliSense 插件`](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)

### 让 `Tailwind CSS IntelliSense` 识别 weapp-tailwindcss v4

`tailwindcss-intellisense` 在 v4 中必须看到 `@import "tailwindcss"` 才会将工作区视为 Tailwind 根文件。从 v4.7.10 起，`weapp-tailwindcss` 默认会在构建阶段把这些 `@import 'tailwindcss'` 自动改写成 `@import 'weapp-tailwindcss'`（可通过 `rewriteCssImports: false` 关闭）。这意味着你可以直接在项目入口写 `@import 'tailwindcss';` 以获得 IntelliSense，而插件会在最早的 PostCSS 流程中替换成小程序可用的样式。

如果仍希望与源码解耦，也可以使用 CLI 为 VS Code 生成一个仅供扩展使用的辅助 CSS：

```bash npm2yarn
npx weapp-tailwindcss vscode-entry --css src/app.css
```

- 默认输出在 `.vscode/weapp-tailwindcss.intellisense.css`，其中包含 `@import 'tailwindcss';`、常见的 `@source` globs 以及你传入的 CSS 入口（例如 `src/app.css`）。
- 该文件只用于激活 IntelliSense，不需要、也不应该被打包流程引用。
- 若需自定义文件名或额外的 `@source`，可通过 `--output`、`--source`、`--force` 等参数调整，运行 `npx weapp-tailwindcss vscode-entry --help` 查看全部选项。
- 如果不想生成独立文件，可以直接在真实入口写 `@import 'tailwindcss';`，默认启用的 `rewriteCssImports` 会让 webpack/vite 在 CSS 解析阶段把它映射到 `weapp-tailwindcss`（只影响样式导入，JS/TS `import 'tailwindcss'` 不会被修改）。

保存/重载任意文件后 VS Code 会检测到该辅助文件，从而让 `@import 'weapp-tailwindcss';` 的项目享受到完整的补全、悬浮和跳转体验。

### wxml 的智能提示

我们知道 `tailwindcss` 最佳实践，是要结合 `vscode`/`webstorm`提示插件一起使用的。

假如你遇到了，在 `vscode` 的 `wxml` 文件中，编写 `class` 没有出智能提示的情况，可以参考以下步骤。

这里我们以 `vscode` 为例:

安装 [`WXML - Language Services 插件`](https://marketplace.visualstudio.com/items?itemName=qiu8310.minapp-vscode)(一搜 wxml 下载量最多的就是了)

然后下方提供了 `2` 种方式, `全局设置` 和 `工作区设置`, 根据你的需求仍选其一即可

#### 全局设置

点击 `vscode` 左下角的设置图标里，通过搜索关键词 `tailwindcss` ，找到 `Tailwind CSS IntelliSense` 插件的 `扩展设置`

在 `include languages`,手动标记 `wxml` 的类型为 `html`

![如图所示](./frameworks/img/vscode-setting.png)

智能提示就出来了:

![智能提示](./frameworks/img/wxml-i.png)

#### 工作区设置

在你的打开的工作区目录的根目录里，创建 `.vscode` 文件夹，然后添加 `settings.json` 内容如下:

```json
{
  "tailwindCSS.includeLanguages": {
    "wxml": "html"
  }
}
```

这样就通过你工作区的 `vscode` 设置，去覆盖了你全局的 `vscode` 设置，也能够达到上图中的效果。

### js,jsx,ts,tsx,vue...这类文件的智能提示

#### 场景

在安装配置好插件后，我们在写代码时，写到那些标签中的 `class=`,`className=`，这种场景时，智能提示一下子就可以出来。

然而我们在写 `js` 代码的时候，很多时候是直接在代码里，去写 `tailwindcss` 字符串字面量，比如:

```jsx
const clsName = 'bg-[#123456] text-[#654321]'

return 
```

写这种字符串是没有任何的智能提示的，怎么办呢？

#### 解决方案

这里给出一种基于插件的解决方案：

1. 安装 `clsx`:

```bash npm2yarn
npm i clsx
```

2. 进入你的 `vscode` 设置的 [`settings.json`](https://code.visualstudio.com/docs/getstarted/settings)

在里面加入下方的配置:

```json
{
  "tailwindCSS.experimental.classRegex": [
    [
      "clsx\\(([^)]*)\\)",
      "(?:'|\"|`)([^']*)(?:'|\"|`)"
    ]
  ]
}
```

这样配置之后，智能提示就出来了:

![智能提示](./frameworks/img/js-intelliSense.png)

[Refer link](https://github.com/lukeed/clsx#tailwind-support)

#### 存在问题

这种原理也是依赖正则匹配，即 `Tailwind CSS IntelliSense 插件` 匹配到了当前 `vscode` 活动的文本域中，存在着 `clsx()` 方法这个关键词，所以就把智能提示给注入进去。

所以你这样写就不会生效:

```js

const btn = AAA('')
```

另外，你可以依据这个特性，修改/添加 `"tailwindCSS.experimental.classRegex"` 里的正则，然后自行封装一个方法，用来进行 `tailwindcss` 的智能提示。

## WebStorm

> 和 `vscode` 方式类似，同样使用 `clsx` 函数

1. 确保你的版本大于等于 [WebStorm 2023.1](https://www.jetbrains.com/webstorm/whatsnew/#version-2023-1-tailwind-css-configuration)

2. 打开设置，前往 [Languages and Frameworks | Style Sheets | Tailwind CSS](https://www.jetbrains.com/help/webstorm/tailwind-css.html#ws_css_tailwind_configuration)

3. 添加以下的配置:

```json
{
  "experimental": {
    "classRegex": ["clsx\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  }
}
```

> 如果你使用 `class-variance-authority` 的 `cva` 函数，只需再添加 `"cva\\(([^)]*)\\)"` 正则即可。

## HbuilderX

<https://ext.dcloud.net.cn/plugin?id=8560>

---

## 1. 安装与配置 tailwindcss(Native)


## 前言

很荣幸，我们在 `weapp-tailwindcss@3.2.0` 版本开始，引入了微信小程序原生支持的能力。 (其他平台的原生小程序开发，也非常容易兼容)

接下来让我们看看，如何进行使用吧！

本教程演示的是，使用微信开发者工具创建的原生 `js` 小程序，以及原生 `js` `skyline` 小程序使用 `tailwindcss` 的方式

### 运行环境

请确保你的 `nodejs` 版本 `>=16.6.0`。目前低于 `16` 的长期维护版本(`偶数版本`) 都已经结束了生命周期，建议安装 `nodejs` 的 `LTS` 版本，详见 [nodejs/release](https://github.com/nodejs/release)。

假如你安装的 `nodejs` 太新，可能会出现安装包不兼容的问题，这时候可以执行安装命令时，使用 `--ignore-engines` 参数进行 `nodejs` 版本的忽略 。

## 创建项目

打开微信开发者工具, 点击 `+` 创建一个项目，依次选择:

0. `AppID` 使用测试号
1. 开发模式: `小程序` 
2. 后端服务: `不使用云服务` 
3. 模板选择: 第二项选择 `基础`
4. 选择 `JS 基础模板`

![](/img/create-project.png)

> 使用 JS 基础模板创建的项目，依然可以使用 `Typescript`

首先安装本插件前，我们需要把 `tailwindcss` 对应的环境和配置安装好。

## 0. 初始化 `package.json`

首先，假如你使用原生的 JS 模板创建的项目。

在创建的项目目录下，是没有 `package.json` 文件 (`原生的 TS 模板有这个文件`), 你需要执行命令:

`npm init -y`，快速创建一个 `package.json` 文件在你的项目下

## 1. 使用包管理器安装 `tailwindcss`

然后执行:

```bash npm2yarn
# 安装 tailwindcss@3 版本的依赖
npm i -D tailwindcss@3 postcss autoprefixer
```

```bash npm2yarn
# 初始化 tailwind.config.js 文件
npx tailwindcss init
```

这样 `tailwindcss` 就被安装到你项目本地了

## 2. 配置 `tailwind.config.js`

`tailwind.config.js` 是 `tailwindcss` 的配置文件，我们可以在里面配置 `tailwindcss` 的各种行为。

这里给出了一份 `JS微信小程序` 通用示例，具体要根据你自己项目的目录结构进行配置

```js title="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // 添加你需要提取的文件目录
    'components/**/*.{wxml,js,ts}',
    'pages/**/*.{wxml,js,ts}',
    // 不要使用下方的写法，这会导致 vite 开发时监听文件数量爆炸
    // '**/*.{js,ts,wxml}', '!node_modules/**', '!dist/**'
  ],
  // 假如你使用 ts 模板，则可以使用下方的配置
  // content: ['miniprogram/**/*.{ts,js,wxml}'],
  corePlugins: {
    // 小程序不需要 preflight 和 container，因为这主要是给 h5 的，如果你要同时开发小程序和 h5 端，你应该使用环境变量来控制它
    preflight: false,
    container: false,
  }
}
```

## 3. 在项目目录下创建 `postcss.config.js` 并注册 `tailwindcss`

内容如下:

```js title="postcss.config.js"
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  }
}
```

> 这个文件和 `tailwind.config.js` 平级

## 4. 引入 `tailwindcss`

在你的小程序项目入口 `app.wxss` 文件中，引入 `tailwindcss` 使它在小程序全局生效

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

在 `app.wxss` 加入这一段代码之后，微信开发者工具会报错。不用担心，这是因为我们还没有完全配置好。

接下来，赶紧进入下一步，安装 `weapp-tailwindcss` 并运行吧！

---

## 2. 安装这个插件并运行


## 安装插件

在项目目录下，执行:

```bash npm2yarn
npm i -D weapp-tailwindcss weapp-vite
```

这样 `weapp-tailwindcss` 和 `weapp-vite` 就被安装在你的本地了

## 执行初始化命令

在命令行中运行

```sh
npx weapp-vite init
```

这个命令会对现有的原生小程序项目，进行 `weapp-vite` 的初始化

执行后，会发现主要有许多文件改动，`CLI` 主要做了 `3` 件事情:

- 创建 `vite.config.ts` 文件，这个是 `weapp-vite` 和 `vite` 的配置文件
- 修改 `package.json`, 添加 `dev` 和 `build` 开发和构建脚本，还有构建 `npm` 和打开微信开发者工具
- 修改 `project.config.json` 内容，来适配构建产物
- 添加适配 vite 的 `dts` 和 `tsconfig.json`

## 安装所有的依赖包

在执行完成 `weapp-vite init` 初始化命令之后，我们需要在项目里执行一下安装命令:

```bash npm2yarn
npm i
```

## 注册插件

给 `package.json` 添加下列脚本:
```json title="package.json"
{
  "scripts": {
    "postinstall": "weapp-tw patch"
  }
}

```

然后在你的 `vite.config.ts` 里对插件进行注册:

```ts title="vite.config.ts"

export default defineConfig({
  // highlight-start
  plugins: [
    uvwt({
      rem2rpx: true,
    }),
  ],
  // highlight-end
})

```

## 开始运行

使用 `npm run dev` 进入开发模式, 此模式带有热更新的，主要用于开发

使用 `npm run build` 进行构建

不论是 `npm run dev` 还是 `npm run build`, 他们的构建产物，都在工程目录下的 `dist` 目录

使用微信开发者工具，直接导入工程目录，然后即可预览效果！

> 注意不是导入 `dist` 目录，是你工程的根目录! 通常是 `dist` 的父级目录，不要搞错了！

## 配置好的模板

假如你配置不成功，你可以参考以下模板进行配置文件对比:

[weapp-vite-tailwindcss-template](https://github.com/weapp-vite/weapp-vite/tree/main/apps/weapp-vite-tailwindcss-template)

或者直接执行命令:

```bash npm2yarn
npx weapp-vite create my-app
```

此命令会在当前目录下，创建一个目录名为 `my-app` 的 `weapp-vite` + `weapp-tailwindcss` 集成模板

{/* [vite-native](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/apps/vite-native) */}

{/* [native-weapp-tailwindcss-template](https://github.com/sonofmagic/native-weapp-tailwindcss-template) */}

## 原生组件样式的隔离性

:::tip
发现很多用户，在使用原生开发的时候，经常会问，为什么 `tailwindcss` 样式对自定义组件不生效。

这可能有以下几个原因:

1. 代码文件不在 `tailwind.config.js` 的 `content` 配置内
2. 原生小程序组件是默认开启 **组件样式隔离** 的，默认情况下，自定义组件的样式只受到自定义组件 `wxss` 的影响。而 `tailwindcss` 生成的工具类，都在 `app.wxss` 这个全局样式文件里面。不属于组件内部，自然不生效。

这时候可以在你组件的 `json` 文件配置中，设置下面一行 `styleIsolation` 来开启样式共享:

```json title="custom-component.json"
{
  "styleIsolation": "apply-shared"
}
```

> `apply-shared` 表示页面 `wxss` 样式将影响到自定义组件，但自定义组件 `wxss` 中指定的样式不会影响页面；

来让组件应用到 `app.wxss` 里的样式。

更多的文档详见: [微信小程序相关开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)

:::

## 想了解更多 weapp-vite

更多场景和配置，请查看 [weapp-vite 文档网站](https://vite.icebreaker.top/)

---

## 4. rem 转 rpx (或 px)


> 此为可选步骤，根据你自己的需求进行配置。通常此配置的值，是由你拿到的设计稿尺寸决定的。

## 为什么要配置 rem 转 rpx 呢？

这是因为 `tailwindcss` 里面工具类的长度单位，默认都是 `rem`，比如:

```css
.m-4 {
  margin: 1rem;
}
.h-4 {
  height: 1rem;
}
/*......*/
```

`rem`这个单位在 `h5` 环境下自适应良好，但小程序环境下，我们大部分都是使用 `rpx` 这个 `wxss` 单位来进行自适应，所以就需要把默认的 `rem` 单位转化成 `rpx`。

## 三种转化方式(根据你的需求选其一即可)

## 插件内置 rem 转 rpx 功能 (推荐)

在 `^3.0.0` 版本中，所有插件都内置了 `rem2rpx` 参数，默认不开启，要启用它只需将它设置成 `true` 即可

```js
// vite.config.js

UnifiedViteWeappTailwindcssPlugin({
  // ...other-options
  // highlight-next-line
  rem2rpx: true
})
// webpack
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
new UnifiedWebpackPluginV5({
  // ...other-options
  // highlight-next-line
  rem2rpx: true
})
```

设置为 `true` 相当于 `rem2rpx` 传入下方这样一个配置对象:

```js
{
  // 32 意味着 1rem = 16px = 32rpx
  rootValue: 32,
  // 默认所有属性都转化
  propList: ['*'],
  // 转化的单位,可以变成 px / rpx
  transformUnit: 'rpx'
}
```

:::tip
为什么 `rootValue` 默认值是 `32`?

这是因为开发微信小程序时, 设计师基本都使用 `iPhone6` 作为视觉稿的标准，此时 `1px = 2rpx`。

然后默认情况下 `1rem = 16px`，所以 `1rem = 16px = 32rpx`。

详见 [WXSS 尺寸单位](https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxss.html#%E5%B0%BA%E5%AF%B8%E5%8D%95%E4%BD%8D) 章节，
:::

当然你也可以自行传入一个 `object` 来进行更多配置，具体的配置项见 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel)

### 优势

这种方式 **最简单**，和插件集成度高，传入一个配置就好了。

## 外置 postcss 插件

<!-- 假如你想要把项目里，所有的 `rem` 都转化成 `rpx`，那么 `postcss plugin`: [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel) 适合你。 -->

<!-- 推荐第一种转化方式，这会把项目里所有你编写的，或者引入的第三方控件里的 `rem` 单位，全部转化为 `rpx`，同时这个包也提供了各种配置项，帮助你进行更加细致的操作。 -->

首先我们安装 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel)

```bash npm2yarn
npm i -D postcss-rem-to-responsive-pixel
```

安装好之后，把它注册进你的 `postcss.config.js` 即可:

```js title="postcss.config.js"
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
    'postcss-rem-to-responsive-pixel': {
      // 32 意味着 1rem = 32rpx
      rootValue: 32,
      // 默认所有属性都转化
      propList: ['*'],
      // 转化的单位,可以变成 px / rpx
      transformUnit: 'rpx'
      // postcss-rem-to-responsive-pixel@6 版本添加了 disabled 参数，用来禁止插件的转化
      // disabled: process.env.TARO_ENV === 'h5' || process.env.TARO_ENV === 'rn'
    }
  }
}
```

:::tip

一些用户在使用 `tarojs` 开发的时候，错误的把 `tailwindcss` 配置在了 `config/index.js` 的 `postcss` 里，导致不生效。

原因实际上是因为 `config/index.js` 的 `postcss`这个配置，只是用来配置 `tarojs` **内置** `postcss` 插件的参数。

要使用 `tailwindcss`，你需要在项目根目录，新建一个 `postcss.config.js`，然后把上面的代码写入进去。
:::

### 优势

这种方式 **最灵活**，你可以自由的决定 `postcss` 插件的加载顺序，也可以按你自己的策略按需加载插件 (比如特定目录下的样式才接受这个插件的转化)

## 外置 tailwindcss 插件

你想缩小一下范围，只把 `tailwindcss` 生成的工具类的单位，从 `rem` 转变为 `rpx`，那么我写的 `tailwindcss preset`: [tailwindcss-rem2px-preset](https://www.npmjs.com/package/tailwindcss-rem2px-preset) 适合你。

同样我们安装它：

```bash npm2yarn
npm i -D tailwindcss-rem2px-preset
```

然后在 `tailwind.config.js` 中，注册这个预设：

```js title="tailwind.config.js"
module.exports = {
  presets: [
    require('tailwindcss-rem2px-preset').createPreset({
      // 32 意味着 1rem = 32rpx
      fontSize: 32,
      // 转化的单位,可以变成 px / rpx
      unit: 'rpx'
    })
  ]
  // ...
}
```

这样即可完成 `tailwindcss` 默认工具类的 `rem` 转 `rpx` 的配置了。

### 优势

这种方式受影响范围 **最小**，因为 `preset` 方式处理 `tailwindcss`,不会把你写的其他样式里的 `rem` 转化成 `rpx`

## px 转 rpx

如果你也有 [`px 转 rpx`](/docs/quick-start/css-unit-transform) 的需求，你可以查看 [CSS 单位转化](/docs/quick-start/css-unit-transform) 这个章节。

---

## 2. 安装 weapp-tailwindcss


在项目目录下，执行:

```bash npm2yarn
npm i -D weapp-tailwindcss

# 假如 tailwindcss 在 weapp-tailwindcss 之后安装，可以手动执行一下 patch 方法
# npx weapp-tw patch
```

然后把下列脚本，添加进你的 `package.json` 的 `scripts` 字段里:

```json title="package.json"
 "scripts": {
    // highlight-next-line
   "postinstall": "weapp-tw patch"
 }
```

:::caution 使用 pnpm@10+
`pnpm@10` 默认只允许 `onlyBuiltDependencies` 中的包运行生命周期脚本。安装完本插件后，请执行 `pnpm approve-builds weapp-tailwindcss` 将其加入白名单，避免 `postinstall` 的 `weapp-tw patch` 被跳过。
:::

:::info
执行 `weapp-tw patch` 主要是做2件事情

### 1. 给当前你本地的 `tailwindcss` 打上支持 `rpx` 的补丁 (小程序特有单位，非 `web` 标准)。

否则你一旦使用像 `text-[14.43rpx]` 这样的任意值写法，生成出来的 `css` 样式就是 `color: 14.43rpx;`，显然是错误的。

它会被 `tailwindcss` 认为是一种颜色，从而导致生成错误，样式不生效。

详见 [rpx 任意值颜色或长度单位二义性与解决方案](/docs/issues/rpx-ambiguities)

### 2. 暴露 `tailwindcss` 运行上下文给 `webpack`/`vite`/`glup` 插件。

这样就能够在 `js` 中，和 `postcss` 插件进行通信，从而达到共享上下文的效果。

---

而添加上面一段 `npm scripts` 的用途是，利用 `npm hook`, 每次安装包后，都会自动执行一遍 `weapp-tw patch` 这个脚本。

这样即使 `tailwindcss` 更新了版本导致了补丁失效，也会在重新下载后，第一时间被打上。

如果你希望在补丁前“强制刷新 `tailwindcss-patch` 的缓存目录（如 `node_modules/.cache/tailwindcss-patch`）”，可以在命令后附加 `--clear-cache`：

```json title="package.json"
 "scripts": {
   "postinstall": "weapp-tw patch --clear-cache"
 }
```

默认不清理缓存，更加保守稳定；仅当怀疑缓存导致补丁未生效或版本不一致时再开启该参数。
:::

我们已经完成了这些步骤了，最后就是注册这个插件，到各个不同的框架里去，马上就好！

---

## uni-app 条件编译语法糖插件


> 版本需求 2.10.0+

## 这是什么玩意?

在 `uni-app` 里，存在一种类似宏指令的[样式条件编译写法](https://uniapp.dcloud.net.cn/tutorial/platform.html#%E6%A0%B7%E5%BC%8F%E7%9A%84%E6%9D%A1%E4%BB%B6%E7%BC%96%E8%AF%91):

```css
/*  #ifdef  %PLATFORM%  */
平台特有样式
/*  #endif  */
```

> uni-app `%PLATFORM%` 的所有取值可以参考这个[链接](https://uniapp.dcloud.net.cn/tutorial/platform.html#preprocessor)

在 `weapp-tailwindcss@2.10.0+` 版本中内置了一个 `css-macro` 功能，可以让你的 `tailwindcss` 自动生成带有条件编译的样式代码，来辅助你进行多平台的适配开发，效果类似如下方式:

```html
<!-- 默认 -->
<view class="ifdef-[H5||MP-WEIXIN]:bg-blue-400">Web和微信小程序平台蓝色背景</view>
<view class="ifndef-[MP-WEIXIN]:bg-red-500">非MP-WEIXIN平台红色背景</view>
<view class="ifdef-[MP-WEIXIN]:bg-blue-500 ifndef-[MP-WEIXIN]:bg-red-500">微信小程序为蓝色，不是微信小程序为红色<view>
<!-- 自定义 -->
<view class="wx:bg-blue-400 -wx:bg-red-400">微信小程序为蓝色，不是微信小程序为红色</view>
<view class="tt:bg-blue-400">头条小程序蓝色</view>
```

或者这样的条件样式代码:

```css
/*只在 H5 和 MP-WEIXIN, 背景为蓝色，否则为红色 */
.apply-test-0 {
  @apply ifdef-[H5||MP-WEIXIN]:bg-blue-400 ifndef-[H5||MP-WEIXIN]:bg-red-400;
}
/* 自定义 */
.apply-test-1 {
  @apply mv:bg-blue-400 -mv:bg-red-400 wx:text-blue-400 -wx:text-red-400;
}
```

让我们看看如何使用吧！

## 如何使用

这里需要同时配置 `tailwindcss` 和 `postcss` 的配置文件才能起作用，其中 `tailwindcss` 配置修改的方式大体类似， `uni-app` `vue2/3` `postcss`插件的注册方式，有些许不同:

### tailwind.config.js 注册

首先在你的 `tailwind.config.js` 注册插件 `cssMacro`:

#### Tailwind CSS 3.x 配置

```js
const cssMacro = require('weapp-tailwindcss/css-macro');
/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    /* 这里可以传入配置项，默认只包括 ifdef 和 ifndef */
    cssMacro(),
  ],
};
```

#### Tailwind CSS 4.x 配置

> v4 推荐直接在入口 CSS 中通过 `@plugin` 引入。

```css
/* tailwind.css */
@import "tailwindcss";
@plugin "weapp-tailwindcss/css-macro";

/* 可选：为常用平台创建语义别名 */
@utility platform-weixin:(value) {
  @apply ifdef-[MP-WEIXIN]:$(value);
}
@utility not-alipay:(value) {
  @apply ifndef-[MP-ALIPAY]:$(value);
}
```

若需要自定义更多静态变体，可额外保留一个 `tailwind.config.ts` 以传入参数：

```ts

export default {
  plugins: {
    cssMacro: cssMacro({
      variantsMap: {
        wx: 'MP-WEIXIN',
        '-wx': { value: 'MP-WEIXIN', negative: true },
      },
    }),
  },
}
```

> [!TIP]
> `cssMacro` 的动态变体（`ifdef:` / `ifndef:`）依赖 Tailwind 内置的 `matchVariant`，请确保 Tailwind 版本 ≥ 3.2；在 v4 中该 API 同样可用。

### postcss 插件注册

对应的 `postcss` 插件位置为 `weapp-tailwindcss/css-macro/postcss`

值得注意的是，你必须把这个插件，注册在 `tailwindcss` 之后和 `@dcloudio/vue-cli-plugin-uni/packages/postcss` 之前。

> `@dcloudio/vue-cli-plugin-uni/packages/postcss` 为 vue2 cli项目特有，vue3不用管。

注册在 `tailwindcss` 之后很好理解，我们在针对 `tailwindcss` 的产物做修改，自然要在它执行之后处理，注册在 `@dcloudio/vue-cli-plugin-uni/packages/postcss` 之前则是因为 `uni-app` 样式的条件编译，靠的就是它。假如在它之后去处理不久已经太晚了嘛。

> 这里提一下 postcss 插件的执行顺序，假如注册是数组，那就是按照顺序执行，如果是对象，那就是从上往下执行，详见[官方文档](https://www.npmjs.com/package/postcss-load-config#ordering)

#### uni-app vite vue3

```diff
// vite.config.ts 文件

// postcss 插件配置
const postcssPlugins = [require('autoprefixer')(), require('tailwindcss')()];
// ... 其他省略
+ postcssPlugins.push(require('weapp-tailwindcss/css-macro/postcss'));
// https://vitejs.dev/config/
export default defineConfig({
  plugins: vitePlugins,
  css: {
    postcss: {
      plugins: postcssPlugins,
    },
  },
});
```

> 可以参考这个项目的配置 [demo/uni-app-vue3-vite](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/uni-app-vue3-vite)

#### uni-app vue2

vue2 cli 项目默认会带一个 `postcss.config.js` 我们之间直接在里面注册即可:

```diff
const webpack = require('webpack')
const config = {
  parser: require('postcss-comment'),
  plugins: [
    // ...
    require('tailwindcss')({ config: './tailwind.config.js' }),
    // ...
+   require('weapp-tailwindcss/css-macro/postcss'),
    require('autoprefixer')({
      remove: process.env.UNI_PLATFORM !== 'h5'
    }),
+   // 注意在 tailwindcss 之后和 这个之前
    require('@dcloudio/vue-cli-plugin-uni/packages/postcss')
  ]
}
if (webpack.version[0] > 4) {
  delete config.parser
}
module.exports = config
```

> 可以参考这个项目的配置 [demo/uni-app](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/uni-app)

### 配置完成

现在配置好了这2个地方，目前你就可以直接使用 `ifdef` 和 `ifndef` 的条件编译写法了！

```html
<!-- 默认 -->
<view class="ifdef-[H5||MP-WEIXIN]:bg-blue-400">Web和微信小程序平台蓝色背景</view>
<view class="ifndef-[MP-WEIXIN]:bg-red-500">非MP-WEIXIN平台红色背景</view>
<view class="ifdef-[MP-WEIXIN]:bg-blue-500 ifndef-[MP-WEIXIN]:bg-red-500">微信小程序为蓝色，不是微信小程序为红色<view>
<!-- 自定义 -->
<view class="wx:bg-blue-400 -wx:bg-red-400">微信小程序为蓝色，不是微信小程序为红色</view>
<view class="tt:bg-blue-400">头条小程序蓝色</view>
```

不过你肯定会觉得这种默认写法很烦！要写很多，不要紧，我还为你提供了自定义的方式，接下来来看看配置项吧！

## 配置项

这里提供了一份示例，

> uni-app `%PLATFORM%` 的所有取值可以参考这个[链接](https://uniapp.dcloud.net.cn/tutorial/platform.html#preprocessor)

```js
const cssMacro = require('weapp-tailwindcss/css-macro');
/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    /* 这里可以传入配置项，默认只包括 ifdef 和 ifndef */
    cssMacro({
      // 是否包含 ifdef 和 ifndef，默认为 true
      // dynamic: true,
      // 传入一个 variantsMap
      variantsMap: {
        // wx 对应的 %PLATFORM% 为 'MP-WEIXIN'
        // 有了这个配置，你就可以使用 wx:bg-red-300
        wx: 'MP-WEIXIN',
        // -wx，语义上为非微信
        // 那就传入一个 obj 把 negative 设置为 true
        // 就会编译出 ifndef 的指令
        // 有了这个配置，你就可以使用 -wx:bg-red-300
        '-wx': {
          value: 'MP-WEIXIN',
          negative: true
        },
        mv: {
          // 可以使用表达式
          value: 'H5 || MP-WEIXIN'
        },
        '-mv': {
          // 可以使用表达式
          value: 'H5 || MP-WEIXIN',
          negative: true
        }
      }
    }),
  ],
};
```

## IDE智能提示

只要你使用 `vscode`/`webstorm` 这类IDE，加上安装了 `tailwindcss` 的官方插件。

智能提示会根据你对 `cssMacro` 这个插件的配置，直接生成出来！

> 假如没有下方的智能提示出现，有可能是 `tailwindcss` 插件挂了，这时候可以改好配置之后 **重启** `vscode` 以重新运行插件

这里我们以上面 `配置项` 为例:

### 动态提示: ifdef-[] 和 ifndef-[]

![macro-tip0](./img/macro-tip0.png)

### 配置的静态提示: wx 和 -wx

![macro-tip1](./img/macro-tip1.png)

---

## Tailwindcss 2.x


目前，有些用户由于现有的项目，已经是 `webpack 4`, `postcss 7.x` 且无法往上升级，但是又想要使用 `tailwindcss`, 

所以写了这个文档作为参考，在现有版本的情况下，**不推荐**任何的新项目使用

## 安装

在这种条件下，只能使用 `tailwindcss 2.x` 版本。

参考 https://v2.tailwindcss.com/docs/installation#post-css-7-compatibility-build 中的安装方式

安装好之后，一定要打开 `jit` 模式, https://github.com/icebreaker-trash/uni-app-vue2-tailwind-hbuilder-template/blob/master/tailwind.config.js

具体更多的细节，详见下方模板代码。

## vue2 hbuilderx 参考模板

注意，一定要在开发环境中设置 

```js
process.env.TAILWIND_MODE = "watch"
```

才能正常热更新

模板源代码地址:

https://github.com/icebreaker-template/uni-app-vue2-tailwind-hbuilder-template

---

## 初始化 package.json

## 1. 安装

```bash npm2yarn
# 初始化 package.json
npm init
# 安装包
npm install -D tailwindcss @tailwindcss/postcss weapp-tailwindcss
```

<Patch />

## 2. 添加 `vite.config.ts`

```ts title="vite.config.ts"

export default defineConfig({
  plugins: [
    uni(),
    UnifiedViteWeappTailwindcssPlugin({
      rem2rpx: true,
      tailwindcssBasedir: __dirname,
      cssEntries: [
        // 你 @import "weapp-tailwindcss"; 那个文件绝对路径
        path.resolve(__dirname, './src/app.css'),
      ],
    }),
  ],
  css: {
    postcss: {
      plugins: [
        tailwindcss({
          base: __dirname
        })
      ]
    }
  }
});
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。

## 3. 添加样式

<UniappHbuilderStyle/>

现在，在你的页面里面去随意的编写样式，比如 `bg-[#123456] text-[#654321]`, 然后运行到微信开发者工具即可

## 参考模板

- [uni-app-x-hbuilderx 模板](https://github.com/icebreaker-template/uni-app-x-hbuilderx) 

- [uni-app-hbuilderx 模板](https://github.com/icebreaker-template/uni-app-hbuilderx-tailwindcss-v4)

---

## UniappCliStyle

在 `src/app.css` 中引入 `weapp-tailwindcss`，这个文件会作为 `cssEntries` 的入口：

```css title="src/app.css"
@import "weapp-tailwindcss";
```

为了解决 IDE 智能提示问题，再额外创建一个 `main.css` 并引入 `weapp-tailwindcss/css`。

```css title="src/main.css"
@import "weapp-tailwindcss/css";
@source not "dist";
```

在项目目录下的 `App.vue` 中，添加以下内容：

```html title="App.vue"
<style src="./main.css"></style>
```

:::warning

千万不要在 `uni.scss` 中去引入 `tailwindcss`, `uni.scss` 本质上走的是 `scss.additionalData`, 它会在每一个 `scss` 文件的开头，都去添加 `uni.scss` 里的文件内容

所以这相当于你每个 `scss`/ `vue` 文件里面，都加了 `tailwindcss` 引入，那 `css` 体积就爆炸了

:::

---

## UniappHbuilderStyle

在 `src/app.css` 中引入 `weapp-tailwindcss`，这个文件会作为 `cssEntries` 的入口：

```css title="src/app.css"
@import "weapp-tailwindcss";
```

为了 IDE 智能提示，再额外创建一个 `main.css` 并引入 `weapp-tailwindcss/css`。

```css title="src/main.css"
@import "weapp-tailwindcss/css";
@source not "unpackage";
```

在项目目录下的 `App.vue` / `App.uvue`(uni-app x 项目) 然后添加以下内容：

```html title="App.vue"
<style src="./main.css"></style>
```

> 添加 `@source not "unpackage";` 是为了避免 `HBuilderX` 差量编译死循环问题

:::warning

千万不要在 `uni.scss` 中去引入 `tailwindcss`, `uni.scss` 本质上走的是 `scss.additionalData`, 它会在每一个 `scss` 文件的开头，都去添加 `uni.scss` 里的文件内容

所以这相当于你每个 `scss`/ `vue` 文件里面，都加了 `tailwindcss` 引入，那 `css` 体积就爆炸了

:::

---

## Mpx


## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

<Patch />

## 配置

更改 `mpx.config.js` 注册 `weapp-tailwindcss`

```js title="mpx.config.js"
const { defineConfig } = require('@vue/cli-service')
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
const path = require('node:path')
const tailwindPostcss = require('@tailwindcss/postcss')
module.exports = defineConfig({
  outputDir: `dist/${process.env.MPX_CURRENT_TARGET_MODE}`,
  pluginOptions: {
    mpx: {
      plugin: {
        postcssInlineConfig: {
          // tailwindcss@4 需要在此处注册 @tailwindcss/postcss，详见 templates/mpx-tailwindcss-v4/mpx.config.js
          ignoreConfigFile: true,
          plugins: [tailwindPostcss()]
        },
        srcMode: 'wx',
        hackResolveBuildDependencies: ({ files, resolveDependencies }) => {
          const path = require('path')
          const packageJSONPath = path.resolve('package.json')
          if (files.has(packageJSONPath)) files.delete(packageJSONPath)
          if (resolveDependencies.files.has(packageJSONPath)) {
            resolveDependencies.files.delete(packageJSONPath)
          }
        }
      },
      loader: {}
    }
  },
  configureWebpack(config) {
    // 添加的代码在这里
    // highlight-start
    config.plugins.push(
      new UnifiedWebpackPluginV5({
        appType: 'mpx',
        rem2rpx: true,
        cssEntries: [
          // 你 @import "weapp-tailwindcss"; 那个文件绝对路径
          path.resolve(__dirname, './src/app.css'),
        ],
      })
    )
    // highlight-end
  }
})
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。
> tailwindcss@4 下必须在 `mpx.config.js` 里用 `postcssInlineConfig` 注册 `@tailwindcss/postcss`（同仓库 `templates/mpx-tailwindcss-v4/mpx.config.js` 的写法），否则插件不会生效，无需再单独维护 `postcss.config.js`。

## 添加样式

在 `src/app.css` 中引入 `weapp-tailwindcss`：

```css title="src/app.css"
@import "weapp-tailwindcss";
```

> 💡 如果你希望在任意样式文件中直接引用包内样式，请使用 `@import "weapp-tailwindcss/index.css";`。这样可以确保 `postcss-import` 解析到的是真实的 CSS 资源，避免出现 “Unknown word "use strict"” 这一类由于误解析到 JS 文件导致的构建报错。

### Tailwind CSS 样式引用指引

- **Tailwind CSS v3.x**：沿用旧模块名即可（例如 `@import 'tailwindcss/base.css'`、`@import 'tailwindcss/components.css'`、`@import 'tailwindcss/utilities.css'`）。
- **Tailwind CSS v4.x**：推荐直接引入 `weapp-tailwindcss` 提供的聚合样式：

```html title="src/app.mpx"
<style lang="scss">
  @import 'weapp-tailwindcss/index.css';
</style>
```

这样可以一次性获得 base / components / utilities，并规避 `postcss-import` 误解析 JS 入口的报错。如果你是从 v3 升级，只需将原来的三个 `@import` 换成这条语句即可。

然后在项目目录下，小程序全局的 `app.mpx` 中，通过 `@import` 引入该文件：

```html title="app.mpx"
<style lang="css">
@import "./app.css";
</style>
```

更改好配置之后，直接启动即可

## 参考模版

https://github.com/icebreaker-template/mpx-tailwindcss-v4

---

## Patch

然后把下列脚本，添加进你的 `package.json` 的 `scripts` 字段里:

```json title="package.json"
 "scripts": {
    // highlight-next-line
   "postinstall": "weapp-tw patch"
 }
```

:::caution 使用 pnpm@10+
`pnpm@10` 默认只允许 `onlyBuiltDependencies` 中的包运行生命周期脚本。安装完本插件后，请执行 `pnpm approve-builds weapp-tailwindcss` 将其加入白名单，避免 `postinstall` 的 `weapp-tw patch` 被跳过。
:::

这是为了给 `tailwindcss@4` 打上支持 `rpx` 单位的补丁，否则它会把 `rpx` 认为是一种颜色

如需在补丁前强制刷新 `tailwindcss-patch` 的缓存，可改为：

```json title="package.json"
 "scripts": {
   "postinstall": "weapp-tw patch --clear-cache"
 }
```

默认不清理缓存；只有当你怀疑缓存导致补丁未生效或目标不一致时，才需要添加 `--clear-cache`。***

---

## 开发参考手册


:::warning
由于 `tailwindcss@4.x` 本身还在快速的开发迭代中，即使是小版本也可能带有一些意外的 `Breaking Change`

所以以下内容可能会经常变更，如果发现已经过时，请提 `issue` 或者直接修复提 `pr`
:::

<!-- ## 出于兼容性考虑，请使用 `tailwindcss@3.x`

目前用户汇报了部分手机，可能是由于内部使用的 `webview` 版本太低，或者一些其他的因素，导致了样式不生效的问题，尤其是华为手机。

`tailwindcss@4.x` 生成的样式，对现代的浏览器来说刚刚好，可是对那些移动设备来说，就不一定了。 -->

所以假如你要兼容更多的手机机型，请使用 `tailwindcss@3.x`。

## 定位的变化: 样式预处理器

相对于 `tailwindcss@3` 版本， `tailwindcss@4` 存在定位的重大变更

它直接变成了一个样式预处理器，和原生 `css` 已经它的规范相结合，相辅相成。

所以你在 `4.x` 版本中，不应该让 `tailwindcss` 和 `sass`,`less`,`stylus` 一起使用

详见: https://tailwindcss.com/docs/compatibility#sass-less-and-stylus

## 集成选择

`tailwindcss` 集成上提供了多种选择 (`cli`,`vite`,`postcss`)，这里我们主要选择 `@tailwindcss/postcss`，原因如下:

1. `@tailwindcss/postcss` 兼容性更好，开发打包器使用 `vite` 和 `webpack` 的都能用，而 `@tailwindcss/vite` 这里只有 `vite` 能用。
2. `@tailwindcss/vite` 很容易和其他的 `vite` 插件起冲突，尤其是和 `uni-app` / `taro` 一起使用的时候，依赖注册的顺序和编译 `hook` 注册的顺序
3. `uni-app`/`taro` 这种框架，默认都是 `cjs` 加载的，而 `@tailwindcss/vite` 只提供了 `esm` 的版本，所以集成上可能会遇到问题
4. `tailwindcss@3.x` 是 `postcss` 插件，`@tailwindcss/postcss` 也是 `postcss` 插件，所以选择它，项目迁移升级的成本会更低。

所以，综合考虑下来，我们主要选择 `@tailwindcss/postcss`。

当然，你也完全可以使用 `uni-app vite vue3` + `@tailwindcss/vite` 这种组合。从编译速度出发, `@tailwindcss/vite` 会更快，但是可能需要一些额外的配置，行为也有可能和 `tailwindcss@3.x` 不一致。

## 小程序样式引入 `tailwindcss` 不同点

在小程序的样式文件中，引入 `tailwindcss` 的时候，需要把官方文档上写的 `@import "tailwindcss"` 替换为 `@import "weapp-tailwindcss"`。

```diff
- @import "tailwindcss";
+ @import "weapp-tailwindcss";
```

### 有什么区别?

`@import "weapp-tailwindcss"` 相比 `@import "tailwindcss"` 的主要区别是:

1. `"weapp-tailwindcss"` 没有 `"tailwindcss"` 中 `h5` `preflight` 的类(这些都是给 `h5` 用的，小程序用不到)
2. `"weapp-tailwindcss"` 中，不使用 `tailwindcss` 默认的 `@layer` 来控制样式优先级。这是因为小程序本身不支持 `css` `@layer` 这个特性，强行启用会造成一些样式难以覆盖的问题。

### 多端开发

假如你需要进行多端的开发，那么可以使用对应框架的样式条件编译写法，比如 `uni-app`:

```css
/*  #ifdef  H5  */
@import "tailwindcss";
/*  #endif  */
/*  #ifndef  H5  */
@import "weapp-tailwindcss";
/*  #endif  */
```

详见 https://uniapp.dcloud.net.cn/tutorial/platform.html

## css 作为配置文件

由于在 `tailwindcss@4` 中，配置文件默认为一个 `css` 文件，所以你需要显式的告诉 `weapp-tailwindcss` 你的入口 `css` 文件的绝对路径。

来让 `weapp-tailwindcss` 和 `tailwindcss` 保持一致的处理模式

> `cssEntries` 为一个数组，就是你 @import "weapp-tailwindcss"; 那些文件，可以有多个

```ts
{
  cssEntries: [
    // 就是你 @import "weapp-tailwindcss"; 那个文件
    // 比如 tarojs
    path.resolve(__dirname, '../src/app.css')
    // 比如 uni-app (没有 app.css 需要先创建，然后让 `main` 入口文件引入)
    // path.resolve(__dirname, './src/app.css')
  ],
}
```

假如不添加这个，会造成 `tailwindcss` 插件生成的样式，转义不了的问题。

> 插件会自动根据已安装的 Tailwind 版本开启 v4 模式。只有在调试自定义 `tailwindcss` 目录或多版本共存时，才需要在 `tailwindcss` 配置里手动指定 `version`。

## 使用 @apply

如果你想在 页面或者组件独立的 `CSS` 模块中使用 `@apply` 或 `@variant`，你需要使用 `@reference` 指令，来导入主题变量、自定义工具和自定义变体，以使这些值在该上下文中可用。

```css
/* 到你引入 weapp-tailwindcss 的 css 相对路径 */
@reference "../../app.css";
/* 如果你只使用默认主题，没有自定义，你可以直接 reference weapp-tailwindcss */
@reference "weapp-tailwindcss";
```

详见: https://tailwindcss.com/docs/functions-and-directives#reference-directive

## @layer 在小程序的降级方案

`tailwindcss@4` 使用原生的 `@layer` 去控制样式的优先级

> 如果你不知道什么是 `@layer`，你可以阅读这篇文档 https://developer.mozilla.org/zh-CN/docs/Web/CSS/@layer

但是像 `uni-app` / `taro` 这种框架，默认都是直接引入很多内置样式的。

于是就会出现下方尴尬的情况: 优先级 `(0,1,0)` 的 `class` 选择器样式无法覆盖 `(0,0,1)` 的标签选择器样式:

![](./tailwindcss-v4-uniapp-layer.png)

这种情况，你就非常需要兼容性降级方案，即使用 [`postcss-preset-env`](https://www.npmjs.com/package/postcss-preset-env) (`weapp-tailwindcss` 已经内置了这个插件了，你可以直接使用它的配置，详见 [cssPresetEnv](/docs/api/interfaces/UserDefinedOptions#csspresetenv))

这在开发需要兼容低版本移动端 h5 的时候很重要。

## 使用 pnpm

默认使用 `pnpm` 的时候，由于 `pnpm` 是无法使用幽灵依赖的

但是 `uni-app`/`taro` 出于一些历史原因，是需要幽灵依赖的，这时候可以在项目下创建 `.npmrc` 添加内容如下

```txt title=".npmrc"
shamefully-hoist=true
```

然后重新执行 `pnpm i` 安装包即可运行

## 智能提示

目前 `tailwindcss@4` 的 `vscode` 插件，会扫描目录下的 `css` 来获取 `tailwindcss` 的配置。

但是这里有个非常坑的点是，它不会去自动的扫描 `.vue` 文件里面的 `tailwindcss` 引入

这就导致，我们假如想在 `vue` 项目(比如 `uni-app`) 中获得智能提示，必须再随便创建一个 `main.css`，然后通过 `App.vue` 文件引入它

```css title="main.css"
@import "weapp-tailwindcss/css";
@source not "dist";
```

```html title="App.vue"
<style src="./main.css"></style>
```

## 如何去除 preflight 样式

在引入 `@import "weapp-tailwindcss"` 时，默认会引入 `preflight` 样式。

### 什么是 preflight 样式

一些全局的 `reset` 样式，用来让一些标签行为统一的，比如你在你的样式中，看到的:

```css
view,text,::before,::after,::backdrop {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
  border: 0 solid;
}
```

类似这样的就是 `weapp-tailwindcss` 给你的应用注入的 `preflight` 样式

### 解决方案

`@import "weapp-tailwindcss"` 本质上由三个部分组成:

```css
@import 'weapp-tailwindcss/theme.css';
@import 'weapp-tailwindcss/preflight.css';
@import 'weapp-tailwindcss/utilities.css';
```

所以想要去除 `preflight` 样式，只需像下面一样写即可

```diff
- @import "weapp-tailwindcss";
+ @import 'weapp-tailwindcss/theme.css';
+ @import 'weapp-tailwindcss/utilities.css';
```

## 使用大写单位 (h-[100PX]) 无效问题

默认情况下，在 `process.env.NODE_ENV === 'production'` 的时候， `tailwindcss` 会自动进入优化模式

它会进行 `CSS` 单位的校准，比如把大写的 `PX` 转化为小写的 `px`，你要禁用这个行为可以这样传入。

```js
export default {
  plugins: {
    "@tailwindcss/postcss": {
      optimize: false
    },
  }
}
```

详见: [@tailwindcss/postcss](https://github.com/tailwindlabs/tailwindcss/blob/7779d3d080cae568c097e87b50e4a730f4f9592b/packages/%40tailwindcss-postcss/src/index.ts#L73C35-L73C72)

---

## Taro vite


## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

> 这里不使用 `@tailwindcss/vite` 是由于 `taro` 配置没法加载纯 `esm` 不是 `cjs` 的包, 会爆错误 `No "exports" main defined`

<Patch />

## 配置

```js title="config/index.ts"

{
  compiler: {
    type: 'vite',
    vitePlugins: [
      {
        name: 'postcss-config-loader-plugin',
        config(config) {
          // 加载 tailwindcss
          if (typeof config.css?.postcss === 'object') {
            config.css?.postcss.plugins?.unshift(tailwindcss())
          }
        },
      },
      UnifiedViteWeappTailwindcssPlugin({
        rem2rpx: true,
        cssEntries: [
          // 你 @import "weapp-tailwindcss"; 那个文件绝对路径
          path.resolve(__dirname, '../src/app.css'),
        ],
      }),
    ]
  },
}
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。

> 这里使用 `vite` 插件直接去加载 `tailwindcss`，这是由于 `taro4 vite` 不会自动去加载项目下的 `postcss.config.js`，所以只能定义这个 `postcss-config-loader-plugin`

## 添加样式

在项目目录下的 `src/app.css` 中，添加以下内容：

```css title="src/app.css"
@import "weapp-tailwindcss";
```

更改好配置之后，直接运行启动项目，微信开发者工具导入这个项目，即可看到效果。

## 参考模板

https://github.com/icebreaker-template/taro-vite-tailwindcss-v4

---

## Taro webpack


## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

<Patch />

## 配置

### 在你的根目录创建 `postcss.config.mjs`

```js title="postcss.config.mjs"
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  }
}
```

### 在你的 `app.css` 里面添加

```css
@import "weapp-tailwindcss";
```

### 注册插件

在项目的配置文件 `config/index` 中注册:

```js title="config/index.[jt]s"

// 假如你使用 js 配置，则使用下方 require 的写法
// const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
// const path = require('node:path')

{
  // 找到 mini 这个配置
  mini: {
    // postcss: { /*...*/ },
    // 中的 webpackChain, 通常紧挨着 postcss 
    webpackChain(chain, webpack) {
      // 复制这块区域到你的配置代码中 region start
      // highlight-start
      chain.merge({
        plugin: {
          install: {
            plugin: UnifiedWebpackPluginV5,
            args: [{
              // 这里可以传参数
              rem2rpx: true,
              cssEntries: [
                // 你 @import "weapp-tailwindcss"; 那个文件绝对路径
                path.resolve(__dirname, '../src/app.css'),
              ],
            }],
          },
        },
      })
      // highlight-end
      // region end
    }
  }
}
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。

## 运行

然后执行命令发布到微信小程序

```bash npm2yarn
npm run dev:weapp
```

微信开发者工具导入这个项目，即可看到效果

## 参考模板

https://github.com/icebreaker-template/taro-webpack-tailwindcss-v4

---

## 高阶篇：性能、兼容与团队协作


Tailwind CSS 4 带来了更强大的原生语法，但在小程序环境中仍需平衡兼容性与团队协作。本篇从工程化视角出发，帮助你在真实项目中稳定地落地、优化与维护。

## 1. 处理 `@layer` 与兼容性

小程序运行时目前对 CSS Cascade Layers 支持有限，当你引用第三方组件或自定义样式时可能出现覆盖关系错乱。`weapp-tailwindcss` 内置的 `postcss-preset-env` 可将 `@layer` 转译成传统写法来提升兼容性。

```ts title="vite.config.ts"

export default defineConfig({
  plugins: [
    UnifiedViteWeappTailwindcssPlugin({
      cssEntries: [
        /* ... */
      ],
      cssPresetEnv: {
        stage: 1,
        features: {
          'cascade-layers': true,
        },
      },
    }),
  ],
})
```

> 如果你只在微信小程序调试，可使用开发者工具的「自定义编译」观察处理前后的差异；若仍存在覆盖问题，可结合传统的 `!important` 或布局拆分策略。

额外提示：

- `cssSelectorReplacement.root` 默认包含 `['page', '.tw-root']`。当页面外的容器（例如自定义 tab bar、弹出层根节点等）需要承载 Tailwind 注入的 `--tw-*` 变量时，只需在容器上加上 `class="tw-root"` 即可复用整套预设，无需额外配置。下面是一个在自定义 tab bar 中注入主题变量的示例：

  ```xml title="custom-tab-bar/index.mpx"
  <template>
    <view class="tw-root bg-[var(--tab-bar-bg)] text-[var(--tab-bar-color)]">
      <!-- 这里仍然可以继续使用 Tailwind 原子类 -->
    </view>
  </template>
  ```

  搭配 `cssPreflight` 注入的变量或自定义 `@theme`，可以把 tab bar 的主题色、渐变背景等统一交给 Tailwind 管理。若你需要覆盖其他容器名称，仍可以通过配置把 `cssSelectorReplacement.root` 扩展为更多选择器。

- `cssPresetEnv` 会参与最终构建，请在发布前执行一次 `pnpm build:apps` 或对应的 `pnpm build` 命令确认产物

## 2. 多端共存与按需构建

团队常同时维护小程序与 H5 版本，此时可以通过多个 `@source` 区分模板范围，并结合条件编译实现按需打包：

```css title="src/app.css"
@source "../src/**/*.{vue,wxml}";
@source not "../src/**/*.h5.*"; /* 排除只用于 H5 的模板 */

/* H5 用 Tailwind 官方包，小程序继续用 weapp-tailwindcss */
/*  #ifdef  H5  */
@import "tailwindcss";
/*  #endif  */
/*  #ifndef  H5  */
@import "weapp-tailwindcss";
/*  #endif  */
```

当需要拆分体积时，可以把不同业务域的样式写到各自的 `entry.css`，再将路径加入 `cssEntries`：

```ts
UnifiedViteWeappTailwindcssPlugin({
  cssEntries: [
    path.resolve(import.meta.dirname, './src/app.css'),
    path.resolve(import.meta.dirname, './src/features/order/app.css'),
  ],
})
```

这样 Tailwind 只会为实际引用的模板生成原子类，避免冗余。

## 3. 产物体积与性能优化

- **控制扫描范围**：`@source` 支持 `not` 语法，排除 `dist`、`node_modules` 等目录能显著加快增量编译
- **合理使用自定义工具类**：把相同组合提炼成 `@utility`，既减少模板体积，也方便统一调整
- **按需开启 `rem2rpx` / `px2rpx`**：在仅小程序端需要 rpx 的情况下，可以在多端构建中动态开启
- **缓存管理**：Tailwind 会在 `.tailwind` 写入缓存。CI 环境可缓存该目录以提升构建速度，发布前若需彻底清理运行 `pnpm exec tailwindcss --config tailwind.config.js --clean` 或直接删除缓存目录

## 4. 调试与质量保障

- **可视化定位**：使用 `outline` 类临时标记组件边界，例如在调试时加上 `outline outline-1 outline-dashed outline-brand/60`
- **断言样式存在**：核心组件可引入快照测试或 DOM 断言，结合 Vitest + @testing-library 验证关键类名
- **lint 约束**：在 `eslint-plugin-tailwindcss` 或团队约定的 lint 规则中，限制自定义类名必须通过 `@utility`
- **回归验证**：Tailwind 升级时执行 `pnpm test`, `pnpm e2e` 确认核心链路稳定，同时在主流机型（尤其是低版本安卓）上真机预览

## 5. 升级与维护策略

1. **版本对齐**：Tailwind 4 迭代频繁，升级前先在 `CHANGELOG` 与 GitHub Release 查 Breaking Change，再在测试分支试跑。
2. **切分 Changeset**：对外发布库时遵循 [Changesets](https://github.com/changesets/changesets) 约定，确保依赖者知道何时需要手动介入。
3. **文档同步**：团队内部记录 `@utility`、`@theme` 的设计规范，推荐把核心样式写进 Storybook 或内部组件示例库。
4. **遇到问题及时回馈**：`weapp-tailwindcss` 社区对 Tailwind 4 的需求反馈快速，遇到兼容问题可通过 Issue 或 PR 参与共建。

至此，你已经掌握了 Tailwind CSS 4 在小程序中的完整落地思路：从环境搭建、组件实践到性能与协同。结合现有的框架集成文档，就能为新成员提供一套体系化的学习路径。

---

## 入门篇：快速认识 Tailwind CSS 4 与 weapp-tailwindcss


Tailwind CSS 4 重新定义了“原子化”样式的组织方式：配置文件换成了 `CSS`，主题变量与自定义工具也变成了原生语法。这一变化对小程序生态同样生效，`weapp-tailwindcss` 已经适配了新的编译流程。本篇入门指南帮助你在 30 分钟内从零搭好一套 `tailwindcss@4` + `weapp-tailwindcss` 的基础开发环境，并理解最核心的概念。

## 本篇能学到什么

- 搭建一套可运行的 Tailwind CSS 4 + 小程序项目骨架
- 分清核心配置（`cssEntries`、`@source`、`@reference` 等）各自负责的事情
- 理解 `@tailwindcss/postcss`、`@tailwindcss/vite` 与编译插件的差异
- 掌握验证样式是否生效的最小闭环，避免“写了没生效”的常见坑

如果你还未接触过 `weapp-tailwindcss`，建议先浏览 [新手快速上手（Tailwind CSS 3.x）](/docs/quick-start/install) 了解插件能解决的问题，再回来完成 4.x 的配置。

## 环境准备

| 名称 | 说明 |
| --- | --- |
| Node.js ≥ 18 | Tailwind CSS 4 要求更高的 Node 版本，建议使用 LTS 20 |
| pnpm ≥ 8 | Monorepo 与文档项目统一使用 `pnpm` |
| 小程序框架 | 任选 `weapp-vite`、`uni-app`、`taro` 等，推荐使用现成模板 |
| 代码编辑器 | VS Code 并安装 `Tailwind CSS IntelliSense` 插件 |

初始化项目后，执行一次 `pnpm install` 以及框架 CLI 的初始化命令（如 `pnpm create @tarojs/cli`）。随后即可进入 Tailwind CSS 配置步骤。

## 步骤一：安装依赖

在项目根目录执行：

```bash
pnpm add -D tailwindcss@latest @tailwindcss/postcss postcss weapp-tailwindcss
```

> `@tailwindcss/postcss` 兼容 Vite、Webpack、Rspack 等大多数构建链路；对于纯 Vite 项目也可以酌情改用 `@tailwindcss/vite`，但在小程序场景下 `postcss` 方案更稳定。

## 步骤二：注册 weapp-tailwindcss 插件

以 `weapp-vite` 为例（不同框架请对照对应的 [集成指南](/docs/quick-start/v4)）：

```ts title="vite.config.ts"

export default defineConfig({
  plugins: [
    UnifiedViteWeappTailwindcssPlugin({
      // 常用内置能力：开启 px 自动转换
      rem2rpx: true,
      cssEntries: [
        // 声明 Tailwind 的入口 CSS，必须是绝对路径
        path.resolve(import.meta.dirname, './src/app.css'),
      ],
    }),
  ],
})
```

`cssEntries` 对 `tailwindcss@4` 至关重要，它告诉 `weapp-tailwindcss` 哪些 CSS 需要参与编译与转义。漏掉该配置将导致产物中缺失样式。

## 步骤三：配置 PostCSS

```js title="postcss.config.js"
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

Tailwind CSS 4 已内置 Autoprefixer，无需手动补充。若项目仍需其他 PostCSS 插件，保持旧的写法即可。

## 步骤四：创建入口 CSS

在 `src/app.css` 中写入：

```css title="src/app.css"
@import "weapp-tailwindcss";

/* 声明模板扫描路径，确保原子类能被收集 */
@source "../src/**/*.{vue,tsx,jsx,svelte,wxml}";

/* 需要自定义设计令牌时可在此编写 */
@theme {
  --color-brand: oklch(67% 0.2 264);
  --spacing-safe: clamp(12px, 1.2vw + 8px, 24px);
}
```

`@source` 是 Tailwind 4 的新写法，用于替代旧版本的 `content` 配置。路径请根据项目结构调整。若你需要在局部样式文件使用 `@apply`，在对应文件顶部添加 `@reference "./app.css";`。

## 步骤五：验证类名是否生效

创建一个最小页面（以 `src/pages/index/index.vue` 为例）：

```html title="src/pages/index/index.vue"
<template>
  <view class="flex min-h-screen flex-col items-center justify-center bg-slate-50 px-6 py-safe">
    <view class="w-full max-w-md rounded-3xl bg-white p-6 shadow-lg shadow-slate-200">
      <text class="text-xs font-semibold uppercase tracking-[0.22em] text-slate-500">Tailwind CSS 4</text>
      <text class="mt-3 text-2xl font-bold text-slate-900">欢迎来到 weapp-tailwindcss</text>
      <text class="mt-2 text-sm leading-6 text-slate-600">
        现在可以尝试修改 <text class="font-medium text-brand">bg-brand</text> 或自定义 <text class="font-medium">utility</text>。
      </text>
      <button class="mt-6 inline-flex items-center justify-center rounded-xl bg-brand px-4 py-2 text-sm font-semibold text-white shadow transition hover:bg-brand/90 active:scale-95">
        开始实践
      </button>
    </view>
  </view>
</template>
```

> `py-safe` 是我们在上文 `@theme` 中声明的自定义变量（通过 `--spacing-safe` 导出），可验证主题自定义是否生效。

运行框架命令（如 `pnpm dev:weapp` 或 `pnpm run build -- --watch`），查看开发者工具中的页面是否渲染出预期样式。如果没有：

- 检查 `cssEntries` 是否指向了正确路径
- 确认 `@source` 是否包含当前文件扩展名
- 若在单文件组件内使用 `@apply`，确保添加了 `@reference`

## 常见下一步

- 阅读 [Tailwind CSS 4 官方文档](https://tailwindcss.com/docs/installation) 了解更多原生指令
- 针对不同框架的集成细节，请查阅「🧪Tailwind CSS @4.x」分类中的各篇文档
- 想理解 `@layer` 在小程序下的降级方案，可继续阅读本教程的 [进阶篇](/docs/quick-start/v4/tutorial/workflow) 与 [高阶篇](/docs/quick-start/v4/tutorial/advanced)

完成本篇后，你已经拥有了稳定的基础开发环境。接着让我们通过真实业务组件把 Tailwind CSS 4 的能力串联起来。

---

## 进阶篇：用 Tailwind CSS 4 构建真实页面


基础环境搭建完成后，真正的挑战来自“如何把抽象的原子类应用到真实业务”。本篇精选小程序常见的页面模块，结合 `tailwindcss@4` 的新指令，总结出一套从设计拆解到代码落地的流程。

## 工具优先的心智模型

Tailwind CSS 的核心不在于背公式，而是把 UI 拆成「布局」「排版」「状态」三个维度，然后使用类名组合快速拼装。Tailwind 4 进一步引入 `@theme`、`@utility` 等指令，让自定义能力与项目约束保持同步：

- `@theme` 管理设计令牌：颜色、间距、字号、阴影等
- `@utility` 声明可复用的工具类，代替传统的 `.btn { ... }`
- `@variant` / `@custom-variant` 管理状态类（如 `active:`、`dark:`）

掌握这些指令后，就可以在不离开 CSS 语法的前提下扩展 Tailwind。

## 1. 拆解一个卡片组件

以「订单卡片」为例，先在 `src/components/order-card/index.vue` 写出骨架：

```html title="src/components/order-card/index.vue"
<template>
  <view class="order-card">
    <view class="order-card__header">
      <text class="order-card__title">{{ title }}</text>
      <text class="order-card__status" :class="statusClass">{{ statusText }}</text>
    </view>
    <view class="order-card__meta">
      <text>{{ createdAt }}</text>
      <text>{{ amount }}</text>
    </view>
    <slot />
  </view>
</template>
```

接下来在 `src/components/order-card/index.css` 中使用 Tailwind 原子类重构：

```css title="src/components/order-card/index.css"
@reference "../../app.css";

/* 使用 @utility 提升可读性 */
@utility order-card {
  @apply block rounded-3xl bg-white shadow-lg shadow-slate-200/70 p-5 space-y-4;
}

@utility order-card__header {
  @apply flex items-center justify-between gap-3;
}

@utility order-card__title {
  @apply text-base font-semibold text-slate-900;
}

@utility order-card__meta {
  @apply flex items-center justify-between text-sm text-slate-500;
}

@utility order-card__status {
  @apply inline-flex items-center gap-1 rounded-full px-3 py-1 text-xs font-medium uppercase tracking-[0.28em];
}

/* 通过 @variant 声明业务状态 */
@custom-variant status-pending (&[data-status="pending"]);
@custom-variant status-finished (&[data-status="finished"]);
@custom-variant status-failed (&[data-status="failed"]);

.order-card__status {
  @apply status-pending:bg-amber-100 status-pending:text-amber-600;
  @apply status-finished:bg-emerald-100 status-finished:text-emerald-600;
  @apply status-failed:bg-rose-100 status-failed:text-rose-600;
}
```

关键点：

- 使用 `@reference` 让局部样式文件继承入口 CSS 中的主题与工具
- `@utility` 让类名语义化，同时还能继续 `@apply` 原子类
- `@custom-variant`（Tailwind 4 新增）能让业务状态转换成语义化前缀

最后在组件实例上应用：

```html title="src/pages/index/index.vue"
<template>
  <order-card
    class="order-card"
    data-status="pending"
    title="小程序尊享套餐"
    status-text="待支付"
    created-at="2024-06-03"
    amount="¥199"
  >
    <view class="flex items-center gap-2 rounded-2xl bg-slate-50 px-4 py-3">
      <text class="text-xs font-medium text-slate-500">自动续费:</text>
      <switch class="scale-90" :checked="false" />
    </view>
  </order-card>
</template>
```

## 2. 构建可复用的设计令牌

Tailwind 4 把主题抽象为原生 CSS 变量。你可以在 `app.css` 中集中维护令牌，再通过 `@theme` 输出：

```css title="src/app.css" {2-7}
@import "weapp-tailwindcss";

@theme {
  --color-brand: oklch(66% 0.21 268);
  --color-brand-muted: oklch(80% 0.04 268);
  --radius-xl: 24px;
  --shadow-elevated: 0 18px 40px -20px rgb(99 102 241 / 45%);
}
```

然后在业务样式中直接引用这些变量，或结合 Tailwind 的 `bg-[...]` 写法：

```css
.order-card {
  @apply shadow-[var(--shadow-elevated)];
}

.order-card__status {
  @apply status-finished:bg-[var(--color-brand-muted)] status-finished:text-[var(--color-brand)];
}
```

得益于 CSS 变量特性，你还可以在不同页面覆写 `:root` 或对应容器的变量，以实现主题切换。

## 3. 管理复杂布局与响应式

小程序虽然没有传统意义上的宽度断点，但我们仍可以借助媒体查询、`min()` / `max()` 等函数实现容错布局：

```css
@layer utilities {
  @responsive {
    @media (min-width: 560px) {
      .md\\:card-grid {
        display: grid;
        grid-template-columns: repeat(2, minmax(0, 1fr));
        gap: clamp(16px, 4vw, 36px);
      }
    }
  }
}
```

在页面中配合默认的原子类即可：

```html
<view class="space-y-4 md:card-grid">
  <slot />
</view>
```

对于需要横向滚动的卡片，Tailwind 4 提供的 `snap-x`, `snap-mandatory`, `snap-center` 等类仍旧适用，不同端的处理逻辑交给 `weapp-tailwindcss`。

## 4. 多文件协作与团队约定

当项目迎来多人协作时，建议遵循以下约定：

1. **入口 CSS 只做聚合**：集中维护 `@import`、`@source` 与 `@theme`，其余逻辑拆到独立文件。
2. **组件目录内固定 `index.css`**：组件内声明 `@utility`、`@apply`，并写在组件同名文件夹下，便于按需引用。
3. **公共工具抽成包**：例如 `src/styles/utilities/forms.css`，内部声明所有表单相关的 `@utility`。
4. **lint 与提示配置**：确保团队成员的 VS Code `tailwindCSS.experimental.classRegex` 包含 `.wxml`、`.vue` 等模板。

## 5. 调试与性能提示

- Tailwind 4 的编译沿用增量模式，`pnpm run:watch` 时生成的原子类会写入缓存。需要彻底清理时删除 `.tailwind`、`node_modules/.cache/tailwind`。
- 小程序开发者工具不支持 `@layer`，若遇到覆盖问题，可以开启 `cssPresetEnv` 的降级行为，详情见 [高阶篇](/docs/quick-start/v4/tutorial/advanced)。
- 借助 `pnpm dev:h5`（部分框架提供）可快速在浏览器预览，调试完后再回到真机验证。

完成本篇后，你应该可以把 Tailwind 应用到实际业务模块，并形成一套可复用的组件写法。接下来，我们会关注性能优化、跨端适配与团队协作等更高阶的话题。

---

## HBuilderX


<UniAppHbuilderShared />

---

## uni-app cli vue3 vite(V4)


## 1. 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss weapp-tailwindcss
```

<Patch />

## 2. 配置 `vite.config.ts`

```ts title="vite.config.ts"

export default defineConfig({
  plugins: [
    uni(),
    UnifiedViteWeappTailwindcssPlugin({
      rem2rpx: true,
      cssEntries: [
        // 你 @import "weapp-tailwindcss"; 那个文件绝对路径
        path.resolve(import.meta.dirname, './src/app.css'),
      ],
    }),
  ],
  css: {
    postcss: {
      plugins: [
        tailwindcss(),
      ],
    },
  },
});

```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。

## 3. 添加样式

<UniappCliStyle/>

接着直接运行 `npm run dev:mp-weixin`，

微信开发者工具导入这个项目，即可看到效果

{/* :::warning
这里必须创建一个额外的 `css` 文件，而不是直接在 `App.vue` 里的 `style` 标签下直接写，

这是因为 `@tailwindcss/vite` 目前只转化 `.css` 文件。后续可能会支持更多格式的文件，比如 `vue` 编译的中间文件

详见 http://github.com/tailwindlabs/tailwindcss/blob/main/packages/%40tailwindcss-vite/src/index.ts#L122 中的 `isCssFile` 判断
::: */}

## 参考模板

[uni-app-tailwindcss-v4](https://github.com/icebreaker-template/uni-app-tailwindcss-v4)

---

## uni-app cli vue2 webpack(V4)


## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

<Patch />

## 配置

### 创建 `vue.config.js`

```js title="vue.config.js"
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')
const path = require('node:path')
/**
 * @type {import('@vue/cli-service').ProjectOptions}
 */
const config = {
  // some option...
  configureWebpack: (config) => {
    config.plugins.push(
      new UnifiedWebpackPluginV5({
        rem2rpx: true,
        cssEntries: [
          // 你 @import "weapp-tailwindcss"; 那个文件绝对路径
          path.resolve(__dirname, './src/app.css'),
        ],
      })
    )
  }
  // other option...
}

module.exports = config
```

> tailwindcss@4 必须配置 `cssEntries` 并且使用绝对路径，否则 `tailwindcss` 生成的类名不会参与转译。

## 配置 `postcss.config.js`

```js title="postcss.config.js"
const path = require('path')
const webpack = require('webpack')
const config = {
  parser: require('postcss-comment'),
  plugins: [
    // highlight-next-line
    require('@tailwindcss/postcss')(), // 只添加这一行
    require('postcss-import')({
      resolve (id, basedir, importOptions) {
        if (id.startsWith('~@/')) {
          return path.resolve(process.env.UNI_INPUT_DIR, id.substr(3))
        } else if (id.startsWith('@/')) {
          return path.resolve(process.env.UNI_INPUT_DIR, id.substr(2))
        } else if (id.startsWith('/') && !id.startsWith('//')) {
          return path.resolve(process.env.UNI_INPUT_DIR, id.substr(1))
        }
        return id
      }
    }),

    require('autoprefixer')({
      remove: process.env.UNI_PLATFORM !== 'h5'
    }),
    require('@dcloudio/vue-cli-plugin-uni/packages/postcss')
  ]
}
if (webpack.version[0] > 4) {
  delete config.parser
}
module.exports = config
```

## 添加样式

<UniappCliStyle />

然后直接运行到小程序，微信开发者工具导入这个项目，即可看到效果

## 参考模板

https://github.com/icebreaker-template/uni-app-webpack-tailwindcss-v4

---

## uni-app x


:::warning
tailwindcss@4 版本，暂时只支持 hbuilderx uni-app x 跨 `h5` 和 `小程序` 平台，

原生安卓和IOS平台无法支持，因为 uni-app x 目前对 css 各种现代语法的兼容较差，兼容不了 tailwindcss@4 生成的样式

未来此功能的适配，取决于 uni-app x 团队对现代 css 的兼容程度

(2025-07-27)
:::

<UniAppHbuilderShared isX />

---

## Weapp-vite


<ExternalClassesReminder framework="weapp-vite" />

## 安装

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/postcss postcss weapp-tailwindcss
```

<Patch/>

## 配置

更改 `vite.config.ts` 注册 `weapp-tailwindcss`

```js title="vite.config.ts"

export default defineConfig({
  plugins: [
    UnifiedViteWeappTailwindcssPlugin({
      rem2rpx: true,
      cssEntries: [
        // app.css 的路径
        path.resolve(import.meta.dirname, './app.css'),
      ],
    }),
  ],
})
```

添加 `postcss.config.js` 注册 `@tailwindcss/postcss`

```js title="postcss.config.js"
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

## 添加样式

在项目目录下，小程序全局的 `app.css` 中，添加以下内容：

```css title="app.css"
@import "weapp-tailwindcss";
```

更改好配置之后，直接启动即可

---

## wxs的转义与处理


:::info
`2.5.2+` 版本中，已经添加了对 `wxs`,`sjs`等视图层运行 `js` 的转义和处理，默认关闭

具体见配置项:

- [`wxsMatcher`](/docs/api/interfaces/UserDefinedOptions#wxsmatcher)
- [`inlineWxs`](/docs/api/interfaces/UserDefinedOptions#inlinewxs)

:::

---

## weapp-tw CLI 使用指南

`weapp-tailwindcss` 自带一个 `weapp-tw` 命令行工具，负责提前给 Tailwind CSS 打补丁、生成类名缓存以及收集 token。以下内容介绍常用命令及最佳实践。

## 常见场景

| 场景 | 命令 | 说明 |
| --- | --- | --- |
| 给 Tailwind CSS 打补丁、注入 `rpx` 支持 | `npx weapp-tw patch` | 运行一次即可，推荐写在 `postinstall`；支持 `--cwd` 指向子包目录。 |
| 强制刷新补丁缓存后再打补丁 | `npx weapp-tw patch --clear-cache` | 默认不会清理缓存；仅在怀疑缓存导致补丁未生效或版本不一致时使用。 |
| 在 monorepo 针对子包补丁 | `pnpm --filter <pkg> exec weapp-tw patch --cwd .` | `pnpm` 场景建议显式传 `--cwd .`，每个子包只写入自己的缓存，避免 hoist 后的 `node_modules` 不一致。 |
| 一键扫描 workspace 并补丁 | `weapp-tw patch --workspace --cwd <repo-root>` | 自动读取 `pnpm-lock.yaml`/`pnpm-workspace.yaml` 批量补丁，跳过未安装 Tailwind 的包，并输出每个子包状态。 |
| 收集 Tailwind 产出的类名缓存 | `npx weapp-tw extract --css src/app.css` | 适用于 Tailwind v3/v4，v4 需传入 `--css`，生成 `.tw-patch/tw-class-cache.*`，支持 `--output`/`--format`。 |
| 输出 Tailwind token 和定位信息 | `npx weapp-tw tokens --format grouped-json` | 调试 `content` 配置时非常有用，可与 `--no-write` 一起纯输出。 |

## `patch` 子命令

### 功能

- 扫描当前工作目录所依赖的 `tailwindcss`，给其打上 `rpx` 单位补丁。
- 暴露 Tailwind 运行时上下文，供 `webpack`/`vite`/`gulp` 插件复用。
- 检测到未安装 Tailwind 时会输出中文警告。

### 常用参数

| 参数 | 默认值 | 含义 |
| --- | --- | --- |
| `--cwd <dir>` | `WEAPP_TW_PATCH_CWD` \| `INIT_CWD` \| `npm_config_local_prefix` \| 当前工作目录 | 指定要补丁的子包目录，等价于先 `cd`。默认会按顺序读取上述环境变量，避免在 `pnpm`/CI 里被 wrapper 覆盖成根目录。 |
| `--record-target` | `true` | 默认记录本次打补丁对应的 `tailwindcss` 根路径到子包专属的 `node_modules/.cache/weapp-tailwindcss/<hash>/tailwindcss-target.json`，包含 `cwd`、Tailwind 路径、补丁版本与时间戳；如需关闭请传 `--record-target false`。 |
| `--clear-cache` | `false` | 按需清理 `tailwindcss-patch` 缓存目录后再执行补丁。默认不清理，避免不必要的 IO 和 CI 侧效应。 |
| `--workspace` | `false` | 批量扫描 workspace（`pnpm-lock.yaml`/`pnpm-workspace.yaml`/`workspaces`），逐个子包执行 patch 并输出“补丁/跳过/失败”状态。 |

默认会记录补丁目标，运行日志类似：

```bash
$ pnpm --filter demo/native-mina weapp-tw patch
weapp-tw patch 绑定 Tailwind CSS -> ./node_modules/tailwindcss (v3.4.18)
记录 weapp-tw patch 目标 -> ./node_modules/.cache/weapp-tailwindcss/<hash>/tailwindcss-target.json
Tailwind CSS 运行时补丁已完成。
```

随后每次启动构建工具，运行时会输出 `tailwindcss-patcher 绑定 Tailwind CSS -> ...`；若检测到与缓存记录不一致，会自动重打补丁并刷新记录，无需手动清理跨包告警。若不希望生成记录，可在命令后追加 `--record-target false`。补丁记录按子包（package.json 路径 hash）隔离，避免 `pnpm` hoist 或 `workspace:` 互相引用时互相覆盖。

## `extract` 子命令

```bash
npx weapp-tw extract --css src/app.css --format lines
```

- `--css`：Tailwind 入口 CSS。v4 必填；v3 可省略以沿用 Tailwind 默认入口。
- `--output`：指定输出文件，默认写入 `.tw-patch/tw-class-cache.json`。
- `--format`：`json`/`lines`，配合 `--no-write` 可仅打印到终端。
- `--cwd` 与 `patch` 一致，也支持放在子包里执行。

生成的缓存可以让构建器快速读取 `tailwindcss` 编译结果，减少重复启动的开销。

## `tokens` 子命令

```bash
npx weapp-tw tokens --format grouped-json --group-key absolute
```

- `--format`：`json`、`lines` 或 `grouped-json`。后一种会按文件分组，便于排查 `content` 匹配不到的问题。
- `--group-key`：`relative`(默认)/`absolute`，决定输出路径的基准。
- `--no-write`：终端预览，不落盘；默认写入 `.tw-patch/tw-token-report.json`。

输出的数据包含扫描到的文件、类名 token、出现位置（行列）、以及被跳过的文件列表。

## 快速排查指引

1. **始终在子包目录执行 `weapp-tw patch`**：`pnpm --filter my-demo weapp-tw patch --cwd demo/my-demo`。
2. **如确实不需要追踪，可传 `--record-target false`**，避免生成额外 JSON。
3. **看到自动重补丁/记录迁移提示**：确认日志里的 Tailwind 路径与子包一致，`pnpm --filter ... exec weapp-tw patch --cwd .` 或 `weapp-tw patch --workspace --cwd <repo-root>` 可避免 `INIT_CWD` 导致的跨包记录污染。
4. **类名缺失**： 用 `weapp-tw extract` 或 `weapp-tw tokens --no-write` 辅助定位是哪段代码没有被 Tailwind `content` 收录。
5. **需要强制指定根目录时**：在 monorepo 根执行 `WEAPP_TW_PATCH_CWD=$PWD weapp-tw patch --workspace`，可覆盖外层脚本设置的 `INIT_CWD`，确保一次性为所有子包补丁并写入各自的缓存记录。

配合这些命令，可以更直观地观察 Tailwind 依赖解析与补丁状态，减少“rpx 被当成颜色” 等由于上下游不一致导致的问题。

---

## uni-app x 专题


  
  
  
  
    跨端原子化样式方案
    Tailwind CSS × uni-app x
  

  
    
    一键使用模板项目（推荐）
  
  
    
    或者按步骤手动集成
  

## 这篇文档适合谁

- 想在 uni-app x 项目里使用 Tailwind CSS 的开发者
- 需要一套能同时覆盖 Web/小程序/Android/iOS/鸿蒙 的原子化样式方案
- 希望以最少的改动尽快起步，并有清晰的后续扩展路线

## 你将收获什么

- 完整的从 0 到 1 集成流程（含运行与验证）
- 可复用的模板项目与配置清单
- 多端开发的实践建议与避坑说明

:::info 支持范围
当前跨端集成仅支持 `tailwindcss@3.x`。  
`tailwindcss@4.x` 生成的 CSS 依赖诸多现代特性，`uni-app x` 暂未全部覆盖，故不建议在该场景使用 v4。
:::

## 最快开始

- 想最快跑起来：点击上方「一键使用模板项目」，按 README 步骤打开 HBuilderX 运行即可
- 想了解每一步：前往「手动集成」教程 → <Link to="/docs/uni-app-x/install">快速集成</Link>

## 开发建议（从用户出发）

- 推荐编辑器协作：用 VS Code 写代码，用 HBuilderX 负责运行与构建
- 首选 Android 端调试：CSS 兼容度一般是 Web > 小程序 > App（Android/iOS/鸿蒙）。先用 Android 模拟器打通路径，跨端成本最低
- 组件语义注意：原生 App 端文字需放在 `<text>` 标签，且文本样式需要直接作用在该元素上
- 渐进增强：若某些样式在 App 端受限，优先保证 Android 端体验，再按需做条件编译适配小程序/Web

## 为什么推荐先用 Android

1) 原生端样式约束更严格，例如文本必须使用 `<text>`，许多 CSS 特性仍在补齐中  
2) 如果你的页面在 Android 端无告警、展示正确，迁移到小程序与 Web 的心智负担会小很多  
3) iOS/鸿蒙的调试门槛更高（设备/系统要求），多数团队以 Android 作为优先目标更务实

## 常见问题

### VS Code 对 uvue/uts 的高亮与跳转

安装官方语言服务插件：  
- ID: dcloud-ide.hbuilderx-language-services  
- 说明: 支持 uni-app x 项目的提示、悬浮、转到定义、查找引用、校验等  
- 链接: https://marketplace.visualstudio.com/items?itemName=dcloud-ide.hbuilderx-language-services

### Tailwind CSS 智能提示

VS Code 原生不识别 `uvue/uts`，建议为 Tailwind 扩展加上语言映射。在项目根目录创建 `.vscode/settings.json`：

```json title=".vscode/settings.json"
{
  "tailwindCSS.includeLanguages": {
    "uvue": "html",
    "uts": "javascript"
  }
}
```

### 运行方式

目前 `uni-app x` 尚无 CLI，需通过 HBuilderX 进行运行与构建。  
建议配合 Android 模拟器进行开发调试。

## 接下来

- 跟着步骤手动完成集成：<Link to="/docs/uni-app-x/install">快速集成</Link>  
- 直接基于模板起步：<Link to="https://github.com/icebreaker-template/uni-app-x-hbuilderx">uni-app x + Tailwind 模板（HBuilderX）</Link>

---

## 快速集成


## 最简单：直接用模板项目（推荐）

立即上手而不纠结配置细节，点击下面链接即可：

  
    
    使用模板一键开始
  

打开后按 README 步骤，用 HBuilderX 运行到 Android 模拟器或真机即可看到效果。

---

## 手动集成（由浅入深）

你也可以按下面步骤，从零开始完成配置。

### 前置条件

- 已安装最新 HBuilderX
- 安装 Node.js（建议 ≥ 18）
- 建议准备 Android 模拟器（或真机），便于快速验证

### 1) 创建项目

在 HBuilderX 中创建一个全新的 `uni-app x` 项目；随后在项目根目录初始化 `package.json`：

```bash npm2yarn
npm init -y
```

> 也可以手动创建 `package.json` 文件。

### 2) 安装并引入 Tailwind CSS 3

```bash npm2yarn
# 安装 tailwindcss@3 所需依赖
npm i -D tailwindcss@3 postcss autoprefixer
```

```bash npm2yarn
# 初始化 Tailwind 配置文件
npx tailwindcss init
```

在应用入口 `App.uvue` 中全局引入：

```html title="App.uvue"
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>
```

### 3) 安装 weapp-tailwindcss 并添加补丁脚本

```bash npm2yarn
npm i -D weapp-tailwindcss
```

在 `package.json` 中增加 `postinstall` 脚本：

```json title="package.json"
{
  "scripts": {
    // highlight-next-line
    "postinstall": "weapp-tw patch"
  }
}
```

> 了解原因可阅读：weapp-tailwindcss 使用说明

### 4) 在 uni-app x 中注册 weapp-tailwindcss

先创建一个简单的路径工具函数，方便在配置里引用绝对路径：

```js title="shared.js"
const path = require('node:path')
function r(...args) {
  return path.resolve(__dirname, ...args)
}
module.exports = { r }
```

创建 `vite.config.ts` 并注册插件（注意 `uniAppX` 预设来自 `weapp-tailwindcss/presets`）：

```js title="vite.config.ts"

export default defineConfig({
  plugins: [
    uni(),
    UnifiedViteWeappTailwindcssPlugin(
      uniAppX({
        base: __dirname,
        rem2rpx: true,
      }),
    ),
  ],
  css: {
    postcss: {
      plugins: [
        tailwindcss({
          config: r('./tailwind.config.js'),
        }),
      ],
    },
  },
})
```

### 5) 配置 Tailwind

使用绝对路径包含所有需要提取原子类的文件：

```js title="tailwind.config.js"
const { r } = require('./shared')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    r('./pages/**/*.{uts,uvue}'),
    r('./components/**/*.{uts,uvue}'),
  ],
  corePlugins: {
    // 由 uni-app x 提供基础样式，这里关闭 preflight 避免冲突
    preflight: false,
  },
}
```

如需从更多目录提取样式，按需扩展 `content` 的 glob。

### 6) 运行与验证

- 在 HBuilderX 中点击「运行」并选择目标平台（推荐 Android 模拟器/真机）  
- 新建/打开任意页面，写入示例类名验证：

```html
<view class="p-4">
  <text class="text-xl text-red-500 font-medium">Hello Tailwind on uni-app x</text>
</view>
```

### 7) 编辑器智能提示（可选）

VS Code 配合插件体验最佳。为 Tailwind 扩展增加语言映射，让其识别 `uvue/uts`：

```json title=".vscode/settings.json"
{
  "tailwindCSS.includeLanguages": {
    "uvue": "html",
    "uts": "javascript"
  }
}
```

同时安装官方语言服务插件（ID: dcloud-ide.hbuilderx-language-services）以获得完整语法支持。

---

## 重要说明与限制

- 仅推荐在 `tailwindcss@3.x` 下跨端使用（v4 在该场景下暂不兼容）
- 原生 App 端对文本与部分 CSS 特性有约束：文本使用 `<text>` 元素，且样式需直接作用其上
- 如遇到 HBuilderX 控制台 CSS 警告，请按提示做兼容性调整或采用条件编译

---

## weapp-tailwindcss


## 接口

- [TailwindcssPatchOptions](interfaces/TailwindcssPatchOptions.md)
- [UserDefinedOptions](interfaces/UserDefinedOptions.md)

---

## 接口: TailwindcssPatchOptions


定义于: node\_modules/.pnpm/tailwindcss-patch@8.4.3\_magicast@0.5.1\_tailwindcss@4.1.18/node\_modules/tailwindcss-patch/dist/index.d.ts:114

Root configuration consumed by the Tailwind CSS patch runner.

## 属性

### cache?

> `optional` **cache**: `boolean` \| `CacheUserOptions`

定义于: node\_modules/.pnpm/tailwindcss-patch@8.4.3\_magicast@0.5.1\_tailwindcss@4.1.18/node\_modules/tailwindcss-patch/dist/index.d.ts:129

Cache configuration or boolean to enable/disable quickly.

***

### cwd?

> `optional` **cwd**: `string`

定义于: node\_modules/.pnpm/tailwindcss-patch@8.4.3\_magicast@0.5.1\_tailwindcss@4.1.18/node\_modules/tailwindcss-patch/dist/index.d.ts:119

Base directory used when resolving Tailwind resources.
Defaults to `process.cwd()`.

***

### features?

> `optional` **features**: `FeatureUserOptions`

定义于: node\_modules/.pnpm/tailwindcss-patch@8.4.3\_magicast@0.5.1\_tailwindcss@4.1.18/node\_modules/tailwindcss-patch/dist/index.d.ts:125

Feature toggles for optional helpers.

***

### filter()?

> `optional` **filter**: (`className`) => `boolean`

定义于: node\_modules/.pnpm/tailwindcss-patch@8.4.3\_magicast@0.5.1\_tailwindcss@4.1.18/node\_modules/tailwindcss-patch/dist/index.d.ts:127

Optional function that filters final class names.

#### 参数

##### className

`string`

#### 返回

`boolean`

***

### output?

> `optional` **output**: `OutputUserOptions`

定义于: node\_modules/.pnpm/tailwindcss-patch@8.4.3\_magicast@0.5.1\_tailwindcss@4.1.18/node\_modules/tailwindcss-patch/dist/index.d.ts:131

Output configuration or boolean to inherits defaults.

***

### overwrite?

> `optional` **overwrite**: `boolean`

定义于: node\_modules/.pnpm/tailwindcss-patch@8.4.3\_magicast@0.5.1\_tailwindcss@4.1.18/node\_modules/tailwindcss-patch/dist/index.d.ts:121

Whether to overwrite generated artifacts (e.g., caches, outputs).

***

### tailwind?

> `optional` **tailwind**: `TailwindUserOptions`

定义于: node\_modules/.pnpm/tailwindcss-patch@8.4.3\_magicast@0.5.1\_tailwindcss@4.1.18/node\_modules/tailwindcss-patch/dist/index.d.ts:123

Tailwind-specific configuration grouped by major version.

---

## 接口: UserDefinedOptions


定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:15](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L15)

## 属性

### replaceRuntimePackages?

> `optional` **replaceRuntimePackages**: `boolean` \| `Record`\<`string`, `string`\>

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:94](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L94)

**`Internal`**

## 0.重要配置

### cssCalc?

> `optional` **cssCalc**: `any`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:165](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L165)

预计算 CSS 变量或 `calc` 表达式的结果。

#### 添加于

^4.3.0

#### 备注

解决部分机型对 `calc` 计算不一致的问题，可传入布尔值、选项对象或自定义匹配列表（支持正则）。在启用计算后，可通过 `includeCustomProperties` 指定需要保留的变量。

#### 示例

```css
// 原始输出
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: calc(var(--spacing) * 2);
}
```

```css
// 启用 cssCalc 后
.h-2 {
  height: 16rpx;
  height: calc(var(--spacing) * 2);
}
```

```js
cssCalc: ['--spacing']
cssCalc: { includeCustomProperties: ['--spacing'] }
```

***

### cssEntries?

> `optional` **cssEntries**: `string`[]

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:264](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L264)

指定 tailwindcss@4 的入口 CSS。

#### 添加于

^4.2.6

#### 备注

未配置时无法加载自定义插件，等价于设置 `tailwindcss.v4.cssEntries`。

***

### cssPreflight?

> `optional` **cssPreflight**: `any`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:123](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L123)

控制在视图节点上注入的 CSS 预设。

#### 参阅

https://github.com/sonofmagic/weapp-tailwindcss/issues/7

#### 备注

默认会向所有 `view`/`text` 元素注入 Tailwind 风格的基础样式，可通过此配置禁用、调整或补充规则，受 `cssPreflightRange` 影响。

#### 示例

```js
cssPreflight: {
  'box-sizing': 'border-box',
  'border-width': '0',
  'border-style': 'solid',
  'border-color': 'currentColor',
}

cssPreflight: false

cssPreflight: {
  'box-sizing': false,
  background: 'black',
}
```

***

### cssPreflightRange?

> `optional` **cssPreflightRange**: `"all"`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:132](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L132)

控制 `cssPreflight` 注入的 DOM 选择器范围。

#### 参阅

https://github.com/sonofmagic/weapp-tailwindcss/pull/62

#### 备注

仅 `view`、`text` 及其伪元素会受影响。设置为 `'all'` 可以覆盖所有元素，此时需自行处理与宿主默认样式的冲突。

***

### cssPresetEnv?

> `optional` **cssPresetEnv**: `any`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:246](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L246)

`postcss-preset-env` 的配置项。

#### 添加于

^4.0.0

#### 参阅

 - https://preset-env.cssdb.org/
 - https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env#readme

***

### cssSelectorReplacement?

> `optional` **cssSelectorReplacement**: `object`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:191](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L191)

控制 CSS 选择器的替换规则。

#### root?

> `optional` **root**: `string` \| `false` \| `string`[]

将全局选择器 `:root` 替换为指定值。

##### 默认值

`'page'` 

##### 备注

设置为 `false` 时不再替换，可根据宿主环境（例如 RootPortal）传入数组值。

##### 示例

```ts
root: ['page', 'wx-root-content']
```

#### universal?

> `optional` **universal**: `string` \| `false` \| `string`[]

将全局选择器 `*` 替换为指定值。

##### 参阅

https://github.com/sonofmagic/weapp-tailwindcss/issues/81 

##### 默认值

`['view','text']` 

##### 备注

小程序环境不支持 `*`，因此默认转换为 `view`、`text`；设置为 `false` 会留下原始选择器。

***

### customAttributes?

> `optional` **customAttributes**: `ICustomAttributes`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:60](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L60)

自定义 `wxml` 标签属性的转换规则。

#### 备注

默认会转换所有标签上的 `class` 与 `hover-class`。此配置允许通过 `Map` 或对象为特定标签指定需要转换的属性字符串或正则表达式数组。
- 使用 `'*'` 作为键可为所有标签追加通用规则。
- 支持传入 `Map<string | RegExp, (string | RegExp)[]>` 以满足复杂匹配需求。
- 常见场景包括通过组件 `prop` 传递类名，或对三方组件的自定义属性做匹配，更多讨论见 [issue#129](https://github.com/sonofmagic/weapp-tailwindcss/issues/129#issuecomment-1340914688) 与 [issue#134](https://github.com/sonofmagic/weapp-tailwindcss/issues/134#issuecomment-1351288238)。
如果自定义规则已经覆盖默认的 `class`/`hover-class`，可开启 [`disabledDefaultTemplateHandler`](/docs/api/interfaces/UserDefinedOptions#disableddefaulttemplatehandler) 以关闭内置模板处理器。

#### 示例

```js
const customAttributes = {
  '*': [/[A-Za-z]?[A-Za-z-]*[Cc]lass/],
  'van-image': ['custom-class'],
  'ice-button': ['testClass'],
}
```

***

### customReplaceDictionary?

> `optional` **customReplaceDictionary**: `Record`\<`string`, `string`\>

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:69](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L69)

自定义 class 名称的替换字典。

#### 备注

默认策略会将小程序不允许的字符映射为等长度的替代字符串，因此无法通过结果反推出原始类名。如需完全自定义，可传入 `Record<string, string>`，只需确保生成的类名不会与已有样式冲突。示例参考 [dic.ts](https://github.com/sonofmagic/weapp-core/blob/main/packages/escape/src/dic.ts)。

#### 默认值

```ts
MappingChars2String
```

***

### disabled?

> `optional` **disabled**: `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:39](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L39)

是否禁用此插件。

#### 备注

在多平台构建场景下常用：小程序构建保持默认，非小程序环境（H5、App）传入 `true` 即可跳过转换。

#### 示例

```ts
// uni-app vue3 vite

const isH5 = process.env.UNI_PLATFORM === 'h5'
const isApp = process.env.UNI_PLATFORM === 'app'
const disabled = isH5 || isApp

uvtw({
  disabled,
})
```

***

### ignoreCallExpressionIdentifiers?

> `optional` **ignoreCallExpressionIdentifiers**: (`string` \| `RegExp`)[]

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:89](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L89)

忽略指定调用表达式中的标识符。

#### 添加于

^4.0.0

#### 备注

使用这些方法包裹的模板字符串或字符串字面量会跳过转义，常与 `@weapp-tailwindcss/merge` 配合（如 `['twMerge', 'twJoin', 'cva']`）。

***

### ignoreTaggedTemplateExpressionIdentifiers?

> `optional` **ignoreTaggedTemplateExpressionIdentifiers**: (`string` \| `RegExp`)[]

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:80](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L80)

忽略指定标签模板表达式中的标识符。

#### 添加于

^4.0.0

#### 备注

当模板字符串被这些标识符包裹时，将跳过转义处理。

#### 默认值

```ts
['weappTwIgnore']
```

***

### injectAdditionalCssVarScope?

> `optional` **injectAdditionalCssVarScope**: `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:176](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L176)

是否额外注入 `tailwindcss css var scope`。

#### 添加于

^2.6.0

#### 备注

当构建链路（例如 `@tarojs/plugin-html`）移除了包含 `*` 的选择器时，可启用该选项重新写入变量作用域，以避免渐变等功能失效。

#### 默认值

```ts
false
```

***

### px2rpx?

> `optional` **px2rpx**: `any`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:236](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L236)

px 到 rpx 的转换配置。

#### 添加于

^4.3.0

#### 备注

传入 `true` 启用默认映射（`1px = 1rpx`），或通过对象自定义更多行为。

***

### rem2rpx?

> `optional` **rem2rpx**: `any`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:227](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L227)

rem 到 rpx 的转换配置。

#### 添加于

^3.0.0

#### 备注

传入 `true` 使用默认配置，或提供 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel) 支持的完整选项。
```ts
{
  rootValue: 32,
  propList: ['*'],
  transformUnit: 'rpx',
}
```

***

### rewriteCssImports?

> `optional` **rewriteCssImports**: `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:185](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L185)

是否在 webpack/vite 阶段自动把 CSS 中的 `@import 'tailwindcss'` 映射为 `weapp-tailwindcss`。

#### 备注

开启后打包链路只会在处理样式时拦截 `tailwindcss` 的导入路径（JS/TS `import 'tailwindcss'` 不会被修改），让源码可以继续写 `@import 'tailwindcss';`，同时输出 weapp-tailwindcss 的样式。传入 `false` 可完全关闭该行为。

#### 默认值

```ts
true
```

***

### tailwindcss?

> `optional` **tailwindcss**: `TailwindUserOptions`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:254](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L254)

为不同版本的 Tailwind 配置行为。

#### 添加于

^4.0.0

## 1.文件匹配

### cssMatcher()?

> `optional` **cssMatcher**: (`name`) => `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:288](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L288)

匹配需要处理的 `wxss` 等样式文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

***

### htmlMatcher()?

> `optional` **htmlMatcher**: (`name`) => `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:282](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L282)

匹配需要处理的 `wxml` 等模板文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

***

### jsMatcher()?

> `optional` **jsMatcher**: (`name`) => `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:294](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L294)

匹配需要处理的编译后 `js` 文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

***

### mainCssChunkMatcher()?

> `optional` **mainCssChunkMatcher**: (`name`, `appType?`) => `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:302](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L302)

匹配负责注入 Tailwind CSS 变量作用域的 CSS Bundle。

#### 参数

##### name

`string`

##### appType?

`AppType`

#### 返回

`boolean`

#### 备注

在处理 `::before`/`::after` 等不兼容选择器时，建议手动指定文件位置。

## 1.文件匹配
 实验性质，有可能会改变

### inlineWxs?

> `optional` **inlineWxs**: `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:338](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L338)

**`Experimental`**

是否转义 `wxml` 中的内联 `wxs`。

#### 备注

使用前同样需要在 `tailwind.config.js` 中声明 `wxs` 格式。

#### 示例

```html
<!-- index.wxml -->
<wxs module="inline">
// 我是内联wxs
// 下方的类名会被转义
var className = "after:content-['我是className']"
module.exports = {
 className: className
}
</wxs>
<wxs src="./index.wxs" module="outside"/>
<view><view class="{{inline.className}}"></view><view class="{{outside.className}}"></view></view>
```

#### 默认值

```ts
false
```

***

### wxsMatcher()?

> `optional` **wxsMatcher**: (`name`) => `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:313](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L313)

**`Experimental`**

匹配各端的 `wxs`/`sjs`/`.filter.js` 文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

#### 备注

配置前请确保在 `tailwind.config.js` 的 `content` 中包含对应格式。

#### 默认值

```ts
()=>false
```

## 2.生命周期

### onEnd()?

> `optional` **onEnd**: () => `void`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:372](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L372)

结束处理时触发。

#### 返回

`void`

***

### onLoad()?

> `optional` **onLoad**: () => `void`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:348](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L348)

插件 `apply` 初始调用时触发。

#### 返回

`void`

***

### onStart()?

> `optional` **onStart**: () => `void`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:354](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L354)

开始处理前触发。

#### 返回

`void`

***

### onUpdate()?

> `optional` **onUpdate**: (`filename`, `oldVal`, `newVal`) => `void`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:366](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L366)

匹配并修改文件后触发。

#### 参数

##### filename

`string`

##### oldVal

`string`

##### newVal

`string`

#### 返回

`void`

## 3.一般配置

### appType?

> `optional` **appType**: `AppType`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:400](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L400)

声明所使用的框架类型。

#### 备注

用于辅助定位主要的 CSS bundle，以便默认的 `mainCssChunkMatcher` 做出更准确的匹配，未传入时将尝试自动猜测变量注入位置。

***

### arbitraryValues?

> `optional` **arbitraryValues**: `IArbitraryValues`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:407](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L407)

TailwindCSS 任意值的相关配置。

***

### babelParserOptions?

> `optional` **babelParserOptions**: `Partial`\<`Options`\> & `object`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:470](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L470)

`@babel/parser` 的配置选项。

#### 类型声明

##### cache?

> `optional` **cache**: `boolean`

##### cacheKey?

> `optional` **cacheKey**: `string`

#### 添加于

^3.2.0

***

### cache?

> `optional` **cache**: `boolean` \| `ICreateCacheReturnType`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:462](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L462)

控制缓存策略。

#### 添加于

^3.0.11

***

### cssChildCombinatorReplaceValue?

> `optional` **cssChildCombinatorReplaceValue**: `string` \| `string`[]

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:487](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L487)

自定义 Tailwind 子组合器的替换值。

#### 备注

为兼容小程序缺乏 `:not([hidden])~` 支持的限制，默认会将 `.space-x-4` 等选择器替换为 `view + view`。可传入字符串或字符串数组以扩展适用标签。
```css
// 数组示例
.space-y-4>view + view,text + text{}

// 字符串示例
.space-y-4>view,text,button,input ~ view,text,button,input{}
```

#### 默认值

```ts
'view + view'
```

***

### cssRemoveHoverPseudoClass?

> `optional` **cssRemoveHoverPseudoClass**: `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:506](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L506)

是否移除 CSS 中的 `:hover` 选择器。

#### 添加于

^3.2.1

#### 参阅

https://github.com/sonofmagic/weapp-tailwindcss/issues/293

#### 备注

小程序不支持 `:hover`，需要使用组件的 `hover-class`，因此默认删除相关节点。

#### 默认值

`true`

***

### cssRemoveProperty?

> `optional` **cssRemoveProperty**: `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:516](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L516)

是否移除 `@property` 节点。

#### 添加于

^4.1.2

#### 备注

微信小程序可识别 `@property`，但支付宝暂不支持，默认移除以避免构建失败。

#### 默认值

`true`

***

### disabledDefaultTemplateHandler?

> `optional` **disabledDefaultTemplateHandler**: `boolean`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:428](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L428)

禁用默认的 `wxml` 模板替换器。

#### 添加于

^2.6.2

#### 备注

启用后模板匹配完全交由 [`customAttributes`](/docs/api/interfaces/UserDefinedOptions#customattributes) 管理，需要自行覆盖默认的 `class` / `hover-class` 等匹配规则。

#### 默认值

```ts
false
```

***

### jsPreserveClass()?

> `optional` **jsPreserveClass**: (`keyword`) => `boolean` \| `undefined`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:417](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L417)

控制 JS 字面量是否需要保留。

#### 参数

##### keyword

`string`

#### 返回

`boolean` \| `undefined`

#### 添加于

^2.6.1

#### 备注

当 Tailwind 与 JS 字面量冲突时，可通过回调返回 `true` 保留当前值，返回 `false` 或 `undefined` 则继续转义。默认保留所有带 `*` 的字符串字面量。

***

### logLevel?

> `optional` **logLevel**: `"info"` \| `"warn"` \| `"error"` \| `"silent"`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:531](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L531)

控制命令行日志输出级别。

#### 备注

默认 `info`，可设置为 `silent` 屏蔽全部输出。

***

### postcssOptions?

> `optional` **postcssOptions**: `any`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:495](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L495)

`postcss` 的配置选项。

#### 添加于

^3.2.0

***

### supportCustomLengthUnitsPatch?

> `optional` **supportCustomLengthUnitsPatch**: `boolean` \| `ILengthUnitsPatchOptions`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:391](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L391)

控制 Tailwind 自定义长度单位补丁。

#### 参阅

https://github.com/sonofmagic/weapp-tailwindcss/issues/110

#### 备注

TailwindCSS 3.2.0 起对任意值执行长度单位校验，会将未声明的 `rpx` 识别为颜色。本选项默认开启以注入 `rpx` 支持。当 Node.js 在插件执行前已缓存 `tailwindcss` 模块时，首轮运行可能未生效，可通过在 `postinstall` 中执行 `weapp-tw patch` 提前打补丁。
```diff
"scripts": {
+  "postinstall": "weapp-tw patch"
}
```

***

### tailwindcssBasedir?

> `optional` **tailwindcssBasedir**: `string`

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:454](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L454)

指定用于获取 Tailwind 上下文的路径。

#### 添加于

^2.9.3

#### 备注

在 linked 或 monorepo 场景下可手动指向目标项目的 `package.json` 所在目录。

***

### tailwindcssPatcherOptions?

> `optional` **tailwindcssPatcherOptions**: [`TailwindcssPatchOptions`](TailwindcssPatchOptions.md)

定义于: [packages/weapp-tailwindcss/src/typedoc.export.ts:523](https://github.com/sonofmagic/weapp-tailwindcss/blob/3f74f29bbba2815e37d9171fddec7566d76a5099/packages/weapp-tailwindcss/src/typedoc.export.ts#L523)

自定义 patcher 参数。

---

## Class: UnifiedWebpackPluginV5

**`Name`**

UnifiedWebpackPluginV5

**`Description`**

webpack5 核心转义插件

**`Link`**

https://tw.icebreaker.top/docs/intro

## Implements

- [`IBaseWebpackPlugin`](../interfaces/IBaseWebpackPlugin.md)

## Constructors

### constructor

• **new UnifiedWebpackPluginV5**(`options?`): [`UnifiedWebpackPluginV5`](UnifiedWebpackPluginV5.md)

#### Parameters

| Name      | Type                                                        |
| :-------- | :---------------------------------------------------------- |
| `options` | [`UserDefinedOptions`](../interfaces/UserDefinedOptions.md) |

#### Returns

[`UnifiedWebpackPluginV5`](UnifiedWebpackPluginV5.md)

#### Defined in

[webpack/BaseUnifiedPlugin/v5.ts:24](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/webpack/BaseUnifiedPlugin/v5.ts#L24)

## Properties

### appType

• `Optional` **appType**: [`AppType`](../#apptype)

#### Implementation of

[IBaseWebpackPlugin](../interfaces/IBaseWebpackPlugin.md).[appType](../interfaces/IBaseWebpackPlugin.md#apptype)

#### Defined in

[webpack/BaseUnifiedPlugin/v5.ts:22](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/webpack/BaseUnifiedPlugin/v5.ts#L22)

---

### options

• **options**: `Required`<`Omit`<[`UserDefinedOptions`](../interfaces/UserDefinedOptions.md), `"customReplaceDictionary"` \| `"supportCustomLengthUnitsPatch"` \| [`GlobOrFunctionMatchers`](../#globorfunctionmatchers)\> & \{ `cssMatcher`: (`name`: `string`) => `boolean` ; `htmlMatcher`: (`name`: `string`) => `boolean` ; `jsMatcher`: (`name`: `string`) => `boolean` ; `mainCssChunkMatcher`: (`name`: `string`, `appType?`: [`AppType`](../#apptype)) => `boolean` ; `wxsMatcher`: (`name`: `string`) => `boolean` } & \{ `cache`: `ICreateCacheReturnType` ; `customReplaceDictionary`: `Record`<`string`, `string`\> ; `escapeMap`: `Record`<`string`, `string`\> ; `jsHandler`: [`JsHandler`](../#jshandler) ; `patch`: () => `void` ; `setMangleRuntimeSet`: (`runtimeSet`: `Set`<`string`\>) => `void` ; `styleHandler`: (`rawSource`: `string`, `options`: [`IStyleHandlerOptions`](../#istylehandleroptions)) => `Promise`<`string`\> ; `supportCustomLengthUnitsPatch`: `false` \| [`ILengthUnitsPatchOptions`](../interfaces/ILengthUnitsPatchOptions.md) ; `templateHandler`: (`rawSource`: `string`, `options?`: [`ITemplateHandlerOptions`](../interfaces/ITemplateHandlerOptions.md)) => `string` }\>

#### Implementation of

[IBaseWebpackPlugin](../interfaces/IBaseWebpackPlugin.md).[options](../interfaces/IBaseWebpackPlugin.md#options)

#### Defined in

[webpack/BaseUnifiedPlugin/v5.ts:21](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/webpack/BaseUnifiedPlugin/v5.ts#L21)

## Methods

### apply

▸ **apply**(`compiler`): `void`

#### Parameters

| Name       | Type       |
| :--------- | :--------- |
| `compiler` | `Compiler` |

#### Returns

`void`

#### Implementation of

[IBaseWebpackPlugin](../interfaces/IBaseWebpackPlugin.md).[apply](../interfaces/IBaseWebpackPlugin.md#apply)

#### Defined in

[webpack/BaseUnifiedPlugin/v5.ts:32](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/webpack/BaseUnifiedPlugin/v5.ts#L32)

---

## weapp-tailwindcss-webpack-plugin

## Classes

- [UnifiedWebpackPluginV5](classes/UnifiedWebpackPluginV5.md)

## Interfaces

- [IArbitraryValues](interfaces/IArbitraryValues.md)
- [IBaseWebpackPlugin](interfaces/IBaseWebpackPlugin.md)
- [ICommonReplaceOptions](interfaces/ICommonReplaceOptions.md)
- [ILengthUnitsPatchDangerousOptions](interfaces/ILengthUnitsPatchDangerousOptions.md)
- [ILengthUnitsPatchOptions](interfaces/ILengthUnitsPatchOptions.md)
- [IPropValue](interfaces/IPropValue.md)
- [ITemplateHandlerOptions](interfaces/ITemplateHandlerOptions.md)
- [InternalCssSelectorReplacerOptions](interfaces/InternalCssSelectorReplacerOptions.md)
- [InternalPatchResult](interfaces/InternalPatchResult.md)
- [RawSource](interfaces/RawSource.md)
- [UserDefinedOptions](interfaces/UserDefinedOptions.md)

## Type Aliases

### AppType

Ƭ **AppType**: `"uni-app"` \| `"uni-app-vite"` \| `"taro"` \| `"remax"` \| `"rax"` \| `"native"` \| `"kbone"` \| `"mpx"`

#### Defined in

[types.ts:10](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L10)

---

### CreateJsHandlerOptions

Ƭ **CreateJsHandlerOptions**: `Omit`<[`IJsHandlerOptions`](#ijshandleroptions), `"classNameSet"`\>

#### Defined in

[types.ts:502](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L502)

---

### CssPreflightOptions

Ƭ **CssPreflightOptions**: \{ `[key: CssPresetProps]`: `string` \| `number` \| `boolean`; } \| `false`

#### Defined in

[types.ts:19](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L19)

---

### CssPresetProps

Ƭ **CssPresetProps**: `string`

#### Defined in

[types.ts:17](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L17)

### GlobOrFunctionMatchers

Ƭ **GlobOrFunctionMatchers**: `"htmlMatcher"` \| `"cssMatcher"` \| `"jsMatcher"` \| `"mainCssChunkMatcher"` \| `"wxsMatcher"`

#### Defined in

[types.ts:460](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L460)

---

### ICustomAttributes

Ƭ **ICustomAttributes**: `Record`<`string`, [`ItemOrItemArray`](#itemoritemarray)<`string` \| `RegExp`\>\> \| `Map`<`string` \| `RegExp`, [`ItemOrItemArray`](#itemoritemarray)<`string` \| `RegExp`\>\>

#### Defined in

[types.ts:50](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L50)

---

### ICustomAttributesEntities

Ƭ **ICustomAttributesEntities**: [`string` \| `RegExp`, [`ItemOrItemArray`](#itemoritemarray)<`string` \| `RegExp`\>][]

#### Defined in

[types.ts:52](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L52)

---

### IJsHandlerOptions

Ƭ **IJsHandlerOptions**: `Object`

#### Type declaration

| Name               | Type                                                                             |
| :----------------- | :------------------------------------------------------------------------------- |
| `arbitraryValues?` | [`IArbitraryValues`](interfaces/IArbitraryValues.md)                             |
| `classNameSet`     | `Set`<`string`\>                                                                 |
| `escapeMap?`       | `Record`<`string`, `string`\>                                                    |
| `generateMap?`     | `boolean`                                                                        |
| `jsPreserveClass?` | (`keyword`: `string`) => `boolean` \| `undefined`                                |
| `minifiedJs?`      | `boolean`                                                                        |
| `needEscaped?`     | `boolean`                                                                        |
| `strategy?`        | [`UserDefinedOptions`](interfaces/UserDefinedOptions.md)[``"jsEscapeStrategy"``] |

#### Defined in

[types.ts:54](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L54)

---

### IStyleHandlerOptions

Ƭ **IStyleHandlerOptions**: [`RequiredStyleHandlerOptions`](#requiredstylehandleroptions) & \{ `ctx?`: `IContext` ; `postcssOptions?`: [`LoadedPostcssOptions`](#loadedpostcssoptions) ; `cssRemoveProperty?`: `boolean` ; `cssRemoveHoverPseudoClass?`: `boolean` ; `cssPresetEnv?`: [`PresetEnvOptions`](#presetenvoptions) ; `cssCalc?`: `boolean` \| [`CssCalcOptions`](#csscalcoptions) \| (`string` \| `RegExp`)[] ; `atRules?`: \{ `property?`: `boolean` ; `supports?`: `boolean` ; `media?`: `boolean`  } ; `uniAppX?`: `boolean` ; `majorVersion?`: `number`  }

#### Defined in

[types.ts:41](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L41)

---

### InternalPostcssOptions

Ƭ **InternalPostcssOptions**: `Pick`<[`UserDefinedOptions`](interfaces/UserDefinedOptions.md), `"cssMatcher"` \| `"mainCssChunkMatcher"` \| `"cssPreflight"` \| `"replaceUniversalSelectorWith"` \| `"cssPreflightRange"` \| `"disabled"`\>

#### Defined in

[types.ts:479](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L479)

---

### InternalUserDefinedOptions

Ƭ **InternalUserDefinedOptions**: `Required`<`Omit`<[`UserDefinedOptions`](interfaces/UserDefinedOptions.md), [`GlobOrFunctionMatchers`](#globorfunctionmatchers) \| `"supportCustomLengthUnitsPatch"` \| `"customReplaceDictionary"`\> & \{ [K in GlobOrFunctionMatchers]: K extends "mainCssChunkMatcher" ? Function : Function } & \{ `cache`: `ICreateCacheReturnType` ; `customReplaceDictionary`: `Record`<`string`, `string`\> ; `escapeMap`: `Record`<`string`, `string`\> ; `jsHandler`: [`JsHandler`](#jshandler) ; `patch`: () => `void` ; `setMangleRuntimeSet`: (`runtimeSet`: `Set`<`string`\>) => `void` ; `styleHandler`: (`rawSource`: `string`, `options`: [`IStyleHandlerOptions`](#istylehandleroptions)) => `Promise`<`string`\> ; `supportCustomLengthUnitsPatch`: [`ILengthUnitsPatchOptions`](interfaces/ILengthUnitsPatchOptions.md) \| `false` ; `templateHandler`: (`rawSource`: `string`, `options?`: [`ITemplateHandlerOptions`](interfaces/ITemplateHandlerOptions.md)) => `string` }\>

#### Defined in

[types.ts:462](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L462)

---

### ItemOrItemArray

Ƭ **ItemOrItemArray**<`T`\>: `T` \| `T`[]

#### Type parameters

| Name |
| :--- |
| `T`  |

#### Defined in

[types.ts:8](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L8)

---

### JsHandler

Ƭ **JsHandler**: (`rawSource`: `string`, `set`: `Set`<`string`\>, `options?`: [`CreateJsHandlerOptions`](#createjshandleroptions)) => [`JsHandlerResult`](#jshandlerresult)

#### Type declaration

▸ (`rawSource`, `set`, `options?`): [`JsHandlerResult`](#jshandlerresult)

##### Parameters

| Name        | Type                                                |
| :---------- | :-------------------------------------------------- |
| `rawSource` | `string`                                            |
| `set`       | `Set`<`string`\>                                    |
| `options?`  | [`CreateJsHandlerOptions`](#createjshandleroptions) |

##### Returns

[`JsHandlerResult`](#jshandlerresult)

#### Defined in

[types.ts:428](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L428)

---

### JsHandlerReplaceResult

Ƭ **JsHandlerReplaceResult**: `Object`

#### Type declaration

| Name   | Type        |
| :----- | :---------- |
| `code` | `string`    |
| `map?` | `SourceMap` |

#### Defined in

[types.ts:46](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L46)

---

### JsHandlerResult

Ƭ **JsHandlerResult**: [`JsHandlerReplaceResult`](#jshandlerreplaceresult) \| `GeneratorResult`

#### Defined in

[types.ts:48](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L48)

---

### RequiredStyleHandlerOptions

Ƭ **RequiredStyleHandlerOptions**: \{ `cssInjectPreflight?`: `InjectPreflight` ; `escapeMap?`: `Record`<`string`, `string`\> ; `isMainChunk`: `boolean` } & `Pick`<[`UserDefinedOptions`](interfaces/UserDefinedOptions.md), `"cssPreflightRange"` \| `"cssChildCombinatorReplaceValue"` \| `"replaceUniversalSelectorWith"` \| `"injectAdditionalCssVarScope"` \| `"cssSelectorReplacement"`\>

#### Defined in

[types.ts:25](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L25)

### LoadedPostcssOptions

`LoadedPostcssOptions` 是 `postcss-load-config` 导出的 `Result` 类型去掉 `file` 字段后再取 `Partial`。在插件内部用于接收已经过 `postcss-load-config` 解析的运行时配置，例如自定义插件、语法语义等设置。

#### 定义

```ts
type LoadedPostcssOptions = Partial<Omit<Result, 'file'>>
```

#### 定义于

[packages/postcss/src/types.ts:14](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/packages/postcss/src/types.ts#L14)

### PresetEnvOptions

`PresetEnvOptions` 直接复用自 `postcss-preset-env` 的 `pluginOptions`，用于控制 `stage`、`browsers`、`features` 等行为。传入该类型可以在保持 Docusaurus 生成文档一致的同时，自由扩展 CSS 预处理特性。

#### 定义

```ts

```

#### 定义于

[packages/postcss/src/types.ts:8](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/packages/postcss/src/types.ts#L8)

### CssCalcOptions

`CssCalcOptions` 基于 `@weapp-tailwindcss/postcss-calc` 的 `PostCssCalcOptions` 扩展而来，并额外提供 `includeCustomProperties`，用于声明哪些自定义属性需要参与 `calc` 计算或在输出中保留。

#### 定义

```ts
interface CssCalcOptions extends PostCssCalcOptions {
  includeCustomProperties?: (string | RegExp)[]
}
```

#### 定义于

[packages/postcss/src/types.ts:45](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/packages/postcss/src/types.ts#L45)

## Functions

### UnifiedViteWeappTailwindcssPlugin

▸ **UnifiedViteWeappTailwindcssPlugin**(`options?`): `Plugin` \| `undefined`

#### Parameters

| Name      | Type                                                     |
| :-------- | :------------------------------------------------------- |
| `options` | [`UserDefinedOptions`](interfaces/UserDefinedOptions.md) |

#### Returns

`Plugin` \| `undefined`

**`Name`**

UnifiedViteWeappTailwindcssPlugin

**`Description`**

uni-app vite vue3 版本插件

**`Link`**

https://tw.icebreaker.top/docs/quick-start/frameworks/uni-app-vite

#### Defined in

[vite/index.ts:17](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/vite/index.ts#L17)

---

### createPlugins

▸ **createPlugins**(`options?`): `Object`

#### Parameters

| Name      | Type                                                     |
| :-------- | :------------------------------------------------------- |
| `options` | [`UserDefinedOptions`](interfaces/UserDefinedOptions.md) |

#### Returns

`Object`

| Name            | Type              |
| :-------------- | :---------------- |
| `transformJs`   | () => `Transform` |
| `transformWxml` | () => `Transform` |
| `transformWxss` | () => `Transform` |

**`Name`**

weapp-tw-gulp

**`Description`**

gulp版本weapp-tw插件

**`Link`**

https://tw.icebreaker.top/docs/quick-start/frameworks/native

#### Defined in

[gulp/index.ts:17](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/gulp/index.ts#L17)

---

## Interface: IArbitraryValues

## Properties

### allowDoubleQuotes

• `Optional` **allowDoubleQuotes**: `boolean`

是否允许在类名里，使用双引号。
建议不要开启，因为有些框架，比如 `vue3` 它针对有些静态模板会直接编译成 `html` 字符串，此时开启这个配置很有可能导致转义出错

**`Example`**

```html
<!-- 开启前默认只允许单引号 -->
<view class="after:content-['对酒当歌，人生几何']"></view>
<!-- 开启后 -->
<view class="after:content-[\"对酒当歌，人生几何\"]"></view>
```

**`Default`**

`false`

#### Defined in

[types.ts:114](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L114)

---

## Interface: IBaseWebpackPlugin

## Implemented by

- [`UnifiedWebpackPluginV5`](../classes/UnifiedWebpackPluginV5.md)

## Properties

### appType

• `Optional` **appType**: [`AppType`](../#apptype)

#### Defined in

[types.ts:488](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L488)

---

### apply

• **apply**: (`compiler`: `any`) => `void`

#### Type declaration

▸ (`compiler`): `void`

##### Parameters

| Name       | Type  |
| :--------- | :---- |
| `compiler` | `any` |

##### Returns

`void`

#### Defined in

[types.ts:490](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L490)

---

### options

• **options**: `Required`<`Omit`<[`UserDefinedOptions`](UserDefinedOptions.md), `"customReplaceDictionary"` \| `"supportCustomLengthUnitsPatch"` \| [`GlobOrFunctionMatchers`](../#globorfunctionmatchers)\> & \{ `cssMatcher`: (`name`: `string`) => `boolean` ; `htmlMatcher`: (`name`: `string`) => `boolean` ; `jsMatcher`: (`name`: `string`) => `boolean` ; `mainCssChunkMatcher`: (`name`: `string`, `appType?`: [`AppType`](../#apptype)) => `boolean` ; `wxsMatcher`: (`name`: `string`) => `boolean` } & \{ `cache`: `ICreateCacheReturnType` ; `customReplaceDictionary`: `Record`<`string`, `string`\> ; `escapeMap`: `Record`<`string`, `string`\> ; `jsHandler`: [`JsHandler`](../#jshandler) ; `patch`: () => `void` ; `setMangleRuntimeSet`: (`runtimeSet`: `Set`<`string`\>) => `void` ; `styleHandler`: (`rawSource`: `string`, `options`: [`IStyleHandlerOptions`](../#istylehandleroptions)) => `Promise`<`string`\> ; `supportCustomLengthUnitsPatch`: `false` \| [`ILengthUnitsPatchOptions`](ILengthUnitsPatchOptions.md) ; `templateHandler`: (`rawSource`: `string`, `options?`: [`ITemplateHandlerOptions`](ITemplateHandlerOptions.md)) => `string` }\>

#### Defined in

[types.ts:487](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L487)

---

## Interface: ICommonReplaceOptions

## Hierarchy

- **`ICommonReplaceOptions`**

  ↳ [`ITemplateHandlerOptions`](ITemplateHandlerOptions.md)

## Properties

### escapeMap

• `Optional` **escapeMap**: `Record`<`string`, `string`\>

#### Defined in

[types.ts:442](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L442)

---

### keepEOL

• `Optional` **keepEOL**: `boolean`

#### Defined in

[types.ts:441](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L441)

---

## Interface: ILengthUnitsPatchDangerousOptions

## Properties

### destPath

• `Optional` **destPath**: `string`

#### Defined in

[types.ts:81](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L81)

---

### gteVersion

• `Optional` **gteVersion**: `string`

#### Defined in

[types.ts:77](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L77)

---

### lengthUnitsFilePath

• `Optional` **lengthUnitsFilePath**: `string`

#### Defined in

[types.ts:78](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L78)

---

### overwrite

• `Optional` **overwrite**: `boolean`

#### Defined in

[types.ts:80](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L80)

---

### packageName

• `Optional` **packageName**: `string`

#### Defined in

[types.ts:76](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L76)

---

### variableName

• `Optional` **variableName**: `string`

#### Defined in

[types.ts:79](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L79)

---

## Interface: ILengthUnitsPatchOptions

**`Deprecated`**

## Properties

### basedir

• `Optional` **basedir**: `string`

#### Defined in

[types.ts:91](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L91)

---

### dangerousOptions

• `Optional` **dangerousOptions**: [`ILengthUnitsPatchDangerousOptions`](ILengthUnitsPatchDangerousOptions.md)

#### Defined in

[types.ts:90](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L90)

---

### paths

• `Optional` **paths**: `string`[]

#### Defined in

[types.ts:89](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L89)

---

### units

• **units**: `string`[]

#### Defined in

[types.ts:88](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L88)

---

## Interface: IPropValue

## Properties

### prop

• **prop**: `string`

#### Defined in

[types.ts:13](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L13)

---

### value

• **value**: `string`

#### Defined in

[types.ts:14](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L14)

---

## Interface: ITemplateHandlerOptions

## Hierarchy

- [`ICommonReplaceOptions`](ICommonReplaceOptions.md)

  ↳ **`ITemplateHandlerOptions`**

## Properties

### customAttributesEntities

• `Optional` **customAttributesEntities**: [`ICustomAttributesEntities`](../#icustomattributesentities)

#### Defined in

[types.ts:447](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L447)

---

### disabledDefaultTemplateHandler

• `Optional` **disabledDefaultTemplateHandler**: `boolean`

#### Defined in

[types.ts:456](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L456)

---

### escapeMap

• `Optional` **escapeMap**: `Record`<`string`, `string`\>

#### Overrides

[ICommonReplaceOptions](ICommonReplaceOptions.md).[escapeMap](ICommonReplaceOptions.md#escapemap)

#### Defined in

[types.ts:451](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L451)

---

### inlineWxs

• `Optional` **inlineWxs**: `boolean`

#### Defined in

[types.ts:453](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L453)

---

### jsHandler

• `Optional` **jsHandler**: [`JsHandler`](../#jshandler)

#### Defined in

[types.ts:454](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L454)

---

### keepEOL

• `Optional` **keepEOL**: `boolean`

#### Inherited from

[ICommonReplaceOptions](ICommonReplaceOptions.md).[keepEOL](ICommonReplaceOptions.md#keepeol)

#### Defined in

[types.ts:441](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L441)

### quote

• `Optional` **quote**: `null` \| `string`

#### Defined in

[types.ts:457](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L457)

---

### runtimeSet

• `Optional` **runtimeSet**: `Set`<`string`\>

#### Defined in

[types.ts:455](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L455)

---

## Interface: InternalCssSelectorReplacerOptions

## Properties

### escapeMap

• `Optional` **escapeMap**: `Record`<`string`, `string`\>

#### Defined in

[types.ts:38](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L38)

---

## Interface: InternalPatchResult

**`Description`**

InternalPatchResult

## Properties

### dataTypes

• `Optional` **dataTypes**: `string`

#### Defined in

[types.ts:497](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L497)

---

### plugin

• `Optional` **plugin**: `string`

#### Defined in

[types.ts:499](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L499)

---

### processTailwindFeatures

• `Optional` **processTailwindFeatures**: `string`

#### Defined in

[types.ts:498](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L498)

---

## Interface: RawSource

## Properties

### end

• **end**: `number`

#### Defined in

[types.ts:67](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L67)

---

### raw

• **raw**: `string`

#### Defined in

[types.ts:68](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L68)

---

### source

• `Optional` **source**: `string`

#### Defined in

[types.ts:70](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L70)

---

### start

• **start**: `number`

#### Defined in

[types.ts:66](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L66)

---

## Interface: UserDefinedOptions

## Properties

### appType

• `Optional` **appType**: [`AppType`](../#apptype)

**`Description`**

使用的框架类型(uni-app,taro...)，用于找到主要的 `css bundle` 进行转化，这个配置会影响默认方法 `mainCssChunkMatcher` 的行为，不传会去猜测 `tailwindcss css var inject scope` 的位置

#### Defined in

[types.ts:284](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L284)

---

### arbitraryValues

• `Optional` **arbitraryValues**: [`IArbitraryValues`](IArbitraryValues.md)

**`Description`**

针对 tailwindcss arbitrary values 的一些配置

#### Defined in

[types.ts:301](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L301)

---

### cssChildCombinatorReplaceValue

• `Optional` **cssChildCombinatorReplaceValue**: `string` \| `string`[]

**`Description`**

用于控制 tailwindcss 子组合器的生效标签范围, 这里我们用一个例子来说明这个配置是干啥用的.

我们布局的时候往往会使用 `space-x-4`
那么实际上会生成这样的css选择器:

```css
.space-x-4>:not([hidden])~:not([hidden]){}
```

然而很不幸，这个选择器在小程序中是不支持的，写了会报错导致编译失败。
所以出于保守起见，我把它替换为了：

```css
.space-x-4>view + view{}
```

这同时也是默认值, 而这个选项就允许你进行自定义子组合器的行为

你可以传入一个 字符串，或者字符串数组

1. 传入字符串数组,比如 `['view','text']` 生成:

```css
.space-y-4>view + view,text + text{}
```

2. 传入一个字符串，此时行为变成了整个替换，比如 `'view,text,button,input ~ view,text,button,input'` 生成:

```css
.space-y-4>view,text,button,input ~ view,text,button,input{}
```

**`Default`**

```ts
'view + view'
```

#### Defined in

[types.ts:329](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L329)

---

### cssMatcher

• `Optional` **cssMatcher**: `string` \| `string`[] \| (`name`: `string`) => `boolean`

**`Description`**

匹配 `wxss` 等等样式文件的方法，支持 `glob` by [micromatch](https://github.com/micromatch/micromatch)

#### Defined in

[types.ts:125](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L125)

---

### cssPreflight

• `Optional` **cssPreflight**: [`CssPreflightOptions`](../#csspreflightoptions)

**`Issue`**

<https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/7>

**`Description`**

在所有 view节点添加的 css 预设，可根据情况自由的禁用原先的规则，或者添加新的规则。 详细用法如下:

```js
// default 默认:
cssPreflight: {
'box-sizing': 'border-box',
'border-width': '0',
'border-style': 'solid',
'border-color': 'currentColor'
}
// result
// box-sizing: border-box;
// border-width: 0;
// border-style: solid;
// border-color: currentColor

// case 禁用所有
cssPreflight: false
// result
// none

// case 禁用单个属性
cssPreflight: {
'box-sizing': false
}
// border-width: 0;
// border-style: solid;
// border-color: currentColor

// case 更改和添加单个属性
cssPreflight: {
'box-sizing': 'content-box',
'background': 'black'
}
// result
// box-sizing: content-box;
// border-width: 0;
// border-style: solid;
// border-color: currentColor;
// background: black
```

#### Defined in

[types.ts:178](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L178)

---

### cssPreflightRange

• `Optional` **cssPreflightRange**: `"view"` \| `"all"`

**`Issue`**

<https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/pull/62>

**`Description`**

全局`dom`选择器，只有在这个选择器作用范围内的`dom`会被注入 `cssPreflight` 的变量和默认样式。默认为 `'view'` 即只对所有的 `view` 和伪元素生效，想要对所有的元素生效，可切换为 `'all'`,此时需要自行处理和客户端默认样式的冲突

#### Defined in

[types.ts:184](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L184)

---

### cssSelectorReplacement

• `Optional` **cssSelectorReplacement**: `Object`

#### Type declaration

| Name         | Type                | Description               |
| :----------- | :------------------ | :------------------------ |
| `root?`      | `string` \| `false` | **`Default`** `ts 'page'` |
| `universal?` | `string` \| `false` | **`Default`** `ts 'view'` |

#### Defined in

[types.ts:410](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L410)

---

### customAttributes

• `Optional` **customAttributes**: [`ICustomAttributes`](../#icustomattributes)

**`Description`**

**这是一个重要的配置!**

它可以自定义`wxml`标签上的`attr`转化属性。默认转化所有的`class`和`hover-class`，这个`Map`的 `key`为匹配标签，`value`为属性字符串或者匹配正则数组。

如果你想要增加，对于所有标签都生效的转化的属性，你可以添加 `*`: `(string | Regexp)[]` 这样的键值对。(`*` 是一个特殊值，代表所有标签)

更复杂的情况，可以传一个 `Map<string | Regex, (string | Regex)[]>`实例。

假如你要把 `className` 通过组件的`prop`传递给子组件，又或者想要自定义转化的标签属性时，需要用到此配置，案例详见：[issue#129](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/129#issuecomment-1340914688),[issue#134](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/134#issuecomment-1351288238)

**`Example`**

```js
const customAttributes = {
// 匹配所有带 Class / class 相关的标签，比如 `a-class`, `testClass` , `custom-class` 里的值
'*': [ /[A-Za-z]?[A-Za-z-]*[Cc]lass/ ],
// 额外匹配转化 `van-image` 标签上的 `custom-class` 的值
'van-image': ['custom-class'],
'ice-button': ['testClass']
}
```

当然你可以根据自己的需求，定义单个或者多个正则/字符串。

甚至有可能你编写正则表达式，它们匹配的范围，直接包括了插件里自带默认的 `class`/`hover-class`，那么这种情况下，你完全可以取代插件的默认模板转化器，开启 [disabledDefaultTemplateHandler](/docs/api/interfaces/UserDefinedOptions#disableddefaulttemplatehandler) 配置项,禁用默认的模版匹配转化器。

#### Defined in

[types.ts:251](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L251)

---

### customReplaceDictionary

• `Optional` **customReplaceDictionary**: `Record`<`string`, `string`\> \| `"simple"` \| `"complex"`

**`Description`**

自定义转化class名称字典，这个配置项用来自定义转化`class`名称字典,你可以使用这个选项来简化生成的`class`

插件中内置了`'simple'`模式和`'complex'`模式:

- `'simple'`模式: 把小程序中不允许的字符串，转义为**相等长度**的代替字符串，这种情况不追求转化目标字符串的一比一绝对等价，即无法从生成结果，反推原先的`class`
- `'complex'`模式: 把小程序中不允许的字符串，转义为**更长**的代替字符串，这种情况转化前后的字符串是等价的，可以从结果进行反推，缺点就是会生成更长的 `class` 导致 `wxml`和`wxss`这类的体积增大

当然，你也可以自定义，传一个 `Record<string, string>` 类型，只需保证转化后 css 中的 `class` 选择器，不会和自己定义的 `class` 产生冲突即可，示例见[dic.ts](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/blob/main/src/dic.ts)

**`Default`**

```ts
'simple'
```

#### Defined in

[types.ts:263](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L263)

### disabled

• `Optional` **disabled**: `boolean`

**`Description`**

是否禁用此插件，一般用于构建到多平台时使用

#### Defined in

[types.ts:196](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L196)

---

### disabledDefaultTemplateHandler

• `Optional` **disabledDefaultTemplateHandler**: `boolean`

**`Version`**

`^2.6.2`

**`Description`**

开启此选项，将会禁用默认 `wxml` 模板替换器，此时模板的匹配和转化将完全被 [`customAttributes`](/docs/api/interfaces/UserDefinedOptions#customattributes) 接管，

此时你需要自己编写匹配之前默认 `class`/`hover-class`，以及新的标签属性的正则表达式`regex`

**`Default`**

```ts
false
```

#### Defined in

[types.ts:389](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L389)

---

### htmlMatcher

• `Optional` **htmlMatcher**: `string` \| `string`[] \| (`name`: `string`) => `boolean`

**`Description`**

匹配 `wxml`等等模板进行处理的方法，支持 `glob` by [micromatch](https://github.com/micromatch/micromatch)

#### Defined in

[types.ts:121](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L121)

---

### injectAdditionalCssVarScope

• `Optional` **injectAdditionalCssVarScope**: `boolean`

**`Version`**

`^2.6.0`

**`Description`**

是否注入额外的 `tailwindcss css var scope` 区域，这个选项用于这样的场景

比如 `taro vue3` 使用 [NutUI](https://nutui.jd.com), 需要使用 `@tarojs/plugin-html`，而这个插件会启用 `postcss-html-transform` 从而移除所有带 `*` 选择器

这会导致 `tailwindcss css var scope` 区域被移除导致一些样式，比如渐变等等功能失效

这种场景下，启用这个选项会再次重新注入整个 `tailwindcss css var scope`

**`Default`**

```ts
false
```

#### Defined in

[types.ts:373](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L373)

---

### inlineWxs

• `Optional` **inlineWxs**: `boolean`

**`Experiment`**

实验性质，有可能会改变

**`Description`**

是否转义 `wxml` 中内联的 `wxs`

> tip: 记得在 `tailwind.config.js` 中，把 `wxs` 这个格式加入 `content` 配置项，不然不会生效

**`Example`**

```html
<!-- index.wxml -->
<wxs module="inline">
// 我是内联wxs
// 下方的类名会被转义
var className = "after:content-['我是className']"
module.exports = {
 className: className
}
</wxs>
<wxs src="./index.wxs" module="outside"/>
<view><view class="{{inline.className}}"></view><view class="{{outside.className}}"></view></view>
```

**`Default`**

```ts
false
```

#### Defined in

[types.ts:359](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L359)

---

### jsEscapeStrategy

• `Optional` **jsEscapeStrategy**: `"regenerate"` \| `"replace"`

**`Version`**

`^2.7.0`

**`Description`**

js 字面量以及模板字符串的转义替换模式

- `regenerate` 模式，为需要转义的字面量，重新生成相同语义的字符串, （默认的传统模式）
- `replace` 模式，为在原版本字符串上直接精准替换, (`2.7.0+` 新增)

如果用一个比喻来形容，那么 `regenerate` 类似于创造一个双胞胎，而 `replace` 模式就类似于一把精准的手术刀

> `replace` 模式已经在 `2.8.0` 版本中，成为默认模式，另外使用这个模式之后，生成相关的参数，比如 `minifiedJs` 就会失效了。

**`Default`**

```ts
'regenerate'
```

#### Defined in

[types.ts:402](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L402)

---

### jsMatcher

• `Optional` **jsMatcher**: `string` \| `string`[] \| (`name`: `string`) => `boolean`

**`Description`**

匹配编译后 `js` 文件进行处理的方法，支持 `glob` by [micromatch](https://github.com/micromatch/micromatch)

#### Defined in

[types.ts:129](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L129)

---

### jsPreserveClass

• `Optional` **jsPreserveClass**: (`keyword`: `string`) => `undefined` \| `boolean`

#### Type declaration

▸ (`keyword`): `undefined` \| `boolean`

##### Parameters

| Name      | Type     |
| :-------- | :------- |
| `keyword` | `string` |

##### Returns

`undefined` \| `boolean`

**`Version`**

`^2.6.1`

**`Description`**

当 `tailwindcss` 和 `js` 处理的字面量撞车的时候，配置此选项可以用来保留js字面量，不进行转义处理。返回值中，想要当前js字面量保留，则返回 `true`。想要转义则返回 `false/undefined`

**`Default`**

保留所有带 `*` js字符串字面量

#### Defined in

[types.ts:380](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L380)

---

### mainCssChunkMatcher

• `Optional` **mainCssChunkMatcher**: `string` \| `string`[] \| (`name`: `string`, `appType?`: [`AppType`](../#apptype)) => `boolean`

**`Description`**

`tailwindcss css var inject scope` 的匹配方法,用于处理原始变量和替换不兼容选择器。可以不传，但是遇到某些 `::before/::after` 选择器注入冲突时，建议传入参数手动指定 css bundle 文件位置

#### Defined in

[types.ts:134](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L134)

### minifiedJs

• `Optional` **minifiedJs**: `boolean`

**`Description`**

是否压缩 js (`process.env.NODE_ENV` 为 `production` 时默认开启)

**`Default`**

```ts
process.env.NODE_ENV === 'production'
```

#### Defined in

[types.ts:290](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L290)

---

### onEnd

• `Optional` **onEnd**: () => `void`

#### Type declaration

▸ (): `void`

##### Returns

`void`

**`Description`**

结束处理时调用

#### Defined in

[types.ts:222](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L222)

---

### onLoad

• `Optional` **onLoad**: () => `void`

#### Type declaration

▸ (): `void`

##### Returns

`void`

**`Description`**

plugin apply 初调用

#### Defined in

[types.ts:206](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L206)

---

### onStart

• `Optional` **onStart**: () => `void`

#### Type declaration

▸ (): `void`

##### Returns

`void`

**`Description`**

开始处理时调用

#### Defined in

[types.ts:210](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L210)

---

### onUpdate

• `Optional` **onUpdate**: (`filename`: `string`, `oldVal`: `string`, `newVal`: `string`) => `void`

#### Type declaration

▸ (`filename`, `oldVal`, `newVal`): `void`

##### Parameters

| Name       | Type     |
| :--------- | :------- |
| `filename` | `string` |
| `oldVal`   | `string` |
| `newVal`   | `string` |

##### Returns

`void`

**`Description`**

匹配成功并修改文件内容后调用

#### Defined in

[types.ts:218](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L218)

---

### replaceUniversalSelectorWith

• `Optional` **replaceUniversalSelectorWith**: `string` \| `false`

**`Issue`**

<https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/81>

**`Default`**

```ts
'view'
```

**`Description`**

把`css`中的全局选择器 **`*`** 替换为指定值，默认替换为 `'view'`，设置为 `false` 时不进行替换，此时小程序会由于不认识`*`选择器而报错

#### Defined in

[types.ts:191](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L191)

---

### supportCustomLengthUnitsPatch

• `Optional` **supportCustomLengthUnitsPatch**: `boolean` \| [`ILengthUnitsPatchOptions`](ILengthUnitsPatchOptions.md)

**`Deprecated`**

**`Issue`**

<https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/110>

**`Description`**

自从`tailwindcss 3.2.0`对任意值添加了长度单位的校验后，小程序中的`rpx`这个`wxss`单位，由于不在长度合法名单中，于是被识别成了颜色，导致与预期不符，详见：[issues/110](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/110)。所以这个选项是用来给`tailwindcss`运行时，自动打上一个支持`rpx`单位的补丁。默认开启，在绝大部分情况下，你都可以忽略这个配置项，除非你需要更高级的自定义。

> 目前自动检索存在一定的缺陷，它会在第一次运行的时候不生效，关闭后第二次运行才生效。这是因为 nodejs 运行时先加载好了 `tailwindcss` 模块 ，然后再来运行这个插件，自动给 `tailwindcss` 运行时打上 `patch`。此时由于 `tailwindcss` 模块已经加载，所以 `patch` 在第一次运行时不生效，`ctrl+c` 关闭之后，再次运行才生效。这种情况可以使用:

```diff
"scripts": {
+  "postinstall": "weapp-tw patch"
}
```

使用 `npm hooks` 的方式来给 `tailwindcss` 自动打 `patch`

#### Defined in

[types.ts:279](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L279)

---

### tailwindcssBasedir

• `Optional` **tailwindcssBasedir**: `string`

**`Version`**

`^2.9.3`

**`Description`**

用于指定路径来获取 tailwindcss 上下文，一般情况下不用传入，使用 linked / monorepo 可能需要指定具体位置，路径通常是目标项目的 package.json 所在目录

#### Defined in

[types.ts:425](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L425)

---

### wxsMatcher

• `Optional` **wxsMatcher**: `string` \| `string`[] \| (`name`: `string`) => `boolean`

**`Experiment`**

实验性质，有可能会改变

**`Description`**

各个平台 `wxs` 文件的匹配方法,可以设置为包括微信的 .wxs,支付宝的 .sjs 和 百度小程序的 .filter.js

> tip: 记得在 `tailwind.config.js` 中，把 `wxs` 这个格式加入 `content` 配置项，不然不会生效

**`Default`**

```ts
()=>false
```

#### Defined in

[types.ts:337](https://github.com/sonofmagic/weapp-tailwindcss/blob/54db673b/src/types.ts#L337)

---

## 使用 arbitrary values


`arbitrary values` 是 `tailwindcss v3` 的重要更新内容，幸运的是你使用了本插件。

使得你可以使用 `tailwindcss v3` 强大的 `arbitrary values` 功能。

比如:

```html
<view :class="[flag?'bg-red-900':'bg-[#fafa00]']">bg-[#fafa00]</view>
<view :class="{'bg-[#098765]':flag===true}">bg-[#098765]</view>
<view class="p-[20px] -mt-2 !mb-[-20px] ">p-[20px] -mt-2 mb-[-20px] margin的jit 不能这么写 -m-[20px]</view>
<view class="space-y-[1.6rem]">
  <view class="w-[300rpx] text-black text-opacity-[0.19]">w-[300rpx] text-black text-opacity-[0.19]</view>
  <view class="min-w-[300rpx] max-h-[100px] text-[20px] leading-[0.9]">min-w-[300rpx] max-h-[100px] text-[20px] leading-[0.9]</view>
  <view class="max-w-[300rpx] min-h-[100px] text-[#dddddd]">max-w-[300rpx] min-h-[100px] text-[#dddddd]</view>
  <view class="flex items-center justify-center h-[100px] w-[100px] rounded-[40px] bg-[#123456] bg-opacity-[0.54] text-[#ffffff]">Hello</view>
  <view class="border-[10px] border-[#098765] border-solid border-opacity-[0.44]">border-[10px] border-[#098765] border-solid border-opacity-[0.44]</view>
  <view class="grid grid-cols-3 divide-x-[10px] divide-[#010101] divide-solid">
    <view>1</view>
    <view>2</view>
    <view>3</view>
  </view>
</view>
```

or `@apply`

```html
<template><view class="hello">world</view></template>
<style lang="scss">
.hello {
  @apply flex items-center justify-center h-[100px] w-[100px] rounded-[40px] bg-[#123456] bg-opacity-[0.54] text-[#ffffff] #{!important};
}
</style>
```

详见 [tailwindcss/using-arbitrary-values 章节](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values)

---

## js 中的精确转化与忽略


默认对所有 `jsx`、`js`、`wxml`、`wxss` 中出现的 `tailwindcss` 运行时工具类进行转化，如果不需要转化可以使用 `weappTwIgnore` 标识符来进行忽略:

例如:

```js
<view :class="classArray">classArray</view>

// weappTwIgnore 就是 String.raw ，所以它的结果就是后面字符串的结果
const weappTwIgnore = String.raw
const classArray = [
  'text-[30rpx]',
  weappTwIgnore`bg-[#00ff00]`
]

```

此时只有 `'text-[30rpx]'` 会被转化，`'bg-[#00ff00]'` 会被忽略。

> 默认情况下仅会忽略与 `weappTwIgnore` 有直接关系的标记模板，例如从包里导入后重命名、或在同一文件里一路别名过去的写法。简单的 `String.raw` 别名会继续参加转译，防止误杀。

如果需要自定义别名，可以包装一层函数并在配置里显式加入该别名，例如：

```js
const alias = (...args) => String.raw(...args)
// 在 ignoreTaggedTemplateExpressionIdentifiers 中加入 'alias'
```

或者直接使用 `ignoreTaggedTemplateExpressionIdentifiers` 配置追加其它标识符。

---

## weapp-tailwindcss 导出总览


> 本文根据 `packages/weapp-tailwindcss/package.json` 的 `exports` 字段整理，帮助你在不同框架/构建场景中快速定位合适的入口文件。

weapp-tailwindcss 同时提供 ESM 与 CommonJS 入口，并内置多个二级导出以适配 webpack、Vite、Gulp、Tailwind 宏等不同组合。下面按用途分类进行说明。

## 核心插件入口

| 导出路径 | 说明 | 典型用法 |
| --- | --- | --- |
| `weapp-tailwindcss` | 聚合入口：`createPlugins`、`UnifiedWebpackPluginV5`、`UnifiedViteWeappTailwindcssPlugin` 等常用工厂齐备 | `import { UnifiedWebpackPluginV5 } from 'weapp-tailwindcss'`
| `weapp-tailwindcss/webpack` | webpack@5 适配入口（uni-app CLI、mpx、原生小程序等） | `const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')`
| `weapp-tailwindcss/webpack4` | webpack@4 适配入口（旧版 Taro/uni-app 项目） | `import { UnifiedWebpackPluginV4 } from 'weapp-tailwindcss/webpack4'`
| `weapp-tailwindcss/vite` | Vite 插件入口（Taro Vite、weapp-vite 等） | `import { UnifiedViteWeappTailwindcssPlugin } from 'weapp-tailwindcss/vite'`
| `weapp-tailwindcss/core` | 暴露 `createContext` 等底层 API，可自定义 transform 流程 | `import { createContext } from 'weapp-tailwindcss/core'`

## 配置、工具与周边

| 导出路径 | 说明 | 场景 |
| --- | --- | --- |
| `weapp-tailwindcss/defaults` | 默认插件配置、补丁行为等常量 | 查看/复用默认选项
| `weapp-tailwindcss/presets` | 官方预设集合（差异化策略、Tailwind 配置等） | 扩展或组合默认行为
| [`weapp-tailwindcss/reset`](./reset) | 内置默认 `button` reset，可通过 `buttonReset` 选项禁用或改写选择器 | `@plugin 'weapp-tailwindcss/reset';`
| `weapp-tailwindcss/types` | TypeScript 类型定义便捷入口 | `import type { UserDefinedOptions } from 'weapp-tailwindcss/types'`
| `weapp-tailwindcss/escape` | `replaceWxml`、`isAllowedClassName` 等字符串处理工具 | 单独处理模板/字符串时复用
| `weapp-tailwindcss/postcss-html-transform` | 针对 HTML/WXML 的 PostCSS 转换器 | 自定义 PostCSS 流程
| `weapp-tailwindcss/css-macro` | Tailwind CSS 宏工具（JS/TS） | 在代码中动态生成原子类
| `weapp-tailwindcss/css-macro/postcss` | 宏工具的 PostCSS 版本 | 构建期宏替换
| `weapp-tailwindcss/gulp` | Gulp 插件入口 | 传统 Gulp 构建链集成
| `weapp-tailwindcss/package.json` | 包元数据 | 读取版本号等信息

## 样式资源

| 导出路径 | 说明 | 引用示例 |
| --- | --- | --- |
| `weapp-tailwindcss/index.css` (`weapp-tailwindcss/index`) | 默认 runtime 样式（==推荐直接引用==） | `@import 'weapp-tailwindcss/index.css';`
| `weapp-tailwindcss/preflight.css` (`weapp-tailwindcss/preflight`) | 小程序专用 Preflight | `@import 'weapp-tailwindcss/preflight.css';`
| `weapp-tailwindcss/theme.css` (`weapp-tailwindcss/theme`) | 主题变量定义 | `@import 'weapp-tailwindcss/theme.css';`
| `weapp-tailwindcss/utilities.css` (`weapp-tailwindcss/utilities`) | 原子类集合 | `@import 'weapp-tailwindcss/utilities.css';`
| `weapp-tailwindcss/with-layer.css` (`weapp-tailwindcss/with-layer`) | layer 版样式，适配 Tailwind v4 layer 写法 | `@import 'weapp-tailwindcss/with-layer.css';`
| `weapp-tailwindcss/uni-app-x.css` (`weapp-tailwindcss/uni-app-x`) | uni-app x 定制样式 | `@import 'weapp-tailwindcss/uni-app-x.css';`
| `weapp-tailwindcss/css` | 指向 `css/index.css`，兼容旧目录结构 | `@import 'weapp-tailwindcss/css';`

> ⚠️ 注意：部分构建工具（例如 `postcss-import`、mpx CLI）在解析 `@import 'weapp-tailwindcss'` 时可能回退到 JS 入口（`dist/index.js`），并抛出 “Unknown word "use strict"”。请显式写出 `index.css`，或在本地创建中转 `app.css` 后再导入。

## 其他导出

- `weapp-tailwindcss/*`：保留通配符路径，兼容历史文件结构；建议优先使用上表列出的稳定入口。
- 所有 JS 模块同时提供 `import` 与 `require` 两种格式，TS 项目结合 `types` 入口即可获得完整声明。

想进一步了解各模块暴露的 API，可以查阅 [`weapp-tailwindcss` API 总览](../api/index.md) 或直接阅读对应类型定义与源码。

---

## Index

id: options/index
slug: /options
sidebar_position: 0
title: 选项概览
description: weapp-tailwindcss 可用配置概览

该章节的详细配置已经迁移至 [API / 配置项文档](/docs/api/interfaces/UserDefinedOptions)。

- [允许的类名写法](/docs/options/arbitrary-values)
- [注释用法与忽略开关](/docs/options/comments)

如果你在升级过程中需要参考原先的配置写法，请参见上方链接。

---

## `weapp-tailwindcss/reset`


`weapp-tailwindcss/reset` 内置了一组常用组件的 reset 规则，默认会：

- 清除所有 `button` 的原生样式（padding / 颜色 / border 等），让它的表现和 `view` / `text` 一致；
- 将 `<image>` / `` 统一为 `display: block`，并限制为 `max-width: 100%`、`height: auto`。

你可以通过选项控制是否注入这些规则、改写选择器 / 声明，甚至追加自定义 reset。

> ℹ️ 当你传入 `.class` / `#id` 作为选择器时，插件会自动转换为 `[class~="class"]` / `[id="id"]`，确保它们仍属于 base layer，不会破坏其他层级。

## 可用选项

- `buttonReset?: false | ResetConfig`
- `imageReset?: false | ResetConfig`
- `extraResets?: ResetConfig[]`

```ts
interface ResetConfig {
  selectors?: string[]        // 支持元素 / 类名 / ID
  declarations?: Record<string, string | number | false>
  pseudo?: Record<string, string | number | false> // 注入到 ::after
}
```

设置为 `false` 即可关闭对应默认 reset；当提供类名 / ID 时会自动转换为 `[class~="foo"]` / `[id="bar"]`。

## Tailwind CSS v3 用法

```ts title="tailwind.config.ts"

export default {
  plugins: [
    // 默认注入 button/image reset
    reset(),

    // 完全自定义
    reset({
      buttonReset: {
        selectors: ['.wx-reset-btn', '#primary-btn'],
        declarations: {
          padding: '0',
          backgroundColor: 'transparent',
        },
        pseudo: {
          border: 'none',
        },
      },
      imageReset: {
        selectors: ['.wx-reset-image'],
        declarations: {
          display: 'inline-block',
          borderWidth: '0',
        },
      },
      extraResets: [
        {
          selectors: ['.wx-reset-view'],
          declarations: {
            display: 'block',
            borderWidth: '0',
          },
          pseudo: {
            borderColor: 'transparent',
          },
        },
      ],
    }),
  ],
}
```

关闭默认 reset：

```ts
reset({
  buttonReset: false,
  imageReset: false,
})
```

## Tailwind CSS v4 用法

在入口 CSS 中通过 `@plugin` 注册即可：

```css title="app.css"
@plugin 'weapp-tailwindcss/reset';

@plugin 'weapp-tailwindcss/reset' ({
  buttonReset: false,
  imageReset: {
    selectors: ['.wx-reset-image'],
    declarations: {
      display: 'inline-block',
    },
  },
  extraResets: [
    {
      selectors: ['.list-reset'],
      declarations: { listStyle: 'none', margin: '0', padding: '0' },
    },
  ],
});

@import 'tailwindcss/utilities';
```

同样可以通过 `buttonReset: false` / `imageReset: false` 精准控制需要的 reset。`extraResets` 允许你一次性追加多个自定义规则。***

---

## 从 v1 迁移到 v2


在 `2.x` 版本中，可以把之前使用的 `webpack` 插件，全部更换为 `UnifiedWebpackPluginV5` 插件，不过 `vite` 插件的导出有一些小变化:

`1.x`:

```js

```

`2.x`:

```js
// UnifiedViteWeappTailwindcssPlugin 就是新的插件

```

另外新的 `UnifiedWebpackPluginV5` 可以直接从 `weapp-tailwindcss-webpack-plugin` 引入，同时在新的 `UnifiedWebpackPluginV5` 中，之前所有的配置项都被继承了过来，只需要用它直接替换原先插件即可。

另外不要忘记把:

```json
 "scripts": {
+  "postinstall": "weapp-tw patch"
 }
```

添加进你的 `package.json` 里，然后清除原先的打包缓存之后重新打包运行。

---

## 从 v2 迁移到 v3


v3 版本相比于 v2, 主要是删去一些过时的功能，配置项，同时会改变插件的默认值，使得整体插件变得更易用，更容易安装
假如你没有用到什么复杂自定义配置，那么完全可以平滑升级上来。

## 配置项改动

### 删除的配置项

- 删去 `replaceUniversalSelectorWith` 选项，使用 `cssSelectorReplacement.universal` 来代替，后者参数覆盖前者
- 删去 `minifiedJs` 选项，现在完全遵从用户的配置，用户压缩就压缩，反之亦然
- 删去 `jsEscapeStrategy` 选项，现在默认只有一种模式 `replace`/ 不再提供 `regenerate` 模式
- 删去 `customReplaceDictionary` 的 `complex` 模式，只内置 `simple` 模式 (你如果还要 `complex` 模式 ,可以从 `@weapp-core/escape` 引入，再传入 `customReplaceDictionary` 配置项即可)
- `cssMatcher`/`htmlMatcher`/`jsMatcher`/ `mainCssChunkMatcher` / `wxsMatcher` 不再能够传入 `glob` 表达式(例如`**/*.html`)，现在都是传入一个方法: `(name: string) => boolean`。要兼容原先的 `glob` 表达式，你可以通过 `minimatch` 把 `glob` 表达式转化成正则来兼容原先的配置
- `cssPreflightRange` 只存在一种模式，为 `all`, 之前的 `view` 选项交给 `cssSelectorReplacement.universal` 进行托管

### 增加的配置项

- `rem2rpx` : 类型 `rem2rpx?: boolean | rem2rpxOptions`

rem 转 rpx 配置，默认 **不开启**，可传入配置项，配置项见 <https://www.npmjs.com/package/postcss-rem-to-responsive-pixel>
这个配置项代表插件内置了 `postcss-rem-to-responsive-pixel` ，不过默认不开启，传入一个 `true` 相当于传入配置:

```js
{
  // 32 意味着 1rem = 32rpx
  rootValue: 32,
  // 默认所有属性都转化
  propList: ['*'],
  // 转化的单位,可以变成 px / rpx
  transformUnit: 'rpx',
}
```

当然你也可以传入 `rem2rpxOptions` 这样一个 `object` 进行自定义

#### 为什么默认不开启？

1. 为了从 `2.x` 版本可以平滑的过渡到 `3.x`
2. 从我的视角看，内置 `postcss` 插件功能，虽然整体集成度上更高了，但是对其他开发者可能不是那么自由，比如在 `2.x` 时候，由于 `postcss-rem-to-responsive-pixel` 是外置的，所以开发者可以自由的决定它的加载顺序和加载逻辑，但是内置之后都是我决定的。不过内置好处也有，就是开箱即用

### 增强的配置项

- `cssChildCombinatorReplaceValue`, `cssSelectorReplacement.root`,`cssSelectorReplacement.universal` 现在都可以接受字符串数组了，它们可以自动展开，防止选择器格式化错误问题

### 修改的默认值

- `cssPreflightRange` 从 `'view'` 变为 `undefined`, 现在 `all` 的作用变成了在 `tailwindcss` 变量注入区域的选择器，添加一个 `:not(not)` 的选择器作为全局选择器的替代
- `cssSelectorReplacement.universal` 从 `'view'` 变为 `['view', 'text']`, 这意味着 `*` 选择器会被展开成 `view,text` 以及对应方式
- `cssChildCombinatorReplaceValue` 从 `'view + view'` 变为 `['view']`
- `replaceUniversalSelectorWith`,`jsEscapeStrategy`,`minifiedJs` 选项被删除，所以不再保留默认值

### 现在选项合并，数组默认行为变为覆盖，原先是合并

```js
const options = getOptions(input,defaults)
defaults: ['a','b'], input:['c']
// before:
options == ['a','b','c']
// after:
options == ['c']
```

<https://github.com/sonofmagic/weapp-tailwindcss/issues/259>

---

## 从 v3 迁移到 v4


<!-- :::warning -->
<!-- 由于 `tailwindcss@4` 改动较大，直接变成了一个样式预处理器，和 `sass` / `less` 类似。

目前 `weapp-tailwindcss@4` 版本并没有较好地兼容 `tailwindcss@4`,  -->

<!-- 请继续以 `weapp-tailwindcss@4` + `tailwindcss@3` 的方式使用

等待 `weapp-tailwindcss` 正式兼容改造的文档发布 (2025-02-12)
::: -->

`tailwindcss@4` 改动较大，直接变成了一个样式预处理器，和 `sass` / `less` 类似，所以你不应该让 `tailwindcss@4` 和 `sass`, `less` 一起使用。

所以关于这方面的改动会比较多, 可能你需要把很多 `.scss`,`.less` 文件后缀改成 `.css`

`v4` 版本相比于 `v3`, 影响功能的重大变动较少，假如你没有用到什么复杂自定义配置，那么完全可以平滑升级上来。

## 重大变更

1. 移除 `jsAstTool` 的 `ast-grep` 支持，现在全部使用 `babel` 进行 `ast` 处理，假如你使用了这个配置，你可以保持不动，或者你可以把它删掉。

## 特性更新

1. 添加 `@weapp-tailwindcss/merge` 包作为小程序版本的 `tailwind-merge`
1. 增加 `ignoreTaggedTemplateExpressionIdentifiers` 和 `ignoreCallExpressionIdentifiers` 配置，用于和 `@weapp-tailwindcss/merge` 结合起来使用
1. 在安装 `@weapp-tailwindcss/merge` 时自动设置 `ignoreCallExpressionIdentifiers` 为 `['twMerge', 'twJoin', 'cva']` 默认不进行转义里面的字面量
1. 更改 `cssChildCombinatorReplaceValue` 默认值从 `['view']` -> `['view', 'text']` 为了更好的小程序开发体验

## 重构

1. 移除 `@babel/generator` 依赖
2. 去除 `weapp-tailwindcss/postcss` 导出，代替可直接安装使用 `@weapp-tailwindcss/postcss`
3. 增加 `weapp-tailwindcss/escape` 来取代 `weapp-tailwindcss/replace`, `weapp-tailwindcss/replace` 导出被移除
4. 项目 `monorepo` 区分包
5. 项目打包方式从 `rollup` 变为 `tsup`

## pnpm@10.x

假如你已经升级到了 `pnpm@10.x`，安装依赖后需要执行 `pnpm approve-builds weapp-tailwindcss` 将其加入 `onlyBuiltDependencies`，以便 `postinstall` 等 `npm hook` 能正常运行

---

## css 中使用 @apply 警告问题


## 解决方案

我们以 `vscode` 为例

1. 创建 `.vscode` 目录

然后在目录下创建 `settings.json` 和 `tailwind.json`

2. 修改 `settings.json` 添加

```jsn
{
  "css.customData": [".vscode/tailwind.json"]
}
```

3. 修改 `tailwind.json`

````json
{
  "version": 1.1,
  "atDirectives": [
    {
      "name": "@tailwind",
      "description": "Use the `@tailwind` directive to insert Tailwind's `base`, `components`, `utilities` and `screens` styles into your CSS.",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#tailwind"
        }
      ]
    },
    {
      "name": "@apply",
      "description": "Use the `@apply` directive to inline any existing utility classes into your own custom CSS. This is useful when you find a common utility pattern in your HTML that you’d like to extract to a new component.",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#apply"
        }
      ]
    },
    {
      "name": "@responsive",
      "description": "You can generate responsive variants of your own classes by wrapping their definitions in the `@responsive` directive:\n```css\n@responsive {\n  .alert {\n    background-color: #E53E3E;\n  }\n}\n```\n",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#responsive"
        }
      ]
    },
    {
      "name": "@screen",
      "description": "The `@screen` directive allows you to create media queries that reference your breakpoints by **name** instead of duplicating their values in your own CSS:\n```css\n@screen sm {\n  /* ... */\n}\n```\n…gets transformed into this:\n```css\n@media (min-width: 640px) {\n  /* ... */\n}\n```\n",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#screen"
        }
      ]
    },
    {
      "name": "@variants",
      "description": "Generate `hover`, `focus`, `active` and other **variants** of your own utilities by wrapping their definitions in the `@variants` directive:\n```css\n@variants hover, focus {\n   .btn-brand {\n    background-color: #3182CE;\n  }\n}\n```\n",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#variants"
        }
      ]
    }
  ]
}
````

这样 `@apply` 就不会报错了。

## 参考文档

https://github.com/tailwindlabs/tailwindcss/discussions/5258

---

## 默认盒模型(box-sizing)问题


`Tailwindcss` 默认会把所有的元素的盒模型，设置为 `border-box`

但是一些组件库，比如 `wot-design-uni`，实现使用的是 `content-box` ，一切换到 `border-box` 高度塌陷了， 所以会导致部分显示效果错乱。

> `box-sizing: border-box;` 这行样式是在 'tailwindcss/base' 中的，所以你禁用这行代码，感觉上生效了，但是这样不是很好的解决方案。

假如你要从插件层面解决问题，只要做出如下修改:

```js
uvtw({
  // 添加这一行配置即可
  cssPreflight: {
    'box-sizing': false,
  },
}),
```

这样就可以把 `box-sizing` 这个样式给去掉，但是你这样就要去评估原先那些依赖盒模型的样式是否会受到影响：

比如 `w-2`, `h-4` 都是盒子模型潜在的影响。

## 参考文档

https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#csspreflight

https://github.com/sonofmagic/weapp-tailwindcss/issues/604

---

## CSS 变量失效问题


## 问题的现象

在使用 `taro` 或者 `uni-app` 中，可能你会遇到 `CSS` 变量失效问题

具体表现，就是你在使用下列类名的时候，小程序的模拟器上，不会出来任何的背景颜色:

```jsx
<View className='h-14 bg-gradient-to-r from-cyan-500 to-blue-500'></View>
<View className='h-14 bg-gradient-to-r from-sky-500 to-indigo-500'></View>
<View className='h-14 bg-gradient-to-r from-violet-500 to-fuchsia-500'></View>
<View className='h-14 bg-gradient-to-r from-purple-500 to-pink-500'></View>
```

## 原因以及解决方案

导致这个的原因，是由于全局的 `tailwindcss` 变量丢失，没有注入进 `App` 引起的。参阅[什么是 `tailwindcss` 全局变量注入区域](#什么是全局-tailwindcss-变量注入区域)。

例如在 `taro` 中和 `@tarojs/plugin-html` 一起使用，就会出现这个问题，这是因为 `@tarojs/plugin-html` 把 `tailwindcss` 变量区域直接删除了。

遇到这样的问题，解决方案也很简单，只需要给插件传入 `injectAdditionalCssVarScope: true` 参数即可。

代码片段和配置详情详见[和 NutUI 一起使用](./use-with-nutui)。

## 设置成功后的效果

设置成功之后的效果如下所示，可以观察一下左侧的效果，和右下角的 `inspect` 面板作为参考

![小程序生效图片](./css-vars.jpg)

## 什么是全局 `tailwindcss` 变量注入区域

在你的 `app.wxss` 样式产物文件中（例如：`taro` 或 `uni-app` 的 `dist` 文件夹内），都有这样一块区域。

上面的这个问题，就是这块变量注入区域没了导致的。

```css
::before,::after {
  --tw-content: "";
}
view,text,::before,::after {
  --tw-border-spacing-x: 0;
  --tw-border-spacing-y: 0;
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-rotate: 0;
  --tw-skew-x: 0;
  --tw-skew-y: 0;
  --tw-scale-x: 1;
  --tw-scale-y: 1;
  --tw-pan-x:  ;
  --tw-pan-y:  ;
  --tw-pinch-zoom:  ;
  --tw-scroll-snap-strictness: proximity;
  --tw-gradient-from-position:  ;
  --tw-gradient-via-position:  ;
  --tw-gradient-to-position:  ;
  --tw-ordinal:  ;
  --tw-slashed-zero:  ;
  --tw-numeric-figure:  ;
  --tw-numeric-spacing:  ;
  --tw-numeric-fraction:  ;
  --tw-ring-inset:  ;
  --tw-ring-offset-width: 0px;
  --tw-ring-offset-color: #fff;
  --tw-ring-color: rgb(59 130 246 / 0.5);
  --tw-ring-offset-shadow: 0 0 #0000;
  --tw-ring-shadow: 0 0 #0000;
  --tw-shadow: 0 0 #0000;
  --tw-shadow-colored: 0 0 #0000;
  --tw-blur:  ;
  --tw-brightness:  ;
  --tw-contrast:  ;
  --tw-grayscale:  ;
  --tw-hue-rotate:  ;
  --tw-invert:  ;
  --tw-saturate:  ;
  --tw-sepia:  ;
  --tw-drop-shadow:  ;
  --tw-backdrop-blur:  ;
  --tw-backdrop-brightness:  ;
  --tw-backdrop-contrast:  ;
  --tw-backdrop-grayscale:  ;
  --tw-backdrop-hue-rotate:  ;
  --tw-backdrop-invert:  ;
  --tw-backdrop-opacity:  ;
  --tw-backdrop-saturate:  ;
  --tw-backdrop-sepia:  ;
  box-sizing: border-box;
  border-width: 0;
  border-style: solid;
  border-color: currentColor;
}
::backdrop {
  --tw-border-spacing-x: 0;
  --tw-border-spacing-y: 0;
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-rotate: 0;
  --tw-skew-x: 0;
  --tw-skew-y: 0;
  --tw-scale-x: 1;
  --tw-scale-y: 1;
  --tw-pan-x:  ;
  --tw-pan-y:  ;
  --tw-pinch-zoom:  ;
  --tw-scroll-snap-strictness: proximity;
  --tw-gradient-from-position:  ;
  --tw-gradient-via-position:  ;
  --tw-gradient-to-position:  ;
  --tw-ordinal:  ;
  --tw-slashed-zero:  ;
  --tw-numeric-figure:  ;
  --tw-numeric-spacing:  ;
  --tw-numeric-fraction:  ;
  --tw-ring-inset:  ;
  --tw-ring-offset-width: 0px;
  --tw-ring-offset-color: #fff;
  --tw-ring-color: rgb(59 130 246 / 0.5);
  --tw-ring-offset-shadow: 0 0 #0000;
  --tw-ring-shadow: 0 0 #0000;
  --tw-shadow: 0 0 #0000;
  --tw-shadow-colored: 0 0 #0000;
  --tw-blur:  ;
  --tw-brightness:  ;
  --tw-contrast:  ;
  --tw-grayscale:  ;
  --tw-hue-rotate:  ;
  --tw-invert:  ;
  --tw-saturate:  ;
  --tw-sepia:  ;
  --tw-drop-shadow:  ;
  --tw-backdrop-blur:  ;
  --tw-backdrop-brightness:  ;
  --tw-backdrop-contrast:  ;
  --tw-backdrop-grayscale:  ;
  --tw-backdrop-hue-rotate:  ;
  --tw-backdrop-invert:  ;
  --tw-backdrop-opacity:  ;
  --tw-backdrop-saturate:  ;
  --tw-backdrop-sepia:  ;
}
```

这块区域就是你 `@tailwind base;` 展开后, `tailwindcss` 注入的全局变量块。

丢失这块区域会导致 `bg-gradient-to-r` 这种依赖 `css` 变量的原子类失效。

---

## 组件外部样式类（externalClasses）的支持

:::warning 快速结论
如果在自定义组件里写了 `my-class="bg-[#fafa00] text-[40px]"`，但调试器里看到变成了 `my-class="bg- #fafa00  text- 40px"` 并导致样式失效，请在插件配置中为 `customAttributes` 显式声明 `my-class`。
:::

## 典型现象

在封装原生自定义组件时经常会用到外部样式类（`externalClasses`）。例如：

```js
/* custom-component.js */
Component({
  externalClasses: ['my-class'],
})
```

在页面里直接使用 `tailwindcss` 工具类：

```html
<custom-component my-class="bg-[#fafa00] text-[40px]" />
```

小程序开发者工具会把 `my-class` 中的样式拆开成 `bg- #fafa00  text- 40px`，最终导致样式全部失效。

## 根本原因

插件默认只会转译 `class` 和 `hover-class`。外部样式类属于自定义属性，如果没有配置 [`customAttributes`](/docs/api/interfaces/UserDefinedOptions#customattributes)，就不会被识别处理。

## 解决方案

在插件选项里增加自定义属性的映射即可：

```js
customAttributes: {
  '*': ['my-class'],
}
```

- `*` 代表匹配所有标签，你也可以改成具体的标签名或正则表达式。
- 支持传入 `Object` 或 `Map`，用于灵活地映射标签与属性的关系。

:::tip 多个外部样式类
如果组件同时暴露 `['my-class', 'title-class']`，直接把它们都写进同一个数组即可。
:::

## 扩展阅读

- 微信官方文档：[外部样式类](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#外部样式类)
- 插件配置项说明：[customAttributes](/docs/api/interfaces/UserDefinedOptions#customattributes)

> 使用正则进行自定义匹配标签时，需要传入一个 `Map`，其中正则作为 `key`，数组作为 `value`。

---

## Tailwindcss 格式化


## prettier 插件

> 这是官方提供的包，

使用并在 `prettier` 注册 [`prettier-plugin-tailwindcss`](https://www.npmjs.com/package/prettier-plugin-tailwindcss)

## eslint 插件

使用并在 `eslint` 注册 [`eslint-plugin-tailwindcss`](https://www.npmjs.com/package/eslint-plugin-tailwindcss)

---

## group 和 peer 使用限制


## group 使用注意事项

在 `tailwindcss` 中，我们常常会这样写:

```html

  <view class="bg-pink-400 group-hover:bg-yellow-400">
    group tapped
  </view>

```

这样在最外层的 `div` 进入 `hover` 状态时，内部的子元素中的 `group-hover` 就会生效，从而改变样式。

然而，在小程序中，伪类 `:hover` 是不起作用的，取而代之的是 `hover-class` 这样一个属性，所以这种情况我们可以这么写：

```html
<view class="group" hover-class="tapped">
  <view class="bg-pink-400 group-[.tapped]:bg-yellow-400">
    group tapped
  </view>
</view>
```

这样在 `group` 进入 `hover` 状态时，`bg-yellow-400` 就会生效了。

相关 issue：[#14](https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template/issues/14)

## peer 使用注意事项

我们一般使用 `peer` 来标记一个元素，再使用各种 `peer-*` 来让它后续兄弟节点的样式生效。这些主要生成大量包含 `~` [后续兄弟选择器](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Subsequent-sibling_combinator) 的 `css` 代码。

然而很不幸，在小程序中 `~` 这个选择器非常容易报错，它前面只能跟 `class` 选择器，不能跟伪类，不然会报错:

```scss
// 报错
// .xxx:invalid~.xxx-invalid:visible {
//   visibility: visible;
// }
// 不报错
.xxx~.xxx-invalid:visible {
  visibility: visible;
}
```

所以你要么就不使用 `peer` 特性，如果需要此特性请使用内嵌 `class` 的方式来使用:

```html
<view>
  <view class="w-20 h-20 peer bg-gray-300" hover-class="tapped" />
  <view class="w-20 h-20 peer-[.tapped]:bg-red-400 bg-blue-400"></view>
</view>
```

> 前一个方块按压后进入 `hover` 状态 ，后面那个就变成红色。

## 出现 unexpected token "~" 错误

出现这个错误后，你应该把对应报错的相关 `peer`、`peer-*` 删掉，注意是删掉，请不要注释，因为 `tailwindcss` 中也会从注释中提取字符串，所以注释掉是没有效果的。

删掉之后，你需要重新启动一下你的应用（例如 `yarn dev:weapp`），不然导致错误的 `css` 还是会存在，导致项目崩溃。

---

## 常见问题


:::info 组件外部样式类必读
自定义组件使用 `externalClasses` 时样式被拆分？请先查看《[组件外部样式类（externalClasses）的支持](/docs/issues/externalClasses)》，按照文档里的 `customAttributes` 配置即可解决。
:::

## 为什么我更改了 class 保存重新打包的时候热更新失效？

[[#93](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/93)]

目前微信开发者工具会默认开启代码自动热重载 `compileHotReLoad` 功能，这个功能在原生开发中表现良好，但在 `uni-app` 和 `taro` 等的框架中，存在一定的问题，参见 [issues#37](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/37)，所以如果你遇到了此类问题，建议关闭 `compileHotReLoad` 功能。

## `disabled:opacity-50` 这类的 `tailwindcss` 工具类不生效?

这是由于微信小程序 `wxss` 选择器的原生限制，无法突破。参见 [issue#33](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/33)。

## `background-image` 为什么不能使用本地路径？

微信小程序在 `wxss` 中禁止 `background-image` 引用本地文件，解析时会直接报 `do-not-use-local-path` 错误。因此像 <code>bg-&#91;url('/images/homebg.png')&#93;</code> 这样的写法无法生效。请改用以下任一方式：

- 使用线上可访问的远程图片地址，例如 `bg-[url('https://example.com/bg.png')]`
- 将资源转成 `base64` 后内联到 `background-image`
- 改用 `<image>` 组件渲染背景效果

选择合适方案后再通过 `tailwindcss` 编写样式，即可避免编译报错。

## 和原生组件一起使用注意事项

假如出现原生组件引入报错的情况，可以参阅 [issue#35](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/35)，忽略指定目录下的文件，跳过插件处理，例如 `uni-app` 中的 `wxcomponents`。

如何更改？在传入的配置项 `cssMatcher`，`htmlMatcher` 这类配置，来过滤指定目录或文件。

## 编译到 h5 / app 注意事项

有些用户通过 `uni-app` 等跨端框架，不止开发成各种小程序，也开发为 `H5`，然而 `tailwindcss` 本身就兼容 `H5` 了。此时你需要更改配置，我们以 `uni-app` 为例:

```js
const isH5 = process.env.UNI_PLATFORM === "h5";
// vue3 版本构建到 app, UNI_PLATFORM 的值为 app
// vue2 版本为 app-plus
const isApp = process.env.UNI_PLATFORM === "app-plus";
const WeappTailwindcssDisabled = isH5 || isApp;

// 然后在 h5 和 app 环境下把 webpack plugin 和 postcss for weapp 给禁用掉
// 我们以 uni-app-vue3-vite 这个 demo为例
// vite.config.ts

// vite 插件配置
const vitePlugins = [uni(),uvtw({
  disabled: WeappTailwindcssDisabled
})];

export default defineConfig({
  plugins: vitePlugins
});

// 同理 postcss 配置
// 假如不起作用，请使用内联postcss
const plugins = [require('autoprefixer')(), require('tailwindcss')()];

if (!WeappTailwindcssDisabled) {
  plugins.push(
    require('postcss-rem-to-responsive-pixel')({
      rootValue: 32,
      propList: ['*'],
      transformUnit: 'rpx'
    })
  );
}

module.exports = {
  plugins
};
```

## 报错 TypeError: Cannot use 'in' operator to search for 'CallExpression' in undefined

遇到这个问题是由于 `babel` 相关的包之间的版本产生了冲突导致的，这种时候可以删除掉 `lock` 文件（`yarn.lock`、`pnpm-lock.yaml`、`package-lock.json`），然后重新安装即可。

## taro webpack5 环境下，这个插件和外置额外安装的 `terser-webpack-plugin` 一起使用，会导致插件转义功能失效

相关 issue：[#142](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/142)

例如：`.h-4/6`、`!w-full` 正常会转义为`.h-4s6`、`.iw-full`，本插件失效后小程序开发者工具报编译错误 `.h-4\/6`、`.\!w-full`。

请压缩代码并不要使用[链接](https://docs.taro.zone/docs/config-detail/#terserenable)中的方法，太老旧了。

使用 `taro` 配置项里的的 `terser` 配置项，参见 [`terser` 配置项](https://docs.taro.zone/docs/config-detail#terser)。

> `terser` 配置只在生产模式下生效。如果你正在使用 `watch` 模式，又希望启用 `terser`，那么则需要设置 `process.env.NODE_ENV` 为 `production`。

也就是说，直接在开发 `watch` 模式的时候，设置环境变量 `NODE_ENV` 为 `production` 就行。

另外也可以不利用 `webpack` 插件压缩代码，去使用微信开发者工具内部的压缩代码选项。

## 为什么 space-y-1 这类写法不起作用?

相关 issue：[#108](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/108)

考虑到小程序的组件 `shadow root` 实现方式，默认情况下 `space` 这一类带有子选择器的，只对 `view` 元素生效。

即选择器变成了 `.space-y-1 > view + view`

这时候解决方案有 3 种：

- 组件外层套一层 `<view>` 元素。
- `virtualHost` 解决方案，在自定义组件中添加 `options: { virtualHost: true }` 即可解决此问题。
- [`cssChildCombinatorReplaceValue`](/docs/api/interfaces/UserDefinedOptions#csschildcombinatorreplacevalue) 配置项

## 使用 uni-app vite vue 注册插件时，发行到 h5 环境出现: [plugin:vite-plugin-uni-app-weapp-tailwindcss-adaptor] 'import' and 'export' may appear only with 'sourceType: "module"' (1:0) 错误

解决方案：

```js
// 注意：打包成 h5 和 app 都不需要开启插件配置
const isH5 = process.env.UNI_PLATFORM === "h5";
// vue3 版本构建到 app, UNI_PLATFORM 的值为 app
// vue2 版本为 app-plus
const isApp = process.env.UNI_PLATFORM === "app-plus";
const WeappTailwindcssDisabled = isH5 || isApp;
const vitePlugins = [uni(), uvwt({
  disabled: WeappTailwindcssDisabled
})];
```

即 `h5` 环境和 `app` 环境都不开启我这个插件，因为本来这 2 个环境就是 `tailwindcss` 支持的环境，没必要开启插件转义。

## 使用 pnpm@8 插件注册失败问题

pnpm 8 这个版本改变了一些默认值，其中 `resolution-mode` 默认值变成了 `lowest-direct`。

这会导致所有的依赖，会被安装成你在 `package.json` 里注册的最低版本，这可能会造成一些问题。如何解决？

目录下创建一个 `.npmrc`，设置 `resolution-mode` 为 `highest`，然后重新安装，

或者，使用 `pnpm up -Li` 升级一下你 `package.json` 里的依赖包版本到最新即可。

## uni-app 在从v1升级到v2的过程中，如果使用了云函数相关功能，编译到小程序会出现问题

解决方案参见：<https://ask.dcloud.net.cn/question/170057>

相关 issue：[#74](https://github.com/sonofmagic/weapp-tailwindcss/issues/74#issuecomment-1573033475)

## uni-app vue2 中的 css 使用 @import 引入其他 css，导致在 `rpx` 在H5下不生效

需要添加并配置 `postcss-import`，参见 [issues/75](https://github.com/sonofmagic/weapp-tailwindcss/issues/75#issuecomment-1574592907)。

你可以查看源码中 `demo/uni-app` 相关的示例来进行配置。

## 为什么使用 taro 写 jsx，js 时候，转义不生效？

这是因为 [patch](/docs/quick-start/this-plugin) 方法没有生效，这个指令是用来在运行时暴露 `tailwindcss` 上下文的，只有暴露成功，我们写的 `js` 里的样式，才会变精准转义，否则就会出现在 `jsx` 里写 `className` 不生效的情况。

## monorepo 项目中 arbitrary values 写法无效？

这可能是由于 tailwindcss 包被提升，导致项目获取不到正确的 tailwind 上下文，有两种解决方案。

- 配置 [tailwindcssBasedir](https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#tailwindcssbasedir)

- 禁止 `tailwindcss` 包被提升，具体配置方法可以去查阅各包管理器的说明文档

---

## 写在 js 中的 tailwindcss 任意值失效


`weapp-tailwindcss` 是允许你在 `js` 中编写任意值的，而且 `weapp-tailwindcss` 会自动帮你做好任意值的转译。

比如:

```js title="src/pages/index/index.js"
const xs = {
  wrapper: 'px-[4px] h-[40px]',
}
```

那么在最终的产物中，编译结果会自动变为

```js title="dist/pages/index/index.js"
const xs = {
  wrapper: 'px-_4px_ h-_40px_',
}
```

但是你这个文件，必须被 `tailwindcss` 感知到，并从里面提取到这 `2` 个 `class`。`weapp-tailwindcss` 才能通过和 `tailwindcss` 的通信，来完成这 `2` 个 `class` 的转译。

所以你这个源文件必须在 `tailwindcss@3` 中的 `tailwind.config.js` 中被 `content` 配置包括。或者 `tailwindcss@4` 被 `@source` 包括到，那这个自动转译的流程才能走完。

否则就会出现 `js` 转译没有进行, 导致开发者工具中审查元素时，出现:

```html
<view class="px- 4px  h- 40px "></view>
```

这种类名被切断的情况。

## 解决方案

### tailwindcss@3

检查你的 `tailwind.config.js` 中的 `content`，确认你出现类名被切断的源文件，被 `content` 包括。

文档地址: https://v3.tailwindcss.com/docs/configuration#content

### tailwindcss@4

检查你的 `@source`，确认你出现类名被切断的源文件，被 `@source` 包括。

文档地址: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources

<!-- 因为 `tailwindcss` 和 `weapp-tailwindcss` 的转化规则 ，是根据你的源代码里提取出来的 `token` 决定的 -->

---

## 在 monorepo 中使用


在 `monorepo` 由于存在 `hoist` 机制，可能会导致 `weapp-tailwindcss` 和 `tailwindcss` 通信受阻，这时候需要显式的去指定 `tailwindcss` 的路径

这里我们以 `taro@4` 的配置 `config/index.ts` 配置为例

## Tailwindcss@3

```ts
const config = {
  webpackChain(chain) {
    chain.merge({
      plugin: {
        install: {
          plugin: UnifiedWebpackPluginV5,
          args: [
            {
              rem2rpx: true,
              // highlight-next-line
              tailwindcssBasedir: path.resolve(__dirname, '../'),
            },
          ],
        },
      },
    })
  },
}
```

## Tailwindcss@4

```ts
const config = {
  webpackChain(chain) {
    chain.merge({
      plugin: {
        install: {
          plugin: UnifiedWebpackPluginV5,
          args: [
            {
              rem2rpx: true,
              // highlight-next-line
              cssEntries: [
                // app.css 的路径
                path.resolve(__dirname, '../src/app.css'),
              ],
            },
          ],
        },
      },
    })
  },
}
```

使用这样的配置，就能在 `monorepo` 中使用了

---

## 生成样式只作用于view和text标签


在微信小程序中，`darkMode` 设置为 `class`/ `selector` 后，`dark:className` 类选择器在 `button` 上无效，看生成样式只作用于 `view` 和 `text` 标签

这是由于小程序是不接受 `*` 这样一个选择器的。

默认情况下， `weapp-tailwindcss` 会把 `*` 选择器转化成 `view,text` 的选择器

这个配置可以通过 `cssSelectorReplacement.universal` 进行更改，从而适配更多标签。

详见 [cssSelectorReplacement.universal 文档](/docs/api/interfaces/UserDefinedOptions#universal)

---

## 原生头条小程序使用 TailWindCSS


> 以下内容由使用 `weapp-tailwindcss` 的热心网友提供，十分感谢！

## 创建项目

创建项目 `test-miniapp`, 进入项目目录并初始化 `package.json`

```sh
cd test-miniapp
npm init -y
```

新建小程序开发目录 `src`，对应的小程序代码，生成目标代码目录为 `dist`

此时目录结构如下所示:

```
test-miniapp
-- src
-- dist
-- package.json
```

## 安装 gulp 及插件

- 本地安装 `gulp`

```sh
npm i -D gulp
```

- 安装 gulp 模块及插件

```sh
npm i -D gulp gulp-postcss gulp-plumber del@^6
```

## 安装与配置 tailwindcss

- 安装 tailwindcss

```sh
npm i -D tailwindcss@3 postcss autoprefixer
```

- 初始化 tailwindcss 配置文件

```sh
npx tailwindcss init
```

- 创建 `postcss.config.js` 并注册 `tailwindcss`

```js
module.exports = {
  plugins: {
    tailwindcss: {},
    // 假如框架已经内置了 `autoprefixer`，可以去除下一行
    autoprefixer: {},
  }
}
```

- 配置 `tailwind.config.js`

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  // 不在 content 包括的文件内的 class，不会生成对应的 css 工具类
  content: ['./src/**/*.{ttml,js}'],
  theme: {
    extend: {},
  },
  plugins: [],
}
```

- 代码引入 `tailwindcss`，打开 `src/app.ttss`

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

## 配置 vscode 插件

### Prettier - Code formatter

安装插件

```sh
npm i -D prettier prettier-plugin-tailwindcss
```

配置 `prettier.config.js`

```js
module.exports = {
  // 行尾加分号
  semi: false,
  // 使用单引号
  singleQuote: true,
  // 配置文件类型
  overrides: [
    {
      files: '*.ttml',
      options: { parser: 'html' },
    },
    {
      files: '*.ttss',
      options: { parser: 'css' },
    },
  ],
  plugins: ['prettier-plugin-tailwindcss'],
}
```

将小程序的文件包括进来，设置：`首选项->工作区->设置->扩展->Prettier->Prettier: Document Selectors`

```txt
**/*.ttml
**/*.ttss
```

- 字节小程序开发助手（微信小程序是这个：WXML - Language Service）

### Tailwind CSS IntelliSense

并配置：`首选项->工作区->设置->扩展->Tailwind CSS IntelliSense->Tailwind CSS: Include Languages`

```
项：ttml，值：html
```

### Gulp Tasks

- Gulp Tasks

  安装插件

  ```sh
  npm i -D weapp-tailwindcss-webpack-plugin
  ```

  配置 `gulpfile.js`，需要注意的事，在面板执行 `serve` 后，即使后来停止了任务，程序里的监听 `watch` 也不会停，使得后续再启动 `serve` 后，会有多个监听 `watch` 和多个监听处理程序 `watchHandler`，重复处理文件。所以停止后再启动 `serve`，应该关闭 `vscode` 后重新打开

  ```js
  const { src, dest, series, parallel, task, watch } = require('gulp')
  const postcss = require('gulp-postcss')
  const plumber = require('gulp-plumber')
  const path = require('path')
  const del = require('del')
  const tailwindcssGulp = require('weapp-tailwindcss-webpack-plugin/gulp')

  // 在 gulp 里使用, 先使用 postcss 转化 css, 触发 tailwindcss，然后转化 transformWxss，最后转化 transformJs, transformWxml
  const {
    transformJs,
    transformWxml: transformHtml,
    transformWxss: transformCss,
  } = tailwindcssGulp.createPlugins({
    rem2rpx: true,
  })

  const config = {
    srcDir: 'src',
    distDir: 'dist',
    cssExt: '.ttss',
    jsExt: '.js',
    htmlExt: '.ttml',
  }

  function transformCssFiles() {
    return src(`${config.srcDir}/**/*${config.cssExt}`)
      .pipe(plumber())
      .pipe(postcss())
      .pipe(transformCss())
      .pipe(dest(`${config.distDir}`))
  }

  function transformJsFiles() {
    return src(`${config.srcDir}/**/*${config.jsExt}`)
      .pipe(plumber())
      .pipe(transformJs())
      .pipe(dest(`${config.distDir}`))
  }

  function transformHtmlFiles() {
    return src(`${config.srcDir}/**/*${config.htmlExt}`)
      .pipe(plumber())
      .pipe(transformHtml())
      .pipe(dest(`${config.distDir}`))
  }

  function copyOtherFiles() {
    return src([
      `${config.srcDir}/**/*`,
      `!${config.srcDir}/**/*${config.cssExt}`,
      `!${config.srcDir}/**/*${config.jsExt}`,
      `!${config.srcDir}/**/*${config.htmlExt}`,
    ]).pipe(dest(`${config.distDir}`))
  }

  function promisify(task) {
    return new Promise((resolve, reject) => {
      if (task.destroyed) {
        resolve(undefined)
        return
      }
      task.on('finish', resolve).on('error', reject)
    })
  }

  // type 取值: changed, added, deleted
  async function watchHandler(type, file) {
    if (type == 'deleted') {
      await del([
        file.replace(
          `${config.srcDir}${path.sep}`,
          `${config.distDir}${path.sep}`
        ),
      ])
    } else {
      const extName = path.extname(file)
      switch (extName) {
        case config.cssExt:
          await promisify(transformCssFiles())
          break

        case config.jsExt:
          await promisify(transformCssFiles())
          await promisify(transformJsFiles())
          break

        case config.htmlExt:
          await promisify(transformCssFiles())
          await promisify(transformHtmlFiles())
          break

        default:
          await promisify(copyOtherFiles())
      }
    }
  }

  function watchTask() {
    const watcher = watch([`${config.srcDir}/**/*`])
    watcher
      .on('change', function (file) {
        console.log(`${file} is changed`)
        watchHandler('changed', file)
      })
      .on('add', function (file) {
        console.log(`${file} is added`)
        watchHandler('added', file)
      })
      .on('unlink', function (file) {
        console.log(`${file} is deleted`)
        watchHandler('deleted', file)
      })
  }

  function clean() {
    return del(config.distDir, { force: true })
  }

  const buildTasks = [
    transformCssFiles,
    transformJsFiles,
    transformHtmlFiles,
    copyOtherFiles,
  ]

  // 注册服务任务
  task('serve', series(...buildTasks, watchTask))

  // 注册清除任务
  task('clean', parallel(clean))
  ```

---

## rpx 任意值颜色或长度单位二义性与解决方案


## 这是一个什么问题？

在不使用 `weapp-tailwindcss` 的情况下，你直接写这样的 `rpx` 写法：

```html

```

最终它会生成这样的 `css`：

```css
.text-\[32rpx\] {
  color: 32rpx;
}
```

为什么 `rpx` 这个好端端的长度单位，会变成颜色呢？

原因在于 `rpx` 不是一个标准的 `W3C` 规定的 `CSS` 长度单位，这是微信小程序自己定的 `WXSS` 单位。

## 什么是 **二义性**?

`tailwindcss` 中有些原子类具有 **二义性**，比如:

- `text-[]`
- `border-[]`
- `bg-[]`
- `outline-[]`
- `ring-[]`

其中 `text-[]` 中的 `text-[16.16px]` 生成的 css 是 `font-size: 16.16px;`, 而 `text-[#123456]` 生成的 css 是 `color: #123456;`;

这就是原子类的 **二义性**

---

而 `tailwindcss` 在针对具有**二义性**的任意值写法:

这些会去**校验括号**内的任意值，是否为有效的 `CSS` 长度单位！

如果为 `true`，则生成出长度单位的 `css` 节点，反之则生成出颜色单位的 `css` 节点:

```css
/* text-[16px] */
.text-\[16px\] {
    font-size: 16px
}
/* text-[#fafafa] */
.text-\[\#fafafa\] {
    --tw-text-opacity: 1;
    color: rgb(250 250 250 / var(--tw-text-opacity))
}
```

那么问题来了，`rpx` 在单位校验的时候，由于不认识这个单位，导致单位无效所有被分到了颜色组。

```css
/* text-[32rpx] */
.text-\[32rpx\] {
    --tw-text-opacity: 1;
    color: 32rpx;
}
```

所以造成了这个问题！那么如何解决呢？

## 目前插件的解决方案

目前，我做了一个解决方案，我在 `weapp-tailwindcss` 植入了一个逻辑，使得插件可以通过分析 `tailwindcss` 运行时代码，来打上支持 `rpx` 单位的补丁，使得 `tailwindcss` 支持这样的写法，生成出长度单位的 `css`。

这也是为什么要让大家去执行 `weapp-tw patch` 的原因。

这个解决方案，最新的 `3.x` 和 `4.x` 版本，都是有效的。

<!-- 然而，以后 `tailwindcss` 将会使用由 `rust` 编写的新引擎。

这时候这种 `hack` 方式将会失效，毕竟那种情况下都是二进制文件了！

那么为了预防这种可能出现的危机，我们应该怎么做呢？ -->

## 强制CSS单位的解决方案

我们可以在使用这些带有**二义性**的单位的时候，可以通过 `length` 或 `color` 这种的前缀来指定它应该是什么，例如：

```html
...
...
<!-- 变成下列的写法 -->
...
...
```

这样就通过指定的方式，直接跳过了长度单位校验，生成出长度单位的 `css` 了！

```css
.text-\[length\:22rpx\] {
    font-size: 22rpx
}
```

同样你可以使用这 2 个前缀来指定 `css` 变量的生成形式：

```html
<!-- 生成 font-size  -->
...

<!-- 生成 color -->
...
```

## 参见

- `tailwindcss` 中的[添加自定义样式](https://tailwindcss.com/docs/adding-custom-styles#resolving-ambiguities)
- 相关 Issue：[#110](https://github.com/sonofmagic/weapp-tailwindcss/issues/110)、[#110](https://github.com/sonofmagic/weapp-tailwindcss/issues/109)

---

## `Tarojs` 中使用 `terser` 压缩代码


在 `taro` `webpack5` 环境下，这个插件和外置额外安装的 `terser-webpack-plugin` 一起使用，会导致插件转义功能失效

相关 issue：[#142](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/142)

## 现象

例如：`.h-4/6`、`!w-full` 正常会转义为`.h-4s6`、`.iw-full`，本插件失效后小程序开发者工具报编译错误 `.h-4\/6`、`.\!w-full`。

## 解决方案

请压缩代码并不要使用[链接](https://docs.taro.zone/docs/config-detail/#terserenable)中的方法，太老旧了。

使用 `taro` 配置项里的的 `terser` 配置项，参见 [`terser` 配置项](https://docs.taro.zone/docs/config-detail#terser)。

> `terser` 配置只在生产模式下生效。如果你正在使用 `watch` 模式，又希望启用 `terser`，那么则需要设置 `process.env.NODE_ENV` 为 `production`。

也就是说，直接在开发 `watch` 模式的时候，设置环境变量 `NODE_ENV` 为 `production` 就行。

另外也可以不利用 `webpack` 插件压缩代码，去使用微信开发者工具内部的压缩代码选项。

## 配置参考

```ts title="config/index.ts"
{
  terser: {
    enable: true,
    config: {
      // 相关配置项
    },
  },
}
```

然后你想要在开发时，就生效，那就需要传入 `NODE_ENV=production` 环境变量，例如:

```json title="package.json"
{
  "scripts":{
    "dev:weapp": "cross-env NODE_ENV=production npm run build:weapp -- --watch",
  }
}
```

`cross-env` 没有安装的可以安装一下

---

## H5 端原生 toast 样式偏移问题


在使用 `tailwindcss` 的时候，编译到 `h5` 平台，使用 `uni.toast` / `taro.toast` 时，出现下列的效果

![](./toast-svg-bug.jpg)

`tailwindcss` 的 `base` 中的 `preflight` 影响这个 `uni.toast` 的样式

这是由于 `preflight.css` 中默认会添加下方的样式

```css
img,
svg,
video,
canvas,
audio,
iframe,
embed,
object {
  display: block; /* 1 */
  vertical-align: middle; /* 2 */
}
```

这导致了 `svg` 变成了 `display: block;` 的状态

解决方案也非常的简单, 在 `app.wxss` 使用样式进行覆盖:

```scss
.uni-toast{
  svg {
    display: initial; // 重新初始化 uni-toast 里的样式进行覆盖 覆盖
  }
}
```

假如你使用的是 `uni-app`，那么还可以使用样式条件编译的方式来做:

```scss
/*  #ifdef  H5  */
svg {
  display: initial;
}
/*  #endif  */
```

---

## 和 NutUI 一起使用


`taro` 使用 [NutUI](https://nutui.jd.com) 的 `vue` 和 `react` 版本的共同注意点:

由于 [NutUI](https://nutui.jd.com) 必须要配合 `@tarojs/plugin-html` 一起使用。

然而 `@tarojs/plugin-html` 这个插件，默认情况下它会移除整个 `tailwindcss` 注入的 `css var` 区域块，这会造成所有 `tw-*` 相关变量找不到，导致样式大量挂掉的问题。例如（`drop-shadow-2xl`，`translate-1/2` 等样式）。

此时可以启用这个插件的 [`injectAdditionalCssVarScope`](/docs/api/interfaces/UserDefinedOptions#injectadditionalcssvarscope) 配置项，把它设为 `true`，这能在插件内部启用功能，来重新注入整个 `tailwindcss` 的 `css` 中的 `var` 区域块( `tailwindcss@3` )。

按照初始的配置，只需要添加一行即可，示例如下：

```diff
const { UnifiedWebpackPluginV5 } = require('weapp-tailwindcss/webpack')

{
  mini: {
    webpackChain(chain, webpack) {
      chain.merge({
        plugin: {
          install: {
            plugin: UnifiedWebpackPluginV5,
            args: [{
              rem2rpx: true,
+             injectAdditionalCssVarScope: true
            }]
          }
        }
      })
    }
  }
}
```

## 可能有用但是过时的方案（部分 taro 版本有用）

~~需要去配置一下 `postcss-html-transform` 这个插件~~（实在找不到方法可以尝试一下）

```js
// config/index.js
config = {
  // ...
  mini: {
    // ...
    postcss: {
      htmltransform: {
        enable: true,
        // 设置成 false 表示 不去除 * 相关的选择器区块
        // 假如开启这个配置，它会把 tailwindcss 整个 css 的 var 区域块直接去除掉
        // 需要用 config 套一层，官方文档上是错的
        config: {
          removeCursorStyle: false,
        }
      },
    },
  },
}
```

## 参见

- [taro 官方文档](https://docs.taro.zone/docs/use-h5#插件-postcss-配置项)
- 相关 Issue：[#155](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/155)

---

## 和 Taroify 一起使用


`taro` 使用 [Taroify](https://taroify.github.io/taroify.com/) 的共同注意点:

由于 [Taroify](https://taroify.github.io/taroify.com/) 引入后，会导致 `tailwindcss` 的样式被覆盖，[Taroify](https://taroify.github.io/taroify.com/) 样式的优先级会高于 `tailwindcss`。

## 解决方案

### 修改Taroify引入方式

按照[Taroify](https://taroify.github.io/taroify.com/) 修改引入方式，将 `taroify` 引入方式改成按需引入

```bash npm2yarn
# 安装插件
npm i babel-plugin-import
```

修改Babel配置文件，修改组件和图标样式的引入方式为手动引入

```js
// babel.config.js
module.exports = {
  plugins: [
    [
      'import',
      {
        libraryName: '@taroify/core',
        libraryDirectory: '',
        // 这修改为false
        style: false,
        // style: false,
      },
      '@taroify/core',
    ],
    [
      'import',
      {
        libraryName: '@taroify/icons',
        libraryDirectory: '',
        camel2DashComponentName: false,
        // 这里修改为false
        style: false,
        // style: () => "@taroify/icons/style",
        customName: name => name === 'Icon' ? '@taroify/icons/van/VanIcon' : `@taroify/icons/${name}`,
      },
      '@taroify/icons',
    ],
  ],
}
```

### 修改引入样式顺序

修改根目录下的样式引入顺序，优先引入[Taroify](https://taroify.github.io/taroify.com/) 的样式，再引入Tailwindcss的样式

```tsx
// src/app.tsx

// ...

```

```scss
// src/app.scss

@use 'tailwindcss/base';
@use 'tailwindcss/components';
@use 'tailwindcss/utilities';
```

## 参见

- [Taroify 官方文档](https://taroify.github.io/taroify.com/)

---

## 和 wot-design-uni 一起使用



---

## v1 版本插件常见问题，使用最新版本插件无须参考


## 我在 `js` 里写了 `tailwindcss` 的任意值，为什么没有生效?

详见 [issue#28](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/28)

A: 因为这个插件，主要是针对, `wxss`,`wxml` 和 `jsx` 进行转义的，`js` 里编写的 `string` 是不转义的。如果你有这样的需求可以这么写:

```js

const cardsColor = reactive([
  replaceJs('bg-[#4268EA] shadow-indigo-100'),
  replaceJs('bg-[#123456] shadow-blue-100')
])
```

> 你不用担心把代码都打进来导致体积过大，我在 'weapp-tailwindcss-webpack-plugin/replace' 中，只暴露了2个方法，代码体积 1k左右，esm格式。

## replaceJs 跨端注意点

就是在常见问题中的 `replaceJs` 这个方法原先是为小程序平台设计的，假如你一份代码，需要同时编译到小程序和 `h5` 平台，可以参考如下的封装：

```js
// util.js

// uni-app 的条件编译写法
export function replaceClass(str) {
  // #ifdef H5
  return str
  // #endif
  return replaceJs(str)
}
// or 环境变量判断
export function replaceClass(str) {
  // 需要根据自己目标平台自定义，这里仅仅给一些思路
  if(process.env.UNI_PLATFORM === 'h5'){
    return str
  }
  return replaceJs(str)
}

// then other.js
const cardsColor = reactive([
  replaceClass('bg-[#4268EA] shadow-indigo-100'),
  replaceClass('bg-[#123456] shadow-blue-100')
])
```

这样就能在多端都生效了。

---

## AI 生成小程序代码


## 提升效率

本页面为使用 AI 快速构建小程序的专题，希望能够帮助大家不断的提升自己的开发效率

同时也希望大家一起讨论参与，快速的生成他个成百上千个小程序, APP, 和网站！

## 如何参与贡献

### 前置环境

1. `nodejs@22`
2. `pnpm@10`
3. `Github` 账号

### 开始

点击 [`fork weapp-tailwindcss`](https://github.com/sonofmagic/weapp-tailwindcss/fork), 然后 `git clone` 到本地在打开这个目录:

1. 执行 `pnpm i` 安装依赖
2. 执行 `pnpm build:pkg` 构建 `website` 的本地依赖包
3. 然后 `cd website && pnpm dev` (切换到 `website` 目录, 跑 `pnpm dev`，当然你也可以在 `vscode` 里面右键打开终端，然后 `pnpm dev` 运行)
4. 访问 `http://localhost:4000` 就是 `weapp-tailwindcss` 的官方文档网站了

然后，你可以在 `website/docs/ai` 目录下，新建 `md` / `mdx` 文件，进行写作，路由会自动映射到:

`http://localhost:4000/docs/ai/{your_doc_name}` 路径中去

> 比如你创建一个 `v0.md`，你的路由就是 `http://localhost:4000/docs/ai/v0`
>
> 假如你创建一个 `index.md`，比如这个页面就是一个 `index.md` 这个页面访问路径为 http://localhost:4000/docs/ai

假如你有素材，可以放在 `website/docs/ai/assets/{your_doc_name}` 目录下，然后在 `md` 文件中，进行引用

## 示例

### 网站

1. https://v0.dev/

2. https://docs.crewai.com/guides

3. https://bolt.new/

### 上传图片

比如要实现 `网页云音乐`，就手机上打开 `网页云音乐`，然后截长图，上传到 `v0.dev`

> 此处有截图

### 提示词

然后提示词为

- `技术栈为 uni-app vue3 tailwindcss, 实现这个页面`(根据你的需求自定义)

然后复制代码即可

> 此处有截图

---

## LLM 友好文档 (llms.txt)


## 生成方式

1. 在仓库根目录执行 `pnpm --filter @weapp-tailwindcss/website build`（或 `cd website && pnpm build`）。
2. 构建后，`website/build/` 会生成：
   - `llms.txt`（索引）
   - `llms-full.txt`（完整内容）
   - `llms-quickstart.txt`（上手/AI 工作流）
   - `llms-api.txt`（配置、API、迁移与问题）
   - 去除 MDX import 的纯 Markdown 文件，方便直接喂给模型。

## 线上地址

- `https://tw.icebreaker.top/llms.txt`
- `https://tw.icebreaker.top/llms-full.txt`
- `https://tw.icebreaker.top/llms-quickstart.txt`
- `https://tw.icebreaker.top/llms-api.txt`

> 如果通过 GitHub Pages 访问，请注意前缀路径 `/weapp-tailwindcss/`。

## 给 AI 的示例提示词

> 你可以从 https://tw.icebreaker.top/llms-quickstart.txt 和 https://tw.icebreaker.top/llms-api.txt 读取 weapp-tailwindcss 的入门与配置说明，回答时请引用相关链接。

## 离线使用

- 下载 `llms-full.txt` 直接给模型。
- 或将生成阶段的 Markdown 文件整体打包后供模型上下文检索。

---

## At Property

在 CSS 里，`@property` 是一个 **注册自定义属性（CSS Custom Properties）** 的新特性，它解决了原先 `--var: value` 那种“纯字符串变量”的一些缺陷。它主要提供了 **类型约束、初始值、继承控制** 等能力，让浏览器能更高效地处理这些变量，从而带来性能优化。

---

## 1. `@property` 的基本作用

在传统 CSS 里，定义变量只能这样：

```css
:root {
  --main-color: red;
}
```

但浏览器只把它当成字符串，无法提前知道这个变量是“颜色”还是“长度”。这会带来两个问题：

- 无法做类型推断或插值优化（比如动画中间值计算）。
- 每次变量被使用时需要重新解析，性能开销更大。

而 `@property` 可以注册一个有类型的自定义属性：

```css
@property --main-color {
  syntax: '<color>';
  inherits: false;
  initial-value: red;
}
```

这样浏览器就能：

- 知道 `--main-color` 必须是一个颜色；
- 有默认值 `red`；
- 明确是否继承。

---

## 2. 为什么它能优化性能

1. **类型约束 → 加快渲染**
   浏览器不需要把字符串再解析成数值或颜色，而是直接使用已经注册好的类型。

2. **动画性能提升**
   原本 CSS 变量无法参与动画插值，例如：

   ```css
   :root { --size: 10px; }
   div { width: var(--size); transition: width 1s; }
   ```

   这是无效的。但使用 `@property` 注册后，浏览器知道它是 `<length>`，就能平滑插值：

   ```css
   @property --size {
     syntax: '<length>';
     inherits: false;
     initial-value: 10px;
   }
   ```

3. **避免 FOUC/回退渲染**
   有了 `initial-value`，在变量未设置时浏览器不用等到计算阶段才决定默认值，从而减少首次绘制闪烁。

---

## 3. 示例场景

### 动画数值

```css
@property --angle {
  syntax: '<angle>';
  inherits: false;
  initial-value: 0deg;
}

.box {
  transform: rotate(var(--angle));
  transition: --angle 1s;
}

.box:hover {
  --angle: 360deg;
}
```

👉 盒子会平滑旋转，而不是瞬间跳转。

---

### 渐变颜色

```css
@property --gradient-color {
  syntax: '<color>';
  inherits: false;
  initial-value: blue;
}

.button {
  background: linear-gradient(var(--gradient-color), white);
  transition: --gradient-color 0.5s;
}

.button:hover {
  --gradient-color: red;
}
```

👉 按钮背景色在 hover 时会有渐变过渡。

---

### 响应式尺寸

```css
@property --radius {
  syntax: '<length>';
  inherits: false;
  initial-value: 0px;
}

.card {
  border-radius: var(--radius);
  transition: --radius 0.3s;
}

.card:hover {
  --radius: 20px;
}
```

👉 hover 时圆角平滑过渡。

---

## 4. 小结

- `@property` 是 **注册型 CSS 自定义属性**。
- 带来性能优化的核心原因：**浏览器能提前知道类型和初始值，减少解析和重绘开销**。
- 实用场景：**动画过渡、主题变量、响应式设计**。

---

确实大多数人提到 `@property` 都会联想到 **transition / animation**，因为这是最直观的刚需。但其实它的用途远不止于动画，这里我给你整理一些 **非动画场景下的“刚需”案例**：

---

## 1. **防止变量未定义时的 FOUC（闪烁）**

普通自定义属性如果没定义，会导致样式不生效甚至回退为 `unset`，页面可能闪烁。
`@property` 可以通过 `initial-value` 提供一个强制的默认值，避免在首次渲染时出现意外。

```css
@property --page-bg {
  syntax: '<color>';
  inherits: true;
  initial-value: white;
}

body {
  background: var(--page-bg);
}
```

👉 即使主题系统的 JS 还没注入 `--page-bg`，页面一开始也会用 **white**，不会闪黑/闪透明。

---

## 2. **保证变量输入合法性**

普通 CSS 变量是字符串，随便写都会被吃掉。
但注册后，浏览器会进行 **语法校验**，错误值会被忽略而回退到 `initial-value`。

```css
@property --spacing {
  syntax: '<length>';
  inherits: false;
  initial-value: 1rem;
}

.card {
  padding: var(--spacing);
}
```

👉 如果有人错误地设置了 `--spacing: "abc";`，不会让布局崩掉，而是安全地回退到 `1rem`。

---

## 3. **在继承/不继承上的精细控制**

普通变量默认会继承，往往带来意料之外的问题。
例如定义主题色时，子元素继承了错误的值。
用 `@property` 就能控制是否继承。

```css
@property --border-color {
  syntax: '<color>';
  inherits: false;
  initial-value: gray;
}

.card {
  border: 1px solid var(--border-color);
}
```

👉 即使父元素设置了 `--border-color: red;`，子元素也不会继承，确保边框始终有稳定表现。

---

## 4. **与容器查询（Container Query）结合**

当你写响应式时，可能用变量去驱动不同尺寸的布局。
如果变量是注册过的，浏览器能更高效地重新计算，而不是“字符串再解析”。

```css
@property --col-gap {
  syntax: '<length>';
  inherits: false;
  initial-value: 1rem;
}

@container (width > 800px) {
  .grid {
    --col-gap: 2rem;
  }
}

.grid {
  display: grid;
  gap: var(--col-gap);
}
```

👉 Gap 会随着容器变化自动稳定更新，而不会因为未定义或错误值导致渲染异常。

---

## 5. **保证动态主题系统更鲁棒**

在“暗黑模式 / 多主题”里，用 `@property` 可以确保每个变量有定义，不会因为缺值导致奇怪的 UI。

```css
@property --theme-accent {
  syntax: '<color>';
  inherits: true;
  initial-value: #0066cc;
}

[data-theme="dark"] {
  --theme-accent: #ffcc00;
}

button {
  color: var(--theme-accent);
}
```

👉 即使某个主题忘了定义 `--theme-accent`，也能回退到默认蓝色，而不是无色。

---

## ✅ 总结

除了 `transition`/`animation`，`@property` 在这些场景也算“刚需”：

1. **提供默认值，避免首屏闪烁**
2. **校验输入合法性，保证健壮性**
3. **控制继承，避免子元素样式污染**
4. **容器查询/响应式布局下提升渲染效率**
5. **多主题系统下保证 fallback 值**

---

## 咨询与定制服务


## 一些碎碎念

国内像我这种开源，大部分都是为爱发电，除了个别朋友零星的打赏之外就再也没有人赞助了，当然打赏的钱也非常少，总的打赏金额比我一天的工资少多了。

诚然，我做开源的目的并不是为了钱，但是，我也知道一个开源项目，想要不断的持续维护，完善下去离不开钱的支持。

就像这个项目已经 `2` 年了，都是我自己维护代码，维护文档，花我自己的钱部署在国内的 `CDN` 上，总的贡献者加我一共 `2` 个人 (截止2024/1/12)，日常维护也只有我一个人。

有些朋友加我，说我文档写的不行，读不懂，那你自己贡献一个易读的版本呀？下面那个编辑此页这么大的 `link` 看到没？

<!-- ## 服务

同时鉴于找我私人咨询和定制开发项目的人越来越多，占用了我很多空余时间。

所以为了解放我自己，我也会对咨询和定制收费:

- 咨询: `200RMB/hour`，一小时起，不包 `100%` 能解决问题
- 定制项目: `2000RMB/day`，一天起，时间由我来进行评估，同样不包 `100%` 能解决问题

另外我定制写的代码，请做好 `code review`，如果产生任何的经济损失，本人概不负责。

所以希望各位小伙伴们，好好看文档，`issue`，以及模板源代码，珍惜各自的时间，好好陪伴你在乎的人。 -->

---

## 加入技术交流群


如果你在使用中遇到什么问题，也欢迎你进入交流群进行提问。

:::tip
添加时请注明来自 `Github: weapp-tw` 项目。
:::

  
    微信群
    微信号 `SonOfMagic`，备注 “weapp-tw”。
    
  

  
    QQ 二群
    扫码加入最新 QQ 技术交流群。
    
  

  
    QQ 一群（已满）
    群号 `49262447` 暂无空位，可等待或加入二群。

---

## 加载自定义字体


## 微信小程序加载自定义字体

详见: https://github.com/sonofmagic/weapp-tailwindcss/discussions/637

---

## cva 与 tailwind-variants 支持

`@weapp-tailwindcss/cva` 与 `@weapp-tailwindcss/variants` 对 `class-variance-authority`（简称 `cva`）和 `tailwind-variants` 进行了运行时封装，帮你在定义组件变体时自动处理类名冲突和小程序转义。

## 安装

```bash npm2yarn
pnpm add @weapp-tailwindcss/cva
pnpm add @weapp-tailwindcss/variants
```

> 运行时已经内置 `class-variance-authority` / `tailwind-variants`，无需再安装上游依赖。

## cva()

```ts

const button = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors',
  {
    variants: {
      tone: {
        primary: 'bg-[#2563EB] text-white hover:bg-[#1D4ED8]',
        outline: 'border border-border/60 bg-transparent',
      },
      size: {
        sm: 'h-8 px-3',
        md: 'h-9 px-4',
        lg: 'h-10 px-6',
      },
    },
    defaultVariants: {
      tone: 'primary',
      size: 'md',
    },
  },
)

button({ tone: 'outline', size: 'sm' })
// => 'inline-flex items-center ... border border-border_f60 bg-transparent h-8 px-3'
```

- 返回结果已经完成小程序转义，可直接用在 `class` 属性中；
- 与原版 `cva` 的 API、推导出的 `VariantProps` 类型完全一致；
- 如果需要自定义转义行为，可通过 `create` 获取隔离实例：

  ```ts

  const { cva: cvaForWeb } = create({ escape: false, unescape: false })
  ```

### Live Demo

```jsx live
function () {
  return <CvaDemo/>
}
```

可以动态切换 tone、size 以及是否关闭 escape/unescape，对比运行时返回的不同字符串。

## tailwind-variants

直接从 `@weapp-tailwindcss/variants` 导入 `tv`/`cn`/`createTV` 等工具，即可在运行时获得与小程序兼容的类名字符串。封装会自动把合并结果转义，保持与编译期一致。

该包还提供了对 [`tailwind-variants`](https://tailwind-variants.org/) 的封装，导出项包括：

| 导出 | 说明 |
| --- | --- |
| `tv` | 等价于默认的 `tailwind-variants` 工厂，但会自动执行小程序转义与合并。 |
| `createTV` | 返回一个「预配置」的 `tv` 工厂，常用于库内定制。 |
| `cn` | 将多个类名组合并（默认开启 `twMerge`），再进行小程序转义。 |
| `cnBase` | 纯拼接工具，不做合并，仅处理转义。 |
| `defaultConfig` | 直接透传上游默认配置。 |
| `create` | 工厂函数，允许为 `tv` / `cn` 自定义转义行为。 |

### 示例：组合变体

```ts

const badge = tv({
  base: 'inline-flex items-center rounded-full px-2 text-xs font-semibold',
  variants: {
    tone: {
      neutral: 'bg-[#F4F4F5] text-[#18181B]',
      success: 'bg-[#DCFCE7] text-[#166534]',
      danger: 'bg-[#FEE2E2] text-[#B91C1C]',
    },
    soft: {
      true: 'bg-opacity-75',
    },
  },
  compoundVariants: [
    {
      tone: 'danger',
      soft: true,
      class: 'bg-[#F87171] text-white',
    },
  ],
  defaultVariants: {
    tone: 'neutral',
  },
})

badge({ tone: 'success' })
// => 'inline-flex ... bg-_b_hDCFCE7_B text-_b_h166534_B'
```

### 自定义合并策略

`cn` 默认会调用 `twMerge` 去重。如果想关闭合并或覆盖其配置，可以使用第二个参数：

```ts

const mergeLater = cn('text-[#ececec]', 'text-[#ECECEC]')
mergeLater() // => 'text-_b_hECECEC_B'

mergeLater({ twMerge: false })
// => 'text-_b_hececec_B text-_b_hECECEC_B'
```

当需要精细化控制转义（例如 SSR 或混合应用中），同样可以结合 `create`：

```ts

const { tv: tvForWeb, cn: cnForWeb } = create({
  escape: false,
  unescape: false,
})
```

这样生成的类名就会保持原样，方便在 Web 渲染时与已有代码复用。

### Live Demo

```jsx live
function () {
  return <VariantsDemo/>
}
```

示例中可切换 tone、soft、twMerge 以及 escape/unescape，观察 `tv` 与 `cn` 输出的差异。

---

## 集成与排障指南

## 与构建工具协作

### 保留关键函数名

`weapp-tailwindcss` 会在编译阶段扫描源码中的 `twMerge`、`twJoin`、`cva`、`cn`、`tv`、`weappTwIgnore` 等标识符。当打包器在压缩环节改写了函数名（如将 `twMerge` 压成 `a`），扫描就会失败，导致运行时字符串无法还原。

- **esbuild / Vite**

  ```ts title="vite.config.ts"
  export default defineConfig({
    build: {
      minify: 'esbuild',
      terserOptions: undefined,
      rollupOptions: {},
    },
    esbuild: {
      keepNames: true,
    },
  })
  ```

- **Terser / Webpack**

  ```js title="webpack.config.js"
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          mangle: {
            keep_classnames: true,
            keep_fnames: true,
          },
        },
      }),
    ],
  },
  ```

完整的配置示例可以参考仓库里的 [`packages/minify-preserve`](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/packages/minify-preserve)。

### 选择运行时版本

不同主版本的 Tailwind CSS 需要配套的运行时包：

```ts
// tailwindcss v3 项目

// tailwindcss v4 项目

```

## 与 weapp-tailwindcss 插件联动

1. **同步依赖版本**：确保项目使用的 `weapp-tailwindcss` 主版本与文档中的说明一致，避免编译期和运行时的转义映射不匹配。
2. **配置忽略列表**：如果封装了新的工具函数来代理 `twMerge`/`cva` 等 API，请把这些名称添加到 [`ignoreCallExpressionIdentifiers`](../../api/interfaces/UserDefinedOptions.md#ignorecallexpressionidentifiers) 或 [`ignoreTaggedTemplateExpressionIdentifiers`](../../api/interfaces/UserDefinedOptions.md#ignoretaggedtemplateexpressionidentifiers)。
3. **联调第三方库**：当需要把类名传给第三方运行时代码（而不是直接渲染到模板上）时，可以结合 `weappTwIgnore` 手动控制是否保留原始字符串。

## 调试建议

- **验证运行时版本**：在构建日志或控制台输出 `tailwindMergeVersion`，确认当前入口是否匹配预期。
- **确认转义链路**：可以在本地执行下面的脚本，检查 `twMerge` 是否正确完成「还原 ➜ 合并 ➜ 重新转义」：

  ```bash
  node - <<'NODE'
  const { twMerge } = require('@weapp-tailwindcss/merge')
  console.log(twMerge('text-[#ececec]', 'text-[#ECECEC]'))
  NODE
  ```

- **排查压缩产物**：打包后搜索产物中是否仍然存在 `twMerge`、`weappTwIgnore` 等关键字；若已经被替换，复查压缩配置。
- **生成快照**：对于依赖大量运行时字符串的项目，建议编写 Vitest 快照测试，记录 `twMerge`/`tv` 的输出，方便升级 Tailwind CSS 或迁移到 v4 时比对差异。

---

## 概览

`@weapp-tailwindcss/merge` 是面向小程序生态的 [`tailwind-merge`](https://github.com/dcastil/tailwind-merge) 运行时封装。它在保留原库全部 API 的基础上，对类名做了小程序合法化转义，并与 `weapp-tailwindcss` 编译期插件联动，提供稳定的跨端开发体验。

## 为什么要使用 merge 运行时

- **动态类名更安全**：在组件里根据状态拼接类名时，`twMerge` 会自动剔除冲突项，确保最终样式一致。
- **小程序专属转义**：运行时会把诸如 `[#ececec]`、`[length:24rpx]` 等非法字符转成小程序可识别的占位符，并在编译期再还原。
- **覆盖多个 Tailwind CSS 主版本**：`@weapp-tailwindcss/merge` 针对 `tailwindcss@4`（基于 `tailwind-merge@3`），而 `@weapp-tailwindcss/merge-v3` 保持对 `tailwindcss@3` 的长期支持，两者 API 完全一致。
- **保留原生 API**：`twMerge`、`twJoin`、`extendTailwindMerge`、`createTailwindMerge` 等函数与原版完全一致，迁移成本低。

:::info 与原库的差异
为了适配小程序，`@weapp-tailwindcss/merge` 会在运行时做两件事：

1. 先调用 `@weapp-core/escape` 对字符串「去转义」，把已经被编译期处理过的值还原为标准 Tailwind 类名；
2. 调用原始的 `tailwind-merge` 完成合并后，再重新转义一次，交给小程序端运行。

如果你在纯 Web 项目中使用，请参考下方的「多端项目」章节配置。
:::

## 运行时矩阵

| 包名 | 适用场景 | 说明 |
| --- | --- | --- |
| `@weapp-tailwindcss/runtime` | 共享依赖 | 封装 escape/unescape、`clsx`、`weappTwIgnore`，被下游包复用 |
| `@weapp-tailwindcss/merge` | `tailwindcss@4` | 基于 `tailwind-merge@3`，默认入口 |
| `@weapp-tailwindcss/merge-v3` | `tailwindcss@3` | 基于 `tailwind-merge@2`，专为老项目保留 |
| `@weapp-tailwindcss/cva` | `class-variance-authority` | 自动 escape 的 `cva()` 运行时 |
| `@weapp-tailwindcss/variants` | `tailwind-variants` | 提供 `tv`/`cn` 等扩展能力 |

## 安装

```bash npm2yarn
npm i @weapp-tailwindcss/merge
```

> 适用于 `tailwindcss@4` 的项目。若你仍在维护 `tailwindcss@3`，请改为安装 `@weapp-tailwindcss/merge-v3`：

```bash npm2yarn
npm i @weapp-tailwindcss/merge-v3
```

## 快速上手

```ts

const buttonClass = twMerge(
  'px-2 py-1 bg-red hover:bg-dark-red',
  'p-3 bg-[#B91C1C]'
)

// => 'hovercbg-dark-red p-3 bg-_hB91C1C_'
```

同样的写法在 Web 端会得到 `hover:bg-dark-red p-3 bg-[#B91C1C]`。在小程序里之所以出现 `_h`、`_` 等占位符，是因为运行时完成了转义。`weapp-tailwindcss` 插件会在编译阶段把这些占位符还原成合法类名。

### 与 weapp-tailwindcss 的编译期配合

- `weapp-tailwindcss` 默认把 `twMerge`、`twJoin`、`cva` 标记为「无需再次转义」的调用点，如果你自定义了函数名（例如把 `twMerge` 重命名为 `cn`），需要在配置里补充 [`ignoreCallExpressionIdentifiers`](../../api/interfaces/UserDefinedOptions.md#ignorecallexpressionidentifiers)。
- 对于模板字符串，可以使用 `weappTwIgnore` 标签跳过编译期处理：

  ```ts

  const raw = weappTwIgnore`text-[#123456]`
  ```

  这个 helper 实际上就是 `String.raw`，但它可以让插件准确识别并跳过转义。

### tailwind-variants 快速体验

`@weapp-tailwindcss/variants` 提供了 [`tailwind-variants`](https://tailwind-variants.org/) 的运行时封装，在小程序环境中同样可以使用 `tv`/`cn` 输出带转义的类名：

```ts

const badge = tv({
  base: 'inline-flex items-center rounded-full px-2 text-xs font-semibold',
  variants: {
    tone: {
      neutral: 'bg-[#F4F4F5] text-[#18181B]',
      success: 'bg-[#DCFCE7] text-[#166534]',
      danger: 'bg-[#FEE2E2] text-[#B91C1C]',
    },
  },
  defaultVariants: {
    tone: 'neutral',
  },
})

badge({ tone: 'success' })
// => 'inline-flex ... bg-_b_hDCFCE7_B text-_b_h166534_B'
```

更多组合用法、`cn` 聚合器以及逃逸策略见后文的 <Link to="/docs/community/merge/cva-and-variants"><code>cva 与 tailwind-variants 支持</code></Link> 章节。

### 多端项目：按需控制转义

`create` 工厂允许你为不同运行时定制 escape 策略：

```ts

const { twMerge: mergeForMiniProgram } = create()
const { twMerge: mergeForWeb } = create({
  escape: false,
  unescape: false,
})

mergeForMiniProgram('text-[#ececec]', 'text-[#ECECEC]') // → 'text-_b_hECECEC_B'
mergeForWeb('text-[#ececec]', 'text-[#ECECEC]')         // → 'text-[#ECECEC]'
```

- `escape: false` 表示结果保持原样（适合 Web 或同构渲染）。
- `unescape: false` 可跳过运行前的「反转义」，用于确保输入不会被改写。
- 如果只想自定义映射表，传入 `escape: { map: { '#': '__hash__' } }` 即可；运行时会把自定义映射与默认映射合并，保证编译期和运行时的行为一致。

### 在线体验

```jsx live
function () {
  return <MergeDemo/>
}
```

上方示例允许切换「禁用 escape/unescape」，用来对比运行时转义前后的差异。

---

## 运行时 API

`@weapp-tailwindcss/runtime` 是所有运行时包的公共底座，统一提供 escape/unescape、`clsx` 封装、`weappTwIgnore` 以及 `createRuntimeFactory`。`@weapp-tailwindcss/merge`、`merge-v3`、`cva`、`variants` 都是基于它实现的。

## 安装

```ts
pnpm add @weapp-tailwindcss/merge
```

如果项目仍在使用 Tailwind CSS v3，请改用 `@weapp-tailwindcss/merge-v3`；而 `@weapp-tailwindcss/runtime` 在大部分场景下会作为间接依赖被自动安装。

## Runtime 基本面

```ts

  clsx,
  weappTwIgnore,
  resolveTransformers,
  createRuntimeFactory,
} from '@weapp-tailwindcss/runtime'
```

- `clsx` / `ClassValue`：统一的类名聚合工具，避免各包重复安装 `clsx`
- `weappTwIgnore`：`String.raw` 的别名，用于跳过 weapp 转义
- `resolveTransformers(createOptions)`：返回 `{ escape, unescape }`
- `createRuntimeFactory(factoryOptions)`：将 `tailwind-merge`、`tailwind-variants` 等库注入 weapp 运行时

## merge 运行时的标准导出

所有 API 都与 `tailwind-merge` 原版保持一致，只是在调用前后包裹了转义逻辑。你可以继续使用熟悉的导入路径：

```ts

  twMerge,
  twJoin,
  createTailwindMerge,
  extendTailwindMerge,
  getDefaultConfig,
  mergeConfigs,
  tailwindMergeVersion,
  weappTwIgnore,
  create,
} from '@weapp-tailwindcss/merge'
```

> - `@weapp-tailwindcss/merge` 适配 `tailwindcss@4`
> - `@weapp-tailwindcss/merge-v3` 适配 `tailwindcss@3`
>
> 两个包内部均依赖 `@weapp-tailwindcss/runtime`，API 完全一致。

## twMerge(...classValues)

合并 Tailwind 工具类并移除冲突项，返回一个经过小程序转义的字符串。支持布尔值、数字、数组、嵌套数组等所有 `tailwind-merge` 支持的参数类型。

```ts
twMerge('px-2 py-1', ['px-6', { 'py-5': shouldExpand }])
// => 'px-6 py-5'

twMerge('text-[#ececec]', flag && 'text-[#ECECEC]')
// => 'text-_b_hECECEC_B'
```

### 常见问题

- 如果输入已经是转义过的占位符（例如 `text-_b_hececec_B`），运行时会先调用 `unescape` 还原，再进行合并，因此不会出现重复。
- 返回结果永远是字符串；若想在 Web 端保持原样，需要使用下文的 `create` 禁用转义。

## twJoin(...classValues)

单纯把类名拼接成一个字符串，不做冲突判断，但仍会执行「先 unescape、后 escape」的流程，保证多端结果一致。适合用于低成本地去除 `undefined` / `false`。

```ts
twJoin('text-[#ececec]', condition && 'bg-[#010101]')
// => 'text-_b_hececec_B bg-_b_h010101_B'
```

## createTailwindMerge(config)

与原版一致，可以基于自定义配置创建一个新的 `twMerge` 实例。区别在于返回值会自动带上小程序转义。

```ts
const mergeCard = createTailwindMerge({
  classGroups: {
    card: ['card-default', 'card-primary'],
  },
})

mergeCard('card-default card-primary') // => 'card-primary'
```

同一个实例在调用过程中仍然执行转义，因此你可以安全地混用转义前后的字符串。

## extendTailwindMerge(config)

基于默认配置扩展新的合并规则，返回一个新的 `twMerge` 运行时。

```ts
const mergeWithCustomSpacing = extendTailwindMerge({
  classGroups: {
    spacing: ['gap-safe', 'gap-huge'],
  },
})

mergeWithCustomSpacing('gap-huge gap-safe') // => 'gap-safe'
```

## getDefaultConfig() 与 mergeConfigs(a, b)

两者直接透传自 `tailwind-merge`：

- `getDefaultConfig()` 返回内部使用的原始配置对象；
- `mergeConfigs(a, b)` 用于把两个配置合并成一个新的配置，常见于库内部复用。

## tailwindMergeVersion

表示当前入口绑定的 `tailwind-merge` 主版本：

- `2` ➜ 运行时基于 `tailwind-merge@2`，适配 `tailwindcss@3`
- `3` ➜ 运行时基于 `tailwind-merge@3`，适配 `tailwindcss@4`

该值可用于调试或在运行时判断最终行为。

## weappTwIgnore

模板字符串标签函数，本质是 `String.raw`。与 `weapp-tailwindcss` 的 `ignoreTaggedTemplateExpressionIdentifiers` 配置联动，用来标记「不要转义」的代码片段。

```ts

const raw = weappTwIgnore`
  bg-[#123456]
  before:content-['>']
`
```

当小程序端确实需要原始类名（例如传递给第三方库）时，可借助该标签避免被编译期改写。

## create(options?)

`create` 会根据传入的 `options` 返回一组隔离的运行时函数（`twMerge`、`twJoin`、`createTailwindMerge`、`extendTailwindMerge`），用于控制转义行为：

```ts
const { twMerge: mergeForWeb } = create({ escape: false, unescape: false })
const { twMerge: mergeForMiniProgram } = create()
```

### CreateOptions

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `escape` | `false` \| `EscapeOptions` | `{ map: 默认映射 }` | 控制输出时是否转义；传入对象可自定义映射表。 |
| `unescape` | `false` \| `UnescapeOptions` | `{ map: 默认映射 }` | 控制在合并前是否还原占位符。 |

- 传入 `false` 会彻底关闭对应阶段；
- 当 `escape`/`unescape` 同时提供自定义 `map` 时，运行时会自动与默认映射 `MappingChars2String` 合并，确保和编译期保持一致；
- 该工厂返回的实例不会影响默认导出的全局实例，可在多端方案里自由组合。
- `EscapeOptions`/`UnescapeOptions` 类型来自 `@weapp-core/escape` 包，与编译期所使用的转义逻辑保持一致。

```ts

const custom = create({
  escape: {
    map: {
      '#': '__hash__',
    },
  },
  unescape: {
    map: {
      '#': '__hash__',
    },
  },
})

custom.twMerge('text-[#ececec]')        // => 'text-_b__hash__ececec_B'
custom.twMerge('text-_b__hash__ececec_B') // => 'text-_b__hash__ececec_B'
```

## 基于 runtime 的其他包

- `@weapp-tailwindcss/cva`：封装 `class-variance-authority`，详见 [cva 支持](/docs/community/merge/cva-and-variants#cva)  
- `@weapp-tailwindcss/variants`：封装 `tailwind-variants`，详见 [variants 支持](/docs/community/merge/cva-and-variants#tailwind-variants)  
- `@weapp-tailwindcss/merge-v3`：面向 `tailwindcss@3` 的长期支持分支

它们全部依赖 `@weapp-tailwindcss/runtime`，因此可以共享 escape 配置、`weappTwIgnore` 以及 `clsx`。

---

## 适配的 `tailwindcss` 插件


虽然，相当一部分 `tailwindcss` 插件，都可以直接在 `weapp-tailwindcss` 里使用了。

但是小程序中 `wxss` 这种 `css` 子集，是原生不支持许多 `css` 的写法和选择器的，所以免不了在使用某些插件的时候会报错。

比如 `tailwindcss/typography`, `daisyui` 等等。

所以很多时候开发它们的迁移/阉割版本是不可避免。

比如 `tailwindcss/typography` 的小程序适配版本就是 `@weapp-tailwindcss/typography`

而 [`IceStack`](https://ui.icebreaker.top/zh-CN/docs/usage) 内部也包含了 `daisyui` 的微信小程序适配。

---

## 🔥各个框架的模板


当你配置不对的时候，也可以参考参考, 其中带有 🔥 标志的为推荐使用版本

:::tip
假如你遇到网络问题，无法登陆 `Github` 的时候，你可以使用 `Gitee`。

登陆进 `Gitee` 之后，点击右上角的加号，有一个导入仓库功能。然后你想使用什么模板，你就右键下方模板的link，点击复制链接地址，然后把复制的url，粘贴到`Gitee`导入仓库的 `Git Repository URL` 中去，点击确定导入之后，过几秒仓库就能够同步完成，就可以下载了。
:::

## uni-app

---

### 使用 `uni-app cli` 进行构建 `vscode` 开发

<TemplateLink
  hot
  title="uni-app-vite-vue3-tailwind-vscode-template"
  href="https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template"
  repoOwner="sonofmagic"
  repo="uni-app-vite-vue3-tailwind-vscode-template"
/>

<TemplateLink
  title="uni-app-vue2-tailwind-vscode-template"
  href="https://github.com/sonofmagic/uni-app-vue2-tailwind-vscode-template"
  repoOwner="sonofmagic"
  repo="uni-app-vue2-tailwind-vscode-template"
/>

<TemplateLink
  title="monorepo-uniapp-template"
  href="https://github.com/sukbearai/x-dev-uni"
  repoOwner="sukbearai"
  repo="x-dev-uni"
/>

{/* ### 若依移动端 (`hbuilderx` 集成 `tailwindcss`)

<TemplateLink
  hot
  title="若依移动端"
  description="Gitee 地址"
  href="https://gitee.com/sonofmagic/RuoYi-App"
/> */}

### 使用 `hbuilderx` 进行构建和开发

<TemplateLink
  title="uni-app-vue3-tailwind-hbuilder-template"
  href="https://github.com/sonofmagic/uni-app-vue3-tailwind-hbuilder-template"
  repoOwner="sonofmagic"
  repo="uni-app-vue3-tailwind-hbuilder-template"
/>

<TemplateLink
  deprecated
  title="uni-app-vue2-tailwind-hbuilder-template"
  description="架构太过老旧，只能作为集成参考，新项目请勿使用"
  href="https://github.com/icebreaker-template/uni-app-vue2-tailwind-hbuilder-template"
  repoOwner="icebreaker-template"
  repo="uni-app-vue2-tailwind-hbuilder-template"
/>

## tarojs

---

### 使用 `tarojs` 进行构建 `vscode` 开发

<TemplateLink
  hot
  title="taro-react-tailwind-vscode-template"
  href="https://github.com/sonofmagic/taro-react-tailwind-vscode-template"
  repoOwner="sonofmagic"
  repo="taro-react-tailwind-vscode-template"
/>

## native

---

### 原生小程序开发模板

<TemplateLink
  hot
  title="weapp-vite-tailwindcss-template"
  description="weapp-vite 打包"
  href="https://vite.icebreaker.top/guide/"
/>

<TemplateLink
  title="vue-mini-tailwindcss-template"
  description="vue-mini 支持"
  href="https://github.com/sonofmagic/vue-mini-tailwindcss-template"
  repoOwner="sonofmagic"
  repo="vue-mini-tailwindcss-template"
/>

#### 下方的技术架构过于老旧，不推荐

<TemplateLink
  deprecated
  title="native-weapp-tailwindcss-template"
  description="cli 打包"
  href="https://github.com/sonofmagic/native-weapp-tailwindcss-template"
  repoOwner="sonofmagic"
  repo="native-weapp-tailwindcss-template"
/>

<TemplateLink
  deprecated
  title="weapp-tailwindcss-gulp-template"
  description="gulp 打包"
  href="https://github.com/sonofmagic/weapp-tailwindcss/tree/main/demo/gulp-app"
/>

<TemplateLink
  deprecated
  title="weapp-native-mina-tailwindcss-template"
  description="webpack 打包"
  href="https://github.com/sonofmagic/weapp-native-mina-tailwindcss-template"
  repoOwner="sonofmagic"
  repo="weapp-native-mina-tailwindcss-template"
/>

## `tailwindcss@4`

所有的 `tailwindcss@4` 模板都维护在下方的地址，标志为标题带有 `tailwindcss-v4` 字样:

https://github.com/icebreaker-template

## 更多模板

你还可以在项目的根目录的 `demo` 文件夹中，找到各个框架的注册方式。

里面有 `gulp` , `mpx` , `webpack5` , `rax` , `taro-react` , `taro-vue2` , `taro-vue3` , `uni-app vue2 webpack5` , `uni-app vue3 vite` 的项目

---

## @weapp-tailwindcss/typography


小程序 `@tailwindcss/typography` 富文本渲染方案

`@weapp-tailwindcss/typography` 是 `@tailwindcss/typography` 的小程序迁移版本，帮助你渲染美丽的富文本。

<iframe src="//player.bilibili.com/player.html?aid=751356751&bvid=BV16k4y1S7nY&cid=1408037969&p=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

## 介绍

在小程序中，我们往往使用 [rich-text](https://developers.weixin.qq.com/miniprogram/dev/component/rich-text.html) 组件，然后从后端请求到 `html` 字符串片段，然后放到小程序中去渲染，所示:

```html
<rich-text nodes="{{nodes}}"></rich-text>
```

但是，使用它有很多的限制，比如自定义组件中使用 `rich-text` 组件，那么仅自定义组件的 `wxss` 样式对 `rich-text` 中的 `class` 生效。

所以针对这种 `case` 设计了 `@weapp-tailwindcss/typography` 来解决小程序渲染富文本的问题。

## 如何使用?

### 安装

```sh npm2yarn
npm i -D @weapp-tailwindcss/typography
```

### 注册

这里比较特殊，由于`rich-text` 组件的样式限制: 自定义组件中使用 `rich-text` 组件，那么仅自定义组件的 `wxss` 样式对 `rich-text` 中的 `class` 生效

#### 创建组件

这里以 `uni-app vue3 vite` 项目为例，比如此时我们目标组件为 `typography.vue`:

```html
<template>
  <rich-text class="prose" :nodes="nodes"></rich-text>
</template>

<script lang="ts" setup>
// getHtml 为你获取 html 的方法

const nodes = transform(getHtml())
</script>

<style>
@config "./tailwind.typography.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>
```

#### 创建独立 tailwindcss 上下文

在当前 `typography.vue` 组件目录下，单独创建一个 `tailwind.typography.config.js` 来创建独立的 `tailwindcss` 上下文，单独处理它，

```js
const path = require('node:path');

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [path.resolve(__dirname, './typography.vue')],
  plugins: [require('@weapp-tailwindcss/typography')],
  corePlugins: {
    preflight: false,
  },
};
```

此时渲染 `html` 就生效了。

#### 指定全局样式配置文件

但是这还没有结束，为了防止这个上下文，影响到你全局的 `tailwindcss` 上下文，你必须做一个显式指定。

此时要在你的引入 `tailwindcss` 的入口文件处(`App.vue`)，声明它用的是根目录的 `tailwind.config.js`

```css
@config "../tailwind.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;
```

这样配置才最终完成。

> 使用 @import 要注意加载顺序是不同的，详见 <https://tailwindcss.com/docs/functions-and-directives#config>

## 配置项

大体的配置项与 <https://tailwindcss.com/docs/typography-plugin> 是相同的

额外添加了 `mode` 和 `classPrefix`

## 原理解释

`@weapp-tailwindcss/typography/transform` 这个方法是为你的 `html` 所有的元素给大上 `class` 属性，这样才能使用那些 `prose-headings:bg-red-100`,`prose-h5:text-green-400` 的写法，来覆盖原先富文本的样式。

而 `@weapp-tailwindcss/typography` 通过 `mode` 的配置，`mode` 为 `tag` 表示为原先默认的行为，`mode` 为 `class`，此时插件更改为对所有的 `class` 选择器生效，而不是对所有的标签生效。默认值为 `class`

假如你觉得 `@weapp-tailwindcss/typography/transform` 放在小程序端处理，体积太大了，你可以把它放在 `nodejs` 服务中，预先处理。

## Demo

<https://github.com/sonofmagic/weapp-tailwindcss/blob/main/demo/uni-app-vue3-vite/src/pages/issue/typography.vue>

---

## 生态以及解决方案


## 插件

### [@weapp-tailwindcss/typography](./community/typography)

### [开箱即用的小程序icon解决方案](./icons)

### [uni-app 条件编译语法糖插件](./quick-start/uni-app-css-macro)

## 模板

### [各个框架的模板](./community/templates)

## 解决方案

### [小程序多主题方案](./quick-start/apply-themes)

### [构建以及引入外部组件](./quick-start/build-or-import-outside-components)

### [tailwindcss 多上下文与独立分包](./quick-start/independent-pkg)

### [wxs的转义与处理](./quick-start/wxs)

## 社群

### [加入技术交流群](./community/group)

<!-- ### [咨询与定制服务](./community/consult) -->

---

## 版权信息



---

## 技术演进


目前 `weapp-tailwindcss` 使用:

- `babel` 来处理 `js`/`wxs`
- `htmlparser2` 来处理 `wxml`
- `postcss` 来处理 `wxss`

## wxml

使用 `htmlparser2` 已经是 `v2` 版本后期的事情了

一开始使用的是 `@vivaxy/wxml` 这是一个 `wxml` 的 `ast` 工具

但是它已经很久没有更新了，在遇到内联的 `wxs` 的时候，会直接挂掉

后续使用正则来出来，但是 正则 同样是有问题的，比如这样一个 case:

`<view class="{{2>1?'xxx':'yyy'}}"></view>`

由于 `2>1`的存在，它会提前匹配并进行返回，所以还是要使用 `ast` 工具才能做到精确。

而 `parse5` 对 html5 是严格的匹配，不怎么适用于 wxml

所以最终选择 `htmlparser2` 来处理 `wxml`

## babel

这里主要有1个演进原先是

`@babel/parser`->`@babel/traverse`->`@babel/generator`

但是这样，相当于重新生成了一遍用户的 js，同时 sourcemap 也会错乱

所以后续改成了 `@babel/parser`->`@babel/traverse`->`magic-string#replace` 的方式，做精确匹配

## postcss

这里的演进比较多，也就是相当于加入了多个 postcss 插件进行转换。

---

## 如何贡献


> 推荐阅读 [如何为开源做贡献?](https://opensource.guide/zh-hans/how-to-contribute/)

## 如何本项目做贡献？

其实非常简单，你不一定需要贡献代码，你提一个 `issue`，回答一个问题，写一篇相关的文章，这些都是为项目做贡献，无需拘泥于具体的形式。

无论你做什么，只要你对这个项目的发展，起到正向的帮助的，我们对你表示感谢 🙏！

## 贡献指南

首先，你必须 `fork` [`weapp-tailwindcss`](https://github.com/sonofmagic/weapp-tailwindcss) 这个项目到你自己的账号下，然后你再把它 `git clone` 到你的本地。

### 文档贡献

目前本网站所有的文档都在 [weapp-tailwindcss/website](https://github.com/sonofmagic/weapp-tailwindcss/tree/main/website) 目录下，

你可以在里面任意添加文章，修改文章，删除文章，然后提交到你 `fork` 的分支，然后在 `pr` 到 `weapp-tailwindcss` 的 `main` 分支。

`website` 这个项目会被部署到 `https://tw.icebreaker.top` 这个域名下，作为 [`weapp-tailwindcss`](https://github.com/sonofmagic/weapp-tailwindcss) 的文档展示。

就项目而言，这是一个 `docusaurus@2` 的项目，和 `vuepress`/`vitepress` 类似，它也是一个开源的文档生成工具，不过它是 `react` 写的。

> `docusaurus` 相关的文档见 [docusaurus.io](https://docusaurus.io/)

#### 目录介绍

- `docs`: `md`,`mdx` 文档所在位置
- `src`: 源代码，你可以在这里写 `jsx`,`tsx`
- `static`: 静态资源所在位置
- `docusaurus.config.js`: `docusaurus` 配置，可在此处调配 `navbar`
- `sidebars.js`: 调整所有 `sidebar` 的配置文件，当你添加一篇文档，你需要在这里声明它的位置

### 代码贡献

#### 根目录介绍

- `assets`: 存放所有静态资源的地方，包括 `weapp-tailwindcss` 所有的 `logo`，还有对应的 `figma` 文件可以做二次设计开发
- `bin`: `cli` 入口文件
- `demo`: 存放所有 `demo` 的地方，里面包含各个框架的各种使用方式
- `demo-linked`: 存放部分 `demo` 的地方，不同的是，这里 `weapp-tailwindcss` 的注册方式都是本地 `linked`
- `e2e`: 存放 `e2e` 测试的地方，测试对象就是 `demo` 下的那些项目
- `plugins`: 存放一些从 `web` 迁移到小程序的 `tailwindcss` 插件，目前包含 `@weapp-tailwindcss/typography`
- `scripts`: 存放一些常用脚本的位置，比如 `readme.md` 生成脚本等等
- `src`: 源代码目录，待会细讲
- `test`: 单元测试和测试快照位置，一般出现一个 `bug`，我们都需要设计 1 到多个测试用例，测试通过后才能发布
- `website`: 文档网站

#### 使用技术介绍

- 单元测试和 `e2e` 测试现在完全使用了 `vitest` 过去曾经是 `jest`
- 打包使用的是 `rollup`

### src 源代码介绍

目前 `weapp-tailwindcss` 使用:

- `babel` 来处理 `js`/`wxs`
- `htmlparser2` 来处理 `wxml`
- `postcss` 来处理 `wxss`

Why？

#### wxml htmlparser2

使用 `htmlparser2` 已经是 `v2` 版本后期的事情了

一开始使用的是 `@vivaxy/wxml` 这是一个 `wxml` 的 `ast` 工具

但是它已经很久没有更新了，在遇到内联的 `wxs` 的时候，会直接挂掉，另外还有各种问题。

后续使用正则来处理 `wxml`，但是正则同样是有问题的，比如这样一个 `case`:

`<view class="{{2>1?'xxx':'yyy'}}"></view>`

由于 `2>1`的存在，它会提前匹配并进行返回，所以还是要使用 `ast` 工具才能做到精确。

而 `parse5` 对 `html5` 是严格的匹配，不怎么适用于 `wxml`

所以最终选择 `htmlparser2` 来处理 `wxml`

#### js/wxs babel

这里主要有1个演进原先是

`@babel/parser`->`@babel/traverse`->`@babel/generator`

但是这样，相当于重新生成了一遍用户的 js，同时 sourcemap 也会错乱

所以后续改成了 `@babel/parser`->`@babel/traverse`->`magic-string#replace` 的方式，做精确匹配

#### postcss

这里的演进比较多，也就是相当于加入了多个 postcss 插件进行转换。

### src 目录介绍

- `babel`: `babel` 工具类
- `bundlers`: 存放使用方式，目前提供 `webpack`,`vite`,`gulp` 插件的使用方式
- `cache`: 缓存策略，用于解决在项目比较大时，热更新的速度问题，本质上是通过计算文件内容的 `hash` 值，如果没有发生改变就跳过 `ast` 的解析，直接返回结果的策略
- `css-macro`: `uni-app` 样式条件编译插件
- `debug`: `debug` 调试用
- `extractors`: 提取器，用于分割字符串
- `js`: 用于处理转译 `js` 结果的地方
- `postcss`: 和 `postcss` 相关，用于处理所有 `wxss` 结果的地方
- `tailwindcss`: 用于 `hack` `tailwindcss`，给它打补丁，强制让它支持小程序的一些特性
- `wxml`: 处理 `wxml` 的地方
- `*`: `src` 其他一些文件，大多是一些导出文件

想要知道各自做了什么事情，详见 [深入核心原理](./principle)

## 如何本地调试

你是否对我这种类型项目的本地调试感到棘手？

其实本地调试很简单，你怎么调试 `webpack`/`vite`/`gulp`/`postcss`插件，同样可以用这些的经验来调试这个项目。

### 单元测试调试

目前这个项目里有大量的单元测试，来对各个模块进行测试。

目前我使用的使用 `vitest` 来进行进行单元测试 (之前使用 `jest` + `ts-jest` 但是它对 `esm`+`cjs`的混合引用的模式，支持不算很好)

所以你可以安装 `vscode` 的 `vitest` 插件，安装完成之后，在 `vscode` 左侧的测试管理器会看到大量的测试用例，这些都是它感应到了 `test` 项目里的单元测试。

此时，你可以选中一个，你就可以进行 `运行`，或者 `调试` ，或者 `打开测试文件` 的操作。

当然你也可以直接打开 `*.test.ts` 测试文件，此时，在 `describe`/`test`/`it` 在前面会出现一个运行的绿色 `icon`，直接点是 `运行`，右键选择 `调试测试` 即可

比如你要调试我的 `postcss` 插件，你就可以引用我的相关代码，在 `test` 文件里写一个用例：

比如 `console.log` 一下 `postcss([plugin]).process(rawSource).css` 结果 ，然后在我的 `postcss` 源代码里面打上断点，这时候再去进行 `调试` 操作，就能命中源码里面的断点了。

调试 `webpack`/`vite` 等等插件同理，你需要准备 `webpack`/`vite` 对应的配置,比如 `webpack/vite` 的 `api` 去引入插件，来进行构建，这样才能命中插件里的断点。

## 源码映射调试

这里的核心是 `sourcemap`，你需要在本地构建的时候，把 `sourcemap` 打出来，然后把所有产物被对应的 `app` 应用（`uni-app`/`taro`）引入并注册

这样你在使用 `javascript` 调试终端，进行运行的时候，就能命中 `dist` 产物里的 `js`，然后再根据 `sourcemap` 命中到你的 `ts` 源码里去了。

当然，假如你生成的 `sourcemap` 不对，或者不生成，你也可以直接在 `dist` 产物里的 `js` 直接打断点进行调试，不过这需要你对源代码比较了解。

当然，每次都使用 `javascript` 调试终端太过于麻烦，为此我准备了 `.vscode/launch.json` 文件，帮助我们快速进行框架产物调试，这样才能获取第一手的 `uni-app` / `taro` 产物。

---

## 小程序 `icon` 解决方案


这里介绍一种在小程序里，开箱即用的 icon 解决方案：[`iconify`](https://iconify.design/)

很高兴，我们已经有这样的能力，为小程序提供大量的 `icon`, 供我们开发者自己进行选择。

## 立即开始

首先，在已经安装和配置完本插件之后，安装 [`@egoist/tailwindcss-icons`](https://www.npmjs.com/package/@egoist/tailwindcss-icons)

```sh npm2yarn
npm i -D @egoist/tailwindcss-icons
```

:::tip
**Iconify for Tailwind CSS** 其实给我们提供了两种选择：
`@iconify/tailwind` 和 `@egoist/tailwindcss-icons`

个人用下来，感觉 `@egoist/tailwindcss-icons` 更好用一点，智能提示也更好一些。

因为它是直接把全部的 `icon` 生成在 `components` 里, 然后再交给 `Tailwind CSS` 从里面进行挑选再输出到我们的 `css` 文件中的。

而 `@iconify/tailwind` 走的是 `jit` 动态加载生成，但是没有智能提示加 `` 不好用啊，笑～。

详见 <https://iconify.design/docs/usage/css/tailwind/>
:::

然后在 `tailwind.config.js` 注册插件:

```js
const { iconsPlugin, getIconCollections } = require("@egoist/tailwindcss-icons")

module.exports = {
  plugins: [
    iconsPlugin({
      // Select the icon collections you want to use
      collections: getIconCollections(["mdi", "lucide"]),
    }),
  ],
}
```

然后你还要安装你挑选的 `icon` 集合包，比如你选择了 `"mdi"` 和 `"lucide"`

那你就要安装: `@iconify-json/mdi` 和 `@iconify-json/lucide` (包名的规则就是：`@iconify-json/{collection_name}`)

当然你也可以直接安装 `@iconify/json`，这里面包含了所有的 `icon`,不过代价就是，这个包比较大（50MB+）

然后你回到你的页面，输入 `i-` 智能提示就出来了，然后就可以这么写了：

`<view class="i-mdi-home text-3xl text-red-600"></view>`

> 假如不起作用，`Tailwindcss@3` 的话，请检查你的 `@tailwind components;` / `@import 'tailwindcss/components';`(scss) 是否在入口 `css/scss` 中引入

## Tailwindcss v4

在 `Tailwindcss@4` 中，不会自动读取 `tailwind.config.js` 文件，所以你需要使用 [@config](https://tailwindcss.com/docs/functions-and-directives#config-directive) 指令，手动 引入 `tailwindcss` 的配置文件。

```css
@import "weapp-tailwindcss";
/* 添加下面这一行，路径为你创建的 tailwind.config.js 文件路径 */
/* highlight-next-line */
@config "../tailwind.config.js";
```

这样在 `tailwindcss@4` 中才能起效果

## icon预览挑选网站

https://icon-sets.iconify.design/

<https://icones.js.org>

## 生成结果

我们以 `i-mdi-home` 这个类的`css` 生成结果为例：

```css
.i-mdi-home{
  display: inline-block;
  width: 1em;
  height: 1em;
  background-color: currentColor;
  -webkit-mask-image: var(--svg);
  mask-image: var(--svg);
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-size: 100% 100%;
  mask-size: 100% 100%;
  --svg: url("data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27 viewBox=%270 0 24 24%27 width=%2724%27 height=%2724%27%3E%3Cpath fill=%27black%27 d=%27M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5Z%27/%3E%3C/svg%3E");
}
```

是的，它是通过 `css var` 的方式，把 `svg` 给内联了（`inline`）了进来，然后通过 `mask-image` 来把图形给显示出来的。 显然，这用多了 `icon` 之后会造成生成的 `css` 体积大的问题。

对此还有 `mask-image` 和 `css var` 在部分机器上不兼容的问题。

对此有解决方案吗？显然是有的，比如我们可以把它做成一个 `webfont`，更改每一个 `icon component class`，把里面换成字体，达到类似 `iconfont` 的效果，最后再生成一份 `ttf/woff` 等文件上传到自己的 `cdn`去，然后这里再引用即可。

这样小程序体积又小，兼容性也好，就是多了些网络请求罢了,我们自己取舍吧。

---

## 💨跨多端开发CSS兼容


## 何时开启插件

本插件主要作用于小程序环境，让开发者可以在小程序环境下可以使用 `tailwindcss` 的特性

然而在 `h5` 和 `app` 中，它们本来就是 `tailwindcss` 支持的环境，所以是没有必要开启本插件的。

所以你可以这样传入 `disabled` 选项。

### uni-app 示例

比如 `uni-app`:

```js title="vite.config.[jt]s"
const isH5 = process.env.UNI_PLATFORM === "h5";
// uni-app v2
// const isApp = process.env.UNI_PLATFORM === "app-plus";
// uni-app v3
const isApp = process.env.UNI_PLATFORM === "app";
// 只在小程序平台开启 weapp-tailwindcss 插件
// highlight-next-line
const WeappTailwindcssDisabled = isH5 || isApp;

const vitePlugins = [
  uni(),
  uvwt({
    // highlight-next-line
    disabled: WeappTailwindcssDisabled
  })
];
```

### Taro 示例

```js title="config/index.ts"
const isH5 = process.env.TARO_ENV === "h5";
const isApp = process.env.TARO_ENV === "rn";
// highlight-next-line
const WeappTailwindcssDisabled = isH5 || isApp;

webpackChain(chain) {
  chain.merge({
    plugin: {
      install: {
        plugin: UnifiedWebpackPluginV5,
        args: [
          {
            // highlight-next-line
            disabled: WeappTailwindcssDisabled,
            rem2rpx: true
          }
        ]
      }
    }
  });
},
```

其他的框架，请自行在对应的文档中，发掘不同目标平台的环境变量判断方式。

## uni-app 打包到 h5 svg icon 偏移问题

这是由于 `tailwindcss` 默认会把 `svg` 的 `display` 设置成 `block` 导致的，所以解决方案很简单

在你的全局样式，引入 `tailwindcss` 的地方下面加一行，进行样式覆盖:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
/*  #ifdef  H5  */
svg {
  display: initial;
}
/*  #endif  */
```

## uni-app 打包安卓 `rgb()` 颜色失效问题

这是由于 `uni-app` 打包成安卓中 `webview` 内核版本较低，无法兼容 `rgb(245 247 255 / var(--tw-bg-opacity))` 这样的 `css` 写法导致的

这时候我们需要把这个写法，转换为兼容写法: `rgba(245, 247, 255, var(--tw-bg-opacity))`，具体解决方案:

### 安装 `postcss-preset-env`

```bash npm2yarn
npm i -D postcss-preset-env
```

### 设置 `postcss.config.js`

```js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
    'postcss-preset-env': {
      browsers: 'chrome >= 50', // configure a compatible browser version
    },
  },
};
```

这样，所有的 `rgb` 和 `/` 写法就被转化成兼容写法了。

相关issue详见:<https://github.com/tailwindlabs/tailwindcss/issues/7618#issuecomment-1140693288>

## CSS变量计算模式

在 `tailwindcss@4` 下，默认启用 CSS 变量计算模式。`tailwindcss@3` 默认不启用。

此模式下会去预编译所有的 `css` 变量和 `calc` 计算表达式。

比如 `tailwindcss@4` 下原先生成的样式为:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: calc(var(--spacing) * 2);
}
```

在CSS变量计算模式启动，进行预编译之后，现在的结果为:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
 height: calc(var(--spacing) * 2);
}
```

这个模式可以解决很多手机机型 `calc` `rpx` 单位的兼容问题。\
当处于 Tailwind CSS 模式（`tailwindcss@4` 及以上）时，插件会默认把 `--spacing` 注入到 `includeCustomProperties`，因此常见的 `space-x`/`space-y` 等工具类会被稳定计算。

> 可通过给插件，传入 `cssCalc` 配置项 `false` 来手动关闭这个功能

假如这时候你需要去除 CSS 变量的声明，你可以传入

```js
{
  cssCalc: ['--spacing']
}
// 或者更精确的
{
  cssCalc: {
    includeCustomProperties: ['--spacing']
  }
}
```

> 你也可以传入正则表达式

这样生成的结果就是:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
}
```

通过这种方式可以解决手机机型 `calc` `rpx` 单位的兼容问题

详见: https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#csscalc

### `includeCustomProperties` 进阶用法

`cssCalc` 提供多种写法来控制需要参与计算的自定义属性。下面结合「执行前 / 执行后」的示例说明差异。

**数组写法**

```ts
cssCalc: ['--spacing', '--gap']
```

- 执行前：

  ```css
  :root {
    --gap: 6rpx;
    --spacing: 8rpx;
  }
  .space-x-2>view+view {
    margin-left: calc(var(--gap) * (1 - var(--tw-space-x-reverse)));
    margin-right: calc(var(--spacing) * var(--tw-space-x-reverse));
  }
  ```

- 执行后：

  ```css
  .space-x-2>view+view {
    margin-left: 6rpx;
    margin-right: 8rpx;
  }
  ```

**对象写法**

```ts
cssCalc: {
  includeCustomProperties: ['--gap'],
  precision: 6,
  preserve: true,
}
```

- 执行前：

  ```css
  :root {
    --gap: 12rpx;
  }
  .btn {
    margin-bottom: calc(var(--gap) * 2);
  }
  ```

- 执行后：

  ```css
  :root {
    --gap: 12rpx;
  }
  .btn {
    margin-bottom: 24rpx;
    margin-bottom: calc(var(--gap) * 2);
  }
  ```

**正则写法**

```ts
cssCalc: [/^--(gap|spacing)$/]
```

- 执行前：

  ```css
  :root {
    --gap: 4rpx;
    --spacing: 10rpx;
  }
  .card + .card {
    margin-top: calc(var(--spacing) * 2);
    margin-left: calc(var(--gap) * 3);
  }
  ```

- 执行后：

  ```css
  .card + .card {
    margin-top: 20rpx;
    margin-top: calc(var(--spacing) * 2);
    margin-left: 12rpx;
    margin-left: calc(var(--gap) * 3);
  }
  ```

**Tailwind 统一变量写法**

```ts
cssCalc: {
  includeCustomProperties: [/^--tw-/],
  preserve: true,
}
```

- 执行前：

  ```css
  :root {
    --tw-space-y-reverse: 0;
    --tw-gradient-from: #38bdf8;
    --tw-gradient-stops: var(--tw-gradient-from), rgba(56,189,248,0);
  }
  .space-y-3>view+view {
    margin-top: calc(var(--spacing) * 3 * (1 - var(--tw-space-y-reverse)));
  }
  .from-sky-400 {
    background-image: linear-gradient(to right, var(--tw-gradient-stops));
  }
  ```

- 执行后：

  ```css
  :root {
    --tw-space-y-reverse: 0;
    --tw-gradient-from: #38bdf8;
    --tw-gradient-stops: var(--tw-gradient-from), rgba(56,189,248,0);
  }
  .space-y-3>view+view {
    margin-top: 24rpx;
    margin-top: calc(var(--spacing) * 3 * (1 - var(--tw-space-y-reverse)));
  }
  .from-sky-400 {
    background-image: linear-gradient(to right, var(--tw-gradient-stops));
  }
  ```

以上示例可以自由组合使用，帮助你根据业务场景精确控制 `calc` 与自定义属性的计算范围。

---

## tailwindcss in weapp 的原理

## 2024-02-20 版本

## 前言

转眼又是一年，感觉是时候再来修订一下 `tailwindcss in weapp 的原理` 这篇文章了, 放心，这次我写作核心就是要让大多数人看懂！

## 什么是 weapp-tailwindcss

如果下一个定义的话，我把 `weapp-tailwindcss` 定义成一个 **转义器**，在我看来它就做了一件事情。那就是把 `tailwindcss` 中，小程序不兼容的写法，转化成小程序兼容的写法，并尽量保持生成的 `CSS` 效果一致罢了。

更加细一点的解释，就是允许开发者像 `tailwindcss` `h5` 环境里那样去写小程序，插件在背后帮助你把 `wxml`,`js`,`wxss` 等等这类产物的小程序兼容转化给做了。

仅仅如此罢了，做了一点小小的努力和贡献。

## 为什么需要 weapp-tailwindcss ？

因为小程序 `wxml`,`wxss` 等等文件/产物，本身是不支持 `Tailwindcss` 里面的一些特殊转义字符的，比如像 `[]`,`!`,`.` 等等。

经过测试后，`wxml` 中 `class` 属性，实际上只支持英文字母，数字，以及 `-` 和 `_` 这 `2` 个特殊字符，不支持的字符会被默认转化成**空格**，所以我们要做的就是把 `Tailwindcss` 选择器的写法，转化成小程序允许的方式。这也是核心包 [`@weapp-core/escape`](https://github.com/sonofmagic/weapp-core) 实现的功能。

插件大体的发展历程和方向，可以看下方以前的 `2023-03-19` 版本，在此不再叙述，接下来我们只来谈谈核心原理。

## 核心原理

插件的核心就是转义，那么具体是怎么做的呢？

实际上就是插件去解析编译后的 `wxml`,`js`,`wxss` 这些产物，并对它们进行改写。

工具方面， `weapp-tailwindcss` 使用 `htmlparser2` 去解析改造 `wxml`，使用 `babel` 去解析改造 `js` 和 `wxs`，使用 `postcss` 去解析改造所有的 `wxss`。

## `wxml`

### 为什么是 `htmlparser2`

其实，`weapp-tailwindcss` 一开始使用的是 `@vivaxy/wxml`，这是一个 `wxml` 的 `ast` 工具，

但是它已经很久没有更新了，在很多场景，比如遇到内联的 `wxs` 的时候，会直接挂掉，而本身我也没有技术能力，去修复和完善这个 `wxml` 自动机，所以后续放弃了它。后来自己实现了一套基于正则的模板匹配引擎，但是再使用一段时间后，发现 `正则` 同样是有问题的，比如这样一个 `case`:

`<view class="{{2>1?'xxx':'yyy'}}"></view>`

由于 `2>1`的存在，它会与 `<view class="{{2>` 进行提前匹配并返回，这和我们的期望不符合，而且正则复杂了之后，其实匹配效率也是很低的 (具体可以在 [regex101](https://regex101.com/) 进行测试和调试)，所以还是要使用 `ast` 工具才能做到兼顾效率的同时，做精确匹配转化。

所有，我还是要去寻找对应的 `xml/html ast` 工具来解析 `wxml`。在寻找的过程中，找到了符合条件的一些包，其中 `parse5` 对 `html5` 是严格的匹配，不怎么适用于 `wxml`，而 `htmlparser2` 是不严格标签匹配，所以经过测试之后，最后使用 `htmlparser2` 来处理 `wxml`。

### 如何使用 `htmlparser2`

实际上很简单，我们可以在 `webpack` / `vite` / `gulp` 或者自己的构建脚本中，找到对应的生命周期 (`hooks`)，对 `wxml` 产物进行处理。

首先在获取到 `wxml` 产物的内容之后，把它构造成一个 `MagicString` 对象，因为 `magic-string` 这个库，操作字符串十分方便。

对产物内容字符串进行解析后，获取到所有 `class` 属性的内容，进行转义即可。代码示例如下:

```js

const parser = new htmlparser2.Parser({
    onopentag(name, attributes) {
      // code
    },
    onclosetag(tagname) {
      // code
    },
    // ....
});
parser.write(wxmlCode);
parser.end();
```

### 字符串以及变量绑定的处理

不过在获取到 `class` / `hover-class` 这些标签里面的内容之后，需要进行进一步解析和转化。

为什么？因为原生小程序可以使用 `{{expression}}` 表达式来动态绑定 `js` 的值，假设有一段 `wxml` 是这样写的:

```html
<view class="w-[13px] {{flag?'h-[23px]':'h-[6px]'}} bg-[#123456] {{customClass}}"></view>
```

这时候你就必须在匹配 `class` 属性值的情况下，对字符串进行转义，再对 `{{}}` 里包裹的 `js` 表达式，进行转义，使得结果变成:

```html
<view class="w-_13px_ {{flag?'h-_23px_':'h-_6px_'}} bg-_#123456_ {{customClass}}"></view>
```

那么怎么做呢？也很简单，我们通过 `htmlparser2` 匹配 `class` 属性，可以获取到 `w-[13px] {{flag?'h-[23px]':'h-[6px]'}} bg-[#123456] {{customClass}}` 这个字符串。

然后对这个字符串进行 `{{}}` 表达式匹配，在 `{{}}` 表达式匹配之外的字符串，直接进行转义。在 `{{}}` 表达式内的代码，使用 `babel` 进行解析，然后获取到所有的 `js` 字符串字面量，进行转义即可。

同时在进行匹配和转义的时候，实际上我们是可以获取到对应字符串 `start` 和 `end` 的下标的，这就为我们使用 `MagicString` 进行替换，提供了良好的基础。

## js / wxs

我们同样要对所有的 `js` 里面的字符串，进行扫描，发现它是 `tailwindcss` 的类名，就需要进行转义。

我们还是以上方的代码片段为例:

```html
<view class="w-[13px] {{flag?'h-[23px]':'h-[6px]'}} bg-[#123456] {{customClass}}"></view>
```

在 `wxml` 的处理过程中，看似我们已经解决了大部分 `class` 内容的转义的，但是开发者也可能在 `customClass` 绑定的 `js` 字符串中，直接去编写 `tailwindcss` 的类名。比如:

```js
Page({
  data: {
    customClass: "bg-[url('https://xxx.com/xx.webp')] text-[#123456] text-[50px] bg-[#fff]",
  },
})
```

又或者直接在 `wxs` 里面去写类名，那么这时候怎么办呢？获取所有字符串字面量和模板字符串，进行转义即可吗？

显然这是不行的，一个应用程序里面，大部分的字符串字面量都是和 `tailwindcss` 无关的，假如全部转化只会把应用程序弄奔溃。

那么，我们是否有什么方式，去获取到 `tailwindcss` 的上下文，再从里面把它所有的类名提取出来，再和我们应用程序里面的字符串进行匹配，从而做到精确转义呢？可是 `tailwindcss` 只是一个 `postcss` 插件啊，怎么从 `webpack` / `vite` 插件里，把一个 `postcss` 插件里的内容取出来呢？

通过这种方式，我们可以在 `postcss` / `postcss-loader` 执行之后，把 `tailwindcss` 执行时的 1 或者多个上下文给取出来，交给插件进行使用，从而达到所有 `js` 字符串字面量筛选的效果，简单实用 `babel` 实现的代码如下:

```js
let ast: ParseResult<File> = parse(rawSource, {
    sourceType: 'unambiguous'
})
const ms = new MagicString(rawSource)

const ropt: TraverseOptions<Node> = {
  StringLiteral: {
    enter(p) {
      // set 为 tailwindcss 上下文里所有生效的 classnames
      if(set.has(p.node.value)){
        // do escape
        const value = escape(p.node.value)
        ms.update(start, end, value)
      }
    },
  },
}

traverse(ast, ropt)

const code = ms.toString()
```

通过这种方式来精确的把 `js` / `wxs` 里面字符串字面量，给转义成小程序允许的方式。

这里我们使用 `babel` 作为 `js ast` 的工具，因为目前为止它也是最流行的这方面的包，但是出于效率上的考虑，未来将会使用 `swc` 并编写 `swc` 插件的方式，来取代 `babel`。

## wxss

最后就是样式的处理了，在转义完 `wxml`,`js` 和 `wxs` 后，我们需要把 `wxss` 里 `tailwindcss` 生成的样式，转化成与之前的 `wxml`,`js`,`wxs` 中匹配的方式。这样才能做到类名的 11 对应，从而达到我们最终的目的。

那么怎么做呢？这里我们选用的工具，自然是 `postcss`，它是目前用 `js` 编写的最流行的一个 `css ast` 工具，它要比 `css-tree` 生态好很多，也有很多现成的稳定插件可以使用，帮助我们完成针对 `css` 各种各样的处理。

所以最后我们所要完成的工作，就是把 `tailwindcss` 的产物，转化成与 `wxml`,`js` 和 `wxs` 匹配，且小程序能够适配的样子了！

怎么做？也很简单，直接使用 `postcss` 扫描 `wxss` 里面所有的 `Rule` 节点，然后获取到里面的选择器，进行转义即可！

### postcss 对象简单介绍

什么是 `Rule` 节点？在 `postcss` 插件中，大致有这 `5` 类对象(其实还有一个 `Document` ):

- `Root`: CSS tree 的根结点，通常可以代表整个 CSS 文件.
- `AtRule`: 以 `@` 开始的 CSS 语句，比如 `@charset "UTF-8"` 或者 `@media (screen) {}`.
- `Rule`: 普通的选择器节点，内部由 CSS 声明填充，比如 `.btn { /*decls*/ }`.
- `Declaration`: key-value 键值对，代表 CSS 声明，比如 `color: black`;
- `Comment`: CSS 注释.

详见 [writing-a-postcss-plugin](https://postcss.org/docs/writing-a-postcss-plugin#step-find-nodes)

通过这些对象，`postcss` 完成了对 `CSS` 的抽象，从而让我们可以通过操作这些对象来对 `CSS` 进行增删改查。

### Tailwindcss 简单原理和运行表现

在转化所有的 `Rule` 节点之前，我们先分析一下 `Tailwindcss` 的原理，它也是一个 `postcss` 插件，它通过提取 `content` 配置里面的 `glob` 表达式 or `vfile` 对象，从里面提取到符合它规则的字符串，然后生成大量的 `AtRule` / `Rule` 对象保存起来。

然后再扫描到我们注册 `Tailwindcss` 的地方:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

把这些对象进行展开，替换掉原先的 `@tailwind xxx;`，从而达到了写什么， `CSS` 就自动生成什么的效果。

其中你可以把 `base` / `components` / `utilities` 理解成一个个 `layer` 标志位，不同的 `AtRule` / `Rule` 对象集合，会在它对应的 `layer` 出展开。比如 `base` 负责所有的 `css vars` 和 `preflight css` 注入，`utilities` 负责所有原子工具类的生成。

同时它们再通过 `@layer` 来控制它们的优先级，从而做到它们之间的 `CSS` 不会产生优先级相互覆盖冲突的问题。

> `@layer` 实际上是原生 `CSS` 的一个实验性功能，用来声明一个 级联层,从而让开发者更容易的控制自己 CSS 代码的优先级罢了。这里我们能使用 `@layer` 是因为这个功能被 `tailwindcss` 用它自己的方式实现了，使得我们可以在 `CSS` 里预先使用 `@layer` 罢了，最终产物里面是没有 `@layer` 的。相关文档详见 [MDN @layer](https://developer.mozilla.org/zh-CN/docs/Web/CSS/@layer)

### 开始转化

首先我们先简单声明一个 `postcss` 插件:

```ts

const creator: PluginCreator<Options> = () => {
  return {
    postcssPlugin,
    Rule(rule) {
      ruleTransformSync(rule, options)
    },
  }
}

creator.postcss = true
```

这里我们把针对 `Rule` 的转化，封装进 `ruleTransformSync` 这个方法里:

这里我们需要用到 `postcss-selector-parser` 来对 `Rule` 中的选择器，做更加细致的转化。

因为 `postcss` 中的 `Rule` 对象的选择器千变万化，可以非常的简单，也可以非常的复杂，你单独把它当作字符串来处理，很容易出现问题。

所以我们需要 `postcss-selector-parser` 来解析 `Rule#selector` 然后进行修改再转化回字符串。

例如:

```ts

export const ruleTransformSync = (rule: Rule, options: IStyleHandlerOptions) => {
  const transformer = selectorParser((selectors) => {
    selectors.walk((selector) => {
      // do something with the selector
    })
  })

  return transformer.transformSync(rule, {
    lossless: false,
    updateSelector: true
  })
}
```

我们通过对 `selectors` 的 `walk`，再方法里面去筛选和修改节点，从而达到我们替换和转义 `Rule#selector` 的效果。

这样就可以去转义所有的 `Tailwindcss` 生成的所有节点了！

## 大功告成

最终在这 3 大部分完成之后，`weapp-tailwindcss` 的核心功能就完成了！

---

## 2023-03-19 版本

(2023-03-19) 版本，现在看了一下，已经比较老了，有空再改进改进。

## 前言

笔者对 `tailwindcss` 这一类库的理解还算比较深刻。之前就已经撰写并发布过相关的许多包，比如像 [`tailwindcss-miniprogram-preset`](https://github.com/sonofmagic/tailwindcss-miniprogram-preset), [`weapp-tailwindcss-webpack-plugin`][weapp-link] [等等大堆的包](https://github.com/sonofmagic?tab=repositories&q=tailwindcss&type=&language=&sort=)。

最近我发布了 [`weapp-tailwindcss-webpack-plugin`][weapp-link] 的 `2.0.0`版本，增加了一些核心特性。想着现在也是时候，回顾总结一下这个插件的原理和历程了。回首`npm`版本发布历史，看到当年发布的第一个正式版，还是在 `2022/2/3` 号，到现在也已经过去了`1`年多的时间了，想想岁月真是如白驹过隙，等着等着我们就老了。

## 这个插件是做什么的？

简单概括一下，就是把 `tailwindcss` 相关的特性，带入进小程序开发中。

为什么需要它呢？核心原因就是，小程序这个平台不像`h5`那么自由，有很多各式各样的束缚与非标准化的 `API`。我们以微信小程序为例：

同`css`相比，`wxss`有着更少的选择器支持，同`wxml`相比，`wxml`有着更少的字符集支持，`js` 和 `wxs` 的运行也是分离的(`wxs`语法像是一个低版本`js`)。

更不用说那些该有的全局对象一个都没有了，比如 `Blob`,`File`,`FormData`, `WebSocket`,`fetch`,`XmlHttpRequest`等等了，这导致许多浏览器包，安装下来无法运行。

> 举个例子，最近我在做服务端 graphql 改造，市面上主流的 `graphql client` 直接安装运行会立即报错，因为缺少全局对象，为了兼容它们，于是就写了 [`weapp-websocket`](https://www.npmjs.com/package/weapp-websocket) 和 [`weapp-fetch`](https://www.npmjs.com/package/weapp-graphql-request) 分别来实现 `subscriptions` 和 `query/mutation`。目前在项目里使用，运转良好。

总的来说，由于缺少许多特定的对象和语法上的限制，一些在 `h5` 上通用的流行库，很有可能在小程序里跑不起来。`tailwindcss` 便是其中之一，而这个插件就能帮助你在小程序里使用它。

## 原理篇

### utility-first CSS framework

其实吧，市面上的 `tailwindcss`/`windicss`/`unocss` 做的是一回事情。如果用比喻来形容，那么它们就是个带着滤网的字符串漏斗。它们对开发者编写的代码文件内容进行读取，并分割成海量的字符串放入漏斗中，然后经过滤网的过滤，符合条件的就去生成原子类，其余的"残渣"则忽略。

其中 `tailwindcss` 大多作为 `postcss plugin` 来使用的，它源码里自己实现了一个文件读取机制(也就是 `tailwind.config.js` 中的 `content` 配置项 )，来对我们编写的代码进行提取。

而 `windicss`/`unocss` 则是依赖 `webpack/rollup/vite` 这类的 `bundler`，在打包的过程中获取到 `Source / Asset / Chunk` 这类的对象，从而提取字符串的。虽然目前 `windicss`/`unocss` 都有对应的 `postcss plugin` 的实现，但是它们大多都是作为实验性质的，并不能很好的复刻它们打包插件的体验。

是什么造成了它们的不同呢？

这点其实就要说到 `unocss/windicss` 它们的优点了。目前 `tailwindcss postcss plugin` 实际上只有**读**的能力，它来读取我们写的代码，生成原子类。而 `windicss`/`unocss` 它们大多作为一个 `webpack/vite/rollup plugin` 来使用的，所以它们不但拥有读的能力，还拥有**修改**的能力。所以它们能写出这样的代码:

```html
<button
  bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
  text="sm white"
  font="mono light"
  p="y-2 x-4"
  border="2 rounded blue-200"
>
  Button
</button>

```

实际上就是在打包的插件内，展开覆写罢了，本质上还是个语法糖。

另外目前你选择这种原子类框架的时候，要不选择 `tailwindcss` 要不就 `unocss`，目前看起来 `windicss` 已经死了。

### 小程序兼容

上面说了这么多，接下来来聊聊它们对小程序的兼容，事实上，市面这么多转义的插件，预设啥的，都是一回事。

思路大多就是把这些原子类`css`框架，生成的 `class` 通过重命名，转义，再覆写的方式，去兼容小程序环境。

说的具体一些，就是对打包后的产物进行修改，把其中的 `wxml` 里开发者撰写的 `className` 进行转义，把 `js` 里写的要应用到 `dom` 节点上的 `className` 也进行转义，同时还要对 `wxss` 里生成的 `css` 选择器进行转义。

而这些核心中的核心，便是转义后类名和选择器，一定要相互匹配！！不然生成的结果就是完全错误的。

## 笔者的实现

前面说了这么多，接下来来讲讲我自己的实现。

实际上我一开始的实现也很简单，在第一版本初期，我选择写了这样一个 `webpack plugin`：

1. 它内部用 `wxml ast` 来解析所有的 `wxml`模板,以此来获取所有的 `className` 进行解析和替换
2. 使用 `postcss` 来解析所有的 `wxss`，以此对所有的`css`选择器进行修改
3. 使用 `babel` 来解析所有的 `js`/`jsx`，以此来动态修改 `jsx?` 里所以满足条件的字面量 (`StringLiteral`)。

然而理想很丰满，现实很骨感，在实现的过程中，困难一个一个浮现出来了：

### js里的字面量转义很容易误伤

一开始想着直接匹配并且替换掉符合要求的 `js` 的字面量，于是便兴致勃勃从 `tailwindcss` 源码里，拷贝来了解析提取器的正则，并在打包后进行匹配和替换。

然而这个方案失败了，原因是`tailwindcss`这个正则匹配有可能会把 `webpack` 它默认注入的一些`js code`的一些字面量，也给匹配进来，从而造成大面积误伤。这种误伤会导致 `js` 加载的失败，应用直接就挂了。所以暂时把 `js`字面量动态修改给去除掉了。同时导出了一个手动标记替换位置的方法：

```js

const cardsColor = reactive([
  replaceJs('bg-[#4268EA] shadow-indigo-100'),
  replaceJs('bg-[#123456] shadow-blue-100')
])
```

这样虽然解决了误伤的问题，但是带来了一些代码的入侵性，导致了开发体验不佳。不过这个问题在 `2.0.0` 解决了，请继续往下看。

### 多框架兼容

> 源码 `framework` 部分

正如你看到的，我的这个 `plugin` 是兼容市面上，几乎所有还活着的主流开发框架的。在开始设计兼容方案的过程中，我发现这些框架编译成小程序的产物各有不同，一类是以 `uni-app`/`mpx`/`native(原生)`为例，它们就是按部就班的把类 `vue` 模板的写法，转义成小程序模板写法。另外一类是以 `taro`，`rax`，`remax` 为代表的 `jsx` 写法，这种写法的产物，最大的特点就是页面与组件的 `wxml` 里往往都是这样的结构：

```html
<import src="../../base.wxml"/>
<template is="taro_tmpl" data="{{root:root}}" />
```

而 `base.wxml` 文件内则是大量的条件渲染语句，然后在 `js` 里生成一个对象传入其中，就把整个页面和逻辑渲染出来了。这个方案显然会比模板方案要灵活许多。个人总结，一种偏静态编译，一种偏动态。

所以开始写的时候插件也分成了 `2` 个版本，一个是 `TemplatePlugin` 专门用来处理偏静态的这种框架，一个是 `JsxPlugin` 负责动态的方案。这 `2` 种插件的侧重点不同，一个主要替换模板代码，一个则主要转义 `jsx`，就开发难度来说 `jsx` 插件要难上许多。

#### 模板插件

> 源码 `base/BaseTemplatePlugin` 和 `wxml` 部分

模板那个插件，要做的是解析所有的 `dom` 的 `class` 属性，但是这个属性里很有可能会存在 `js`表达式(`{{}}`包裹的部分)。

如果是不带表达式的，可以直接转义覆写，带表达式的会稍微复杂一点，我需要去预估开发者所使用的语法，比如开发者经常会使用一些数组绑定的语法，或者多元条件运算符，例如 `x?y:z?a:b` 来撰写类名。这就代表着我们需要像解析 `js` 那样去解析 `{{}}` 内部包着的表达式，再通过语法的检测去进行替换。

比如 `x?y:z?a:b` 派生的 `{{ flag ? 'bg-[#123456]' : otherFlag ? 'text-[50px]' : 'text-[#654321]' }}` 我们就需要匹配 `3` 个字面量进行转义。

#### jsx插件

> 源码 `base/BaseJsxPlugin` 和 `jsx` 部分

这个插件的开发难度更高，因为我发现就单单 `taro` 一个框架，它就支持 `react`/ `preact`/ `vue2` / `vue3` 这些框架，要命的是，`react`/`vue2`/`vue3` 它们构建出来的产物，有很大的不同。

> 这点你可以通过我 `src/jsx` 目录下的源码，和相应的`jest`单元测试快照，查看它们的差别。

所以我在配置项里，除了原先的 `appType`(框架) 之外又加了一个 `framework` 专门提供给 `taro`，通过传入 `react/vue2/vue3` 让它们走各自不同的 `jsx?` 替换策略。

当然这样远远没有解决问题，毕竟原先插件是在 `processAssets` 这个`hook`去执行的核心逻辑，相比较来说还是偏晚的，还可能有误伤的问题存在。为此我做了一些努力：

1. 在替换字面量时，只匹配 `react/vue2/vue3`的`return`模板部分代码，放弃函数作用域内字面量的匹配和替换。
2. 为了让这个转义替换的范围足够的精确，就必须要尽可能的提前执行。于是基于这个思路，我想到了在插件里，动态去插入一个自己的 `webpack-loader`:`jsx-rename-loader` (见源码 `src/loader` )

这个 `loader` 会被动态的插入 `jsx?` 文件的加载读取序列中，并确保它在队列的最先执行，即 `babel-loader` 或 `ts-loader` 之前。这样在这个`loader`内部执行转义的时候，得到的原始内容就非常贴近用户自己编写的代码了。

#### webpack4/5 和 vite 的兼容

> 源码 `base` -> `v4/v5` 部分

这一块也是由于各个框架，使用的 `webpack` / `postcss` 版本不同导致的。

不过要达成这个目标还是比较简单的，看看`webpack`文档就可以了，而 `rollup/vite` 这种，它们本身的 `API` 就要比 `webpack` 简单，实现起来也非常简单。

具体举一些例子便是:

```js
// webpack5 动态插入 loader

NormalModule.getCompilationHooks(compilation).loader.(pluginName, (loaderContext, module) => {})
// webpack4
compilation.hooks.normalModuleLoader.tap(pluginName, (loaderContext, module) => {})

// webpack5
compilation.hooks.processAssets
// webpack4
compilation.hooks.optimizeChunkAssets

// webpack5
const Compilation = compiler.webpack.Compilation
const { ConcatSource } = compiler.webpack.sources
// webpack4

// 还有 `loader-utils` 的版本问题

// 还有 Compilation 封闭后 assets 对象不可修改问题等等等等
```

这种问题只要愿意多调试，都能解决。

### css 选择器替换

> 源码 `postcss` 部分

这部分是 `postcss` 的主场，我们知道 `postcss` 本质上就是一个 `css ast` 工具。有了 `ast` 才有了各种各样的转化插件来生成 `css`。

现在我们使用它的核心目标为：找到所有 `tailwindcss` 的生成块，对选择器进行转义。

我们先来解决第一个问题: 怎么找？

#### 找到tailwindcss节点

> 源码 `postcss/mp` 部分

各个框架，它们公共样式文件的路径不同的。比如 `uni-app` 的路径就是 `common/main.wxss`，`taro` 则为 `app.wxss` ，而某些框架更加的奇葩，`common/miniprogram-app.wxss` 等等，这简直就是简直了。

所以我们可以通过用户传入的 `appType` 这个框架类型，以此来精确定位公共样式的位置。不过这个方案后续还经过了许多的优化，核心便是利用 `postcss` 解析，对 `tailwindcss` 所在的文件位置，进行猜测。

这个猜测的方案是由于 `tailwindcss` 的特性实现的。因为 `tailwindcss` 它在生成原子类之前，它会先去注入大量的 `css` 变量，以此来控制所有的原子类的呈现。

所以我们会看到这样一个 `css` 节点

```css
*,:after,:before{
  --tw-border-spacing-x: 0;
  --tw-border-spacing-y: 0;
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-rotate: 0;
  /* ..... */
}
```

那么我们就可以认为，找到它，这个文件就是公共样式的所在之处了。不过在寻址时要注意选择器条件和 `-tw-` 变量条件，以此做到精确匹配。

#### 转义原子类选择器

> 源码 `postcss/selectorParser` 和 `shared` 部分

第一个问题解决了，第二个问题接踵而至，怎么换？

直接对所有的选择器进行转义可行吗？显然是不可行的，这只会导致 `css` 的大面积误伤。

我们知道一个`css`选择器，可能很简单也可以很复杂，它可以包含相邻兄弟选择器，子选择器，后代选择器，通用兄弟选择器，伪类选择器，伪元素选择器，还能使用 `,` 来添加选择器。我们必须要对选择器进一步解析，从而做到精确匹配和转义。

这时候就需要 `postcss-selector-parser` 出场了。

我们在使用 `postcss` 进行 `root.walk` 之后，再把符合条件的 `css` 节点进行 `selectors.walk`，从而达成了选择器局部精确转义的效果。

另外由于 `tailwindcss` 默认的 `preflight` 是针对 `h5` 的，所以我们也需要注入自己的小程序 `preflight`，还有一点值得注意就是， `js/wxml` 的转义方法和 `wxss` 的转义方法是不同的，因为 `css` 中，往往会多加一个 `\` 字符。

### 模板解析的重新实现

> 源码 `reg` 和 `wxml/utils` 部分

原先用的 `wxml ast` 是第三方的，已经彻底没人维护了，一直出 `bug`(比如`wxml`内联`wxs`)，于是自己基于正则写了一个模板属性提取器。

这是由于日益增长的需求导致的，原先可能想着模板里，只要支持 `class`/ `hover-class` 这类的属性转义就够了。但是后续发现，用户在定义和使用组件的时候，也会经常把 `className` 作为属性传入进组件，这时候就需要我们自定义生成正则，来对满足条件的属性进行转义了。比如:

```html
<my-com class="bg-[#123456]" hover-class="bg-[#654321]" custom-class="text-[#ff00ff]" happy-attr="text-[green]" sad-attr="text-[blue]"></my-com>
```

默认只匹配转义 `2` 个，怎么行呢？所以开放了 `customAttributesEntities` 配置项，这个配置项会和原先 `class`/ `hover-class` 相关的属性一起进行匹配，从而转化上述例子中所有的 `Arbitrary values`。

### 动态源码补丁

> 源码 `tailwindcss` 部分

很多时候，出于 `tailwindcss` 自身的限制，和技术国情等等原因。我们的 `pr` 往往不会被他们接受，这时候我们就需要自己去修改他们的源码，从而封装一个符合中国国情的 `tailwindcss`。这种可以通过 `fork` 一个新的版本进行发布来做到，也可以通过给源码打补丁做到。

> 注意点：给源码打补丁，这个操作一定要是幂等的，不然重复执行可能会破坏源码的结构

#### 支持自定义长度单位(rpx)

> 源码 `tailwindcss/supportCustomUnit` 部分

自从 `tailwindcss 3.2.x` 开始，由于加入了单位分类校验 [issue#110](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/110) 导致原先一些直接在类名里写 `rpx` 的原子类，被错误识别然后被转化成了颜色。

什么意思呢？

比如现在有三个原子类，`text-[#123]`，`text-[30rpx]`，`text-[30px]`，在 `3.2.x` 之前，前一个是字体颜色，后面两个是字体的大小。在这个版本之后，前 **2** 个是颜色，只有最后一个是字体大小了！

这是因为 `tailwindcss` 会对 `mdn` 上合法长度单位进行校验，在合法长度单位列表内，则认为是字体大小，反之则为字体颜色。而 `rpx` 这个单位是微信的独创，不是一个标准的 `css` 单位，自然就在合法长度单位这个集合之外了。

那么如何进行修复支持呢？通过阅读 `tailwindcss` 的源码，会发现它校验单位的方法在 `utils/dataType.js` 这个文件里。

再通过 `babel` 三件套: `parse`，`traverse`,`generate` 可以精确锁定暴露的合法变量列表位置，然后把 `rpx` 这个单位 `push` 进 `ast node.elements`之后，重新生成覆写即可。

## 2.0 增加了什么？

这个版本新增了 `UnifiedWebpackPluginV5`
和 `UnifiedViteWeappTailwindcssPlugin` 这种以 `Unified` 开头的插件。

它们能够自动识别并精确处理所有 `tailwindcss` 的工具类，这意味着它可以同时处理 `wxss`,`wxml` 和 `js` 里静态和动态的 `class`(v1版本只有处理`wxss`,`wxml`静态`class`的能力)。所以你再也不需要在 `js` 里引入并调用 `replaceJs`方法了！由于 `2.x` 插件有精准转化 `js`/`jsx` 的能力，误伤问题得到了有效的解决，也大大提升了 `taro` 这种动态模板框架的开发体验。

欢迎体验，`star`/`fork`。

## 尾言

正如马克·吐温的名言： `To a man with a hammer, everything looks like a nail`。

笔者的方案肯定也会有许多的局限性，本篇文章也不可避免的会出现许多的勘误。

欢迎大佬们指出，也欢迎大家的建议和指点 ^\_^

作者: [ice breaker](https://github.com/sonofmagic)

[weapp-link]: https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin

---

## Related projects


### CLI 工具

[weapp-ide-cli](https://github.com/sonofmagic/utils/tree/main/packages/weapp-ide-cli): 一个微信开发者工具命令行，快速方便的直接启动 ide 进行登录，开发，预览，上传代码等等功能。

### 模板 template

> 目前模板大多还是 `1.x` 的版本，后续我会对模板进行一系列的升级

#### 如何选择？

假如你仅仅是开发一个`小程序` + `h5` 的组合，那么使用 `vscode` 模板就足够了

假如你的项目构建的重点平台是 `app` 那么还是推荐使用 `hbuilderx` 模板，因为 `hbuilderx` 自带了一套 `app` 构建和调试的工具链，可以更好的支持你的开发。

#### 使用`uni-app cli`进行构建 `vscode`开发

[uni-app-vite-vue3-tailwind-vscode-template](https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template)

[uni-app-vue3-tailwind-vscode-template](https://github.com/sonofmagic/uni-app-vue3-tailwind-vscode-template)

[uni-app-vue2-tailwind-vscode-template](https://github.com/sonofmagic/uni-app-vue2-tailwind-vscode-template)

[weapp-native-mina-tailwindcss-template](https://github.com/sonofmagic/weapp-native-mina-tailwindcss-template)

#### 使用`hbuilderx` 进行构建和开发

[uni-app-vue2-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue2-tailwind-hbuilder-template)

[uni-app-vue3-tailwind-hbuilder-template](https://github.com/sonofmagic/uni-app-vue3-tailwind-hbuilder-template)

### tailwindcss plugin

[weapp-tailwindcss-children](https://github.com/sonofmagic/weapp-tailwindcss-children)

### tailwindcss preset

[tailwindcss-miniprogram-preset](https://github.com/sonofmagic/tailwindcss-miniprogram-preset)

---

## 2.x 版本新特性


这个版本新增了 `UnifiedWebpackPluginV5`
和 `UnifiedViteWeappTailwindcssPlugin` 这种 `Unified` 开头的插件。

它们能够自动识别并精确处理所有 `tailwindcss` 的工具类。这意味着它可以同时处理所有文件中的静态或动态的 `class`。

相比`v1`版本只有处理`wxss`,`wxml`静态`class`的能力，使用`v2`版本新的插件，你再也不需要在 `js` 里引入并调用标记方法 `replaceJs`了！`2.x` 插件有精准转化 `js`/`jsx` 的能力，大大提升了 `taro` 这种动态模板框架的开发体验。

## 新插件介绍

`UnifiedWebpackPluginV5` 是一个核心插件，所有使用 `webpack` 进行打包的框架都可以使用它，只需要传入 `appType` 配置项: `uni-app`/`taro`/`rax`/`remax`/`mpx` 等等，如果不传的话，插件会去猜测公共的样式文件位置，并进行转化(有可能不准确)。

目前，这个方案只支持 `tailwindcss v3.2.2` 以上版本和 `webpack5`。同时这个方案依赖 `monkey patch`，所以你应该把

```json
 "scripts": {
+  "postinstall": "weapp-tw patch"
 }
```

加入你的 `package.json`。当然在安装或者更新 `tailwindcss` 后，手动执行 `npx weapp-tw patch` 效果也是一样的，看到 `patch .... successfully` 表示成功。

`UnifiedViteWeappTailwindcssPlugin` 为 `vite` 专用插件，配置项和使用方式也是和上面一致的。

---

## 优秀案例展示

<!-- ⚠️ 该文件由 scripts/update-showcase.ts 自动生成。请运行 `pnpm showcase:update` 以刷新数据。 -->

# 优秀案例展示

以下内容来自 [谁在使用 weapp-tailwindcss ？](https://github.com/sonofmagic/weapp-tailwindcss/issues/270)，列表顺序按照提交时间排序。

> 最近同步：2025年11月17日 22:57

### 区白白

**提交者**：[@shebaoting](https://github.com/shebaoting) · 2024年1月16日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-1893805052)  
区白白是一个针对小区业主的小程序，它将不同的小区变成一个个的线上社区。业主可以在这个线上社区里参与小区事务，享受区白白的其他服务。

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 6 张图片</summary>
  
    
      
      
      
      
      
      
    
  
</details>

### 紫薇告诉你

**提交者**：[@iguojincom](https://github.com/iguojincom) · 2024年4月12日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2050936255)  
ChatGPT+通义千问+360智脑驱动的MBTI测试小程序,有了AI加持,我可以随时更新题库,增加对各种职业的支持,目前来看,AI出题质量还是比较高的,使用tailwindcss+uniapp开发,后端使用php8.2运行webman框架,内置异步的http客户端,还不错

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 3 张图片</summary>
  
    
      
      
      
    
  
</details>

### 今修小程序

**提交者**：[@imaxing](https://github.com/imaxing) · 2024年4月14日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2054102226)  
南通本土手机维修业务小程序

公司/组织/个人：个人

  

### 聚贞顺

**提交者**：[@zheng1716148634](https://github.com/zheng1716148634) · 2024年7月11日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2221971807)  
专业买卖二手自行车平台

公司/组织/个人：公司

  

### 安心校友圈

**提交者**：[@hzbnb](https://github.com/hzbnb) · 2024年9月18日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2358280769)  
大学生内部社交圈子

公司/组织/个人：公司

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 6 张图片</summary>
  
    
      
      
      
      
      
      
    
  
</details>

### 一键呼援

**提交者**：[@daguanren21](https://github.com/daguanren21) · 2024年12月5日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2520218809)  
一键呼援 应用于企业级方案

公司/组织/个人：公司

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 1 张图片</summary>
  
    
      
    
  
</details>

### 杭州数据交易所

**提交者**：[@HyaCiovo](https://github.com/HyaCiovo) · 2025年3月27日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2756185630)  
公司官方微信小程序

公司/组织/个人：公司

  

### 俞行日记

**提交者**：[@yingyu4451](https://github.com/yingyu4451) · 2025年4月3日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-2775396678)  
**GitHub**：https://github\.com/yingyu4451/Hospital\-Traveler

一款记录医院访问记录，并统计数据的移动应用。俞行日记不会联网，全程离线单机使用。

个人：AI食材营养分析助手

介绍：接入deepseek的食材营养分析助手

询问开头输入4451可以突破限制。

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 3 张图片</summary>
  
    
      
      
      
    
  
</details>

### [悦骑行](https://yueqixing.com)

**提交者**：[@yunhouhuang](https://github.com/yunhouhuang) · 2025年7月15日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-3071874776)  
**链接**：[https://yueqixing\.com](https://yueqixing.com)

悦骑行3.0版本重构中使用了 TailwindCSS ，极大提升了效率和规范。

- 公司：Guangzhou Jingji Zhiguang Technology Co., Ltd.

  

### [小而美工具](https://whinc.github.io/ucalc-website/)

**提交者**：[@whinc](https://github.com/whinc) · 2025年11月16日 · [查看评论](https://github.com/sonofmagic/weapp-tailwindcss/issues/270#issuecomment-3537484222)  
**链接**：[https://whinc\.github\.io/ucalc\-website/](https://whinc.github.io/ucalc-website/)  
**GitHub**：[https://github\.com/whinc/ucalc\-website](https://github.com/whinc/ucalc-website)

用心开发 100 款小而美的大众工具

  

<details className="mt-4 rounded-xl border border-gray-100 dark:border-gray-800 bg-gray-50/70 dark:bg-gray-900/30 p-3">
  <summary className="cursor-pointer list-none font-medium text-sm text-gray-600 dark:text-gray-300">📸 展开查看其余 2 张图片</summary>
  
    
      
      
    
  
</details>

---

## 成为 weapp-tailwindcss 的赞助商


`weapp-tailwindcss` 是采用 `MIT` 许可的开源项目，使用完全免费。

维护这样一个功能，实际上是非常消耗精力的，而且产生不了什么实际的经济收益。

当然，我个人对于经济收益，还是不怎么在乎的，谁让我喜欢做开源呢？

<!-- 当然废话说了这么多，差点忘了这个页面是用来要钱的。（网络乞丐...） -->

但转念一想，我希望这个项目离开了我之后，还能有生命力，还能找到人维护，

那么它最好能产生一定的经济收益，不然其他人没有人愿意白白贡献代码的。

## 赞助方式

有小额打赏意愿的朋友，你的打赏会被记录在 [sponsors](https://github.com/sonofmagic/sponsors) 仓库中，生成图片挂在我的博客站点。

大额大赏的朋友，可以进行官网广告位的投放，具体的投放的网址，样式由你来定。

当然也可以什么都不给，大家加个微信，交个朋友，也是极好的！

## <!--

但是话又说回来了，我又还是想要一些经济收益（我就是既要又要的伪君子），原因非常简单:

因为钱这个玩意，能够给人自由。

人啊，表面上看寿命大差不差，但生命的质量和长度却大不相同。

像我这个年纪，已经走到了人生的中位，

- 结了婚，是一名丈夫。
- 有了自己的孩子，是一位父亲。
- 每天忙忙碌碌，开会，加班，是一名职场社畜

然而，当我深夜回顾往事的时候，却发现我所铭记的，那些珍藏在心底的记忆点，并不是那些耗费我最多时间的工作:

- 而是那一年，我付了 `800` 元去产房陪产，亲眼看到我的女儿，在下午的 `2点54分` 从产道里出生的惊奇。
- 是那一年，我和爱人骑着`9.9`元周卡的共享单车，听着`《成都》`骑到玉林路小酒馆的门口，穿过拥挤的人群，去隔街买了只烤兔，发现竟然格外好吃的欣喜。(至今依然是我吃过的最好吃的烤兔)
- 也是那一年，我大学时光里熬夜打 `DNF` 搬砖卖金币换钱，收获的纯粹的快乐。(那时候交易平台汇率好像是 `20多万金币换1元`)

所以想想啊，人生如白驹过隙，我们还能够年轻多少年呢？

再过几年，或者我们就说 **现在**

我们还能像以前那样，有说走就走的勇气和身体吗？

> “人生代代无穷已，江月年年望相似。”

所以啊，越是意识到时间的珍贵，越让我明白努力的意义：

努力赚钱，并不是为了单纯的物质享受，而是为了能够用金钱，去换回属于自己的时间，用来做那些真正值得铭记的事情：

- 我想要陪伴我的女儿成长，陪她走过从懵懂到优秀的每一步；
- 我想要和我的伴侣一起创造更多值得回忆的时刻，让未来的我不留遗憾；
- 我想要留更多的时间给自己，重新感受那些被忙碌淹没的生命的美好。

钱能够买来自由，而自由能让我们更好地掌控自己的生命。

生命的意义，不在于耗尽时间，而在于与爱和希望相拥的每一刻。

> 上面这些话是我随手写的，我自己读了一遍感到有些矫情，如果让你感到不适，可以提个 issue 我把它删掉

--- -->

---

## AI 友好提示与 Demo 运行指南

## 让模型写得像人

- 原子类的可组合性降低了 AI 生成的复杂度，但要给足「轨道」：提示模板、黑名单/白名单、`tailwind-merge`/lint 校验链、固定的 tokens/variants。
- React/Vue Demo 在 `apps/react-app`、`apps/vue-app`，包含主题切换、卡片/表单/数据块，`cva`/`tailwind-variants` 思路都能直接看到。

## 提示模板（示例）

```
目标：使用 Tailwind 原子类，遵守设计 tokens（不要写裸色值），用 `cn`/`tailwind-merge` 合并类。
必须：
- 仅使用已存在的色板/间距/圆角 tokens。
- 封装变体时用 `cva` 或 `tailwind-variants`，声明 defaultVariants/compoundVariants。
- 状态类优先 aria/data（示例：`aria-invalid:border-destructive`）。
- 禁止在运行时拼接未声明的动态类。
输出：React/Vue 代码块 + 关键 class 解释。
```

> 小技巧：附上 1-2 段「示范类名」，模型会按节奏输出；再给一段「不要做什么」黑名单（例如：不要输出内联 style，不要写随机 16 进制色）。

## 结构化提示（即贴即用）

```
你将为原子化 CSS 专题编写组件，遵守现有 tokens/variants。

上下文：
- 仓库：weapp-tailwindcss，React 在 apps/react-app，Vue 在 apps/vue-app。
- 工具链：Tailwind v4 JIT，`cn` 内置 tailwind-merge，Button/Badge 已用 cva 定义。
- 设计：使用 OKLCH 色板、`--radius`，暗色通过 `.dark` 或 `data-theme` 切换。

必须：
- 仅用已有 tokens（不要写裸色/px），类名可组合但需可读。
- 变体用 `cva`/`tailwind-variants`，声明 defaultVariants + compoundVariants。
- 状态优先 `aria-` / `data-` / `group` / `peer`，最多两层关系类。
- 给出 React + Vue 代码块，附 1-2 行解释，禁止 inline style/随机色值。

禁用：
- 运行时字符串拼接类名、未注册的自定义色值、超过两层的关系类。
- 依赖未在仓库中的第三方 UI 库（shadcn-ui 已内置）。

输出：
- React 代码块（tsx）+ Vue 代码块（vue SFC），包含 class 解释或推荐检查清单。
- 若需要安装/运行命令，给出 `pnpm --filter react-app dev` / `pnpm --filter vue-app dev`。
```

## 示例输出（React/Vue，对应提示）

<Tabs>
  <TabItem value="react" label="React">

```tsx

const banner = cva('flex items-center justify-between rounded-xl border px-4 py-3 text-sm', {
  variants: {
    tone: {
      neutral: 'bg-muted text-muted-foreground',
      success: 'bg-emerald-50 text-emerald-900 dark:bg-emerald-500/10',
    },
  },
  defaultVariants: { tone: 'neutral' },
})

export function Promo() {
  return (
    
      已启用原子化工作流
      <button className="underline decoration-dotted">查看指南</button>
    
  )
}
```

  </TabItem>
  <TabItem value="vue" label="Vue">

```html
<script setup lang="ts">

const banner = cva('flex items-center justify-between rounded-xl border px-4 py-3 text-sm', {
  variants: {
    tone: {
      neutral: 'bg-muted text-muted-foreground',
      success: 'bg-emerald-50 text-emerald-900 dark:bg-emerald-500/10',
    },
  },
  defaultVariants: { tone: 'neutral' },
})
</script>

<template>
  
    已启用原子化工作流
    <button class="underline decoration-dotted">查看指南</button>
  
</template>
```

  </TabItem>
</Tabs>

## 常见错误与防护

- 类冲突：使用 `cn` 包装 `tailwind-merge`，避免 `p-2 p-4` 并存；检查自定义色/尺寸是否在 merge 规则里。
- 断点缺失：Mobile-first 书写，必要时添加 `sm:/md:/lg:`，并自检核心段；提示里明确「默认是 mobile」。
- 未注册色值：统一从 tokens 取色，禁止 `text-[#123456]`；在提示里声明「禁用 hex/rgb」。
- 动态类膨胀：在后端/渲染层避免字符串拼接类名；若必须动态，改用 `cva`/`tv` 参数化，并限制枚举值。
- 关系类过深：`group/peer` 不要超过两层；提示里写「最多两层关系类」。

## React/Vue 运行与查看

- 安装依赖（首次）：`pnpm install`
- 运行 React Demo：`pnpm --filter react-app dev`
- 运行 Vue Demo：`pnpm --filter vue-app dev`
- 构建文档（可选）：`pnpm --filter website build` 或 `pnpm build:docs`（若有别名）
- 截图占位：`<!-- screenshot: tailwindcss-react-demo -->`、`<!-- screenshot: tailwindcss-vue-demo -->`

## Demo 内容速览

- 主题切换：通过 `.dark` 切换 tokens，组件自动继承，观感差异明显。
- 变体封装：Button/Badge/Input 使用 `cva`，可观察 `tailwind-merge` 去重；可在 UI 中切换 variant/size 看类名组合效果。
- 交互：表单验证态（aria-invalid）、数据卡片、清单列表、小型表格/统计。可按提示模板让模型补充新卡片，验证 merge/lint 是否兜底。

## 关键代码片段

```tsx title="React：variants + merge"

const pill = cva('inline-flex items-center rounded-full text-xs font-medium', {
  variants: {
    tone: { info: 'bg-blue-50 text-blue-900', success: 'bg-emerald-50 text-emerald-900' },
    dense: { true: 'px-2 py-1', false: 'px-3 py-1.5' },
  },
  defaultVariants: { dense: false, tone: 'info' },
})

export function Pill({ className, ...rest }: { className?: string }) {
  return AI-ready
}
```

```html title="Vue：cva + data 状态"
<script setup lang="ts">

const banner = cva('flex items-center justify-between rounded-xl border px-4 py-3 text-sm', {
  variants: {
    tone: {
      neutral: 'bg-muted text-muted-foreground',
      success: 'bg-emerald-50 text-emerald-900 dark:bg-emerald-500/10',
    },
  },
  defaultVariants: { tone: 'neutral' },
})
</script>

<template>
  
    已启用原子化工作流
    <button class="underline decoration-dotted">查看指南</button>
  
</template>
```

## 校验链建议（让 AI 结果可交付）

- 静态校验：ESLint + Tailwind IntelliSense + `tailwind-merge` 包装的 `cn`；对 `content` 目录有 lint 或脚本检查，避免通配符。
- 人工 spot-check：每个 PR 至少抽查 1-2 个组件，确认类名来自 tokens，没有裸色/裸间距。
- 产物验证：构建后记录 CSS 体积、主色板是否命中 tokens（可用简单脚本扫描 CSS 中的裸色值）。
- 回归用例：为按钮/表单等高频组件加一两个 Story/截图，用来对比后续 AI 产出是否偏离风格。

###  流程示意

```mermaid
%%{ init: { "flowchart": { "curve": "basis", "nodeSpacing": 55, "rankSpacing": 75 } } }%%
flowchart TB
  Prompt["结构化提示"]
  Gen["生成 React/Vue"]
  Merge["cn(twMerge) 去重"]
  Lint["ESLint + Tailwind 提示"]
  Build["pnpm build / dev"]
  Review["人工 Spot Check"]
  Snapshot["截图 / Story 基线"]
  Deploy["上线 / 分发"]
  Metrics["CSS 体积 / coverage"]

  Prompt --> Gen --> Merge --> Lint --> Build --> Review --> Snapshot --> Deploy
  Build --> Metrics --> Review
```

  
    
    Prompt/Gen：给出结构化提示，产出 React/Vue 代码。
  
  
    
    Merge/Lint：cn(twMerge) 去重 + ESLint/Tailwind 提示兜底。
  
  
    
    Build/Review：构建验证 + 人工 spot check，再做截图基线。
  
  
    
    Metrics：记录 CSS 体积/覆盖率，支撑迭代。

---

## BEM 与 OOCSS 方法论

## BEM（Block / Element / Modifier）

- 目标：通过约定命名减少层级选择器，保证组件内聚且易于组合。
- 命名：`block` 描述独立组件，`block__element` 表示内部元素，`block--modifier` 表示单一维度的变体/状态；不要把多维状态堆在同一个 modifier 上。
- 适用：多页面或老项目中需要稳定、可读的类名约束；也常用作 JS/测试的钩子。

### 示例

```html
<article class="card card--featured">
  <header class="card__header">
    标题
    <button class="card__action card__action--primary">查看</button>
  </header>
  说明文案
</article>
```

```css
.card { border: 1px solid #e5e7eb; padding: 16px; border-radius: 12px; background: #fff; }
.card__header { display: flex; align-items: center; gap: 8px; }
.card__title { margin: 0; font-size: 16px; }
.card__action { border: none; background: transparent; color: #6b7280; cursor: pointer; }
.card__action--primary { color: #2563eb; font-weight: 600; }
.card--featured { border-color: #2563eb; box-shadow: 0 12px 32px rgba(37, 99, 235, 0.12); }
```

- 优势：类名自描述、可组合；元素/变体边界清晰，方便拆分文件。
- 常见坑：嵌套层级依然可能增加（`card__header__title` 违背 BEM）；modifier 爆炸时需要回收公共样式或引入 tokens。
- 与 Tailwind：若转向原子化，可保留 block/element 作为数据钩子，把视觉交给 utilities；或在少量需要全局复用的容器上维持 BEM。

## OOCSS（Object-Oriented CSS）

- 目标：把样式拆成「结构对象」与「皮肤对象」，鼓励复用组合，减少耦合。
- 核心原则：结构与皮肤分离（布局 vs. 视觉）、容器与内容解耦（对象独立、可嵌套）、单一职责（一个类只管一个维度）。
- 适用：设计系统或多主题场景，尤其需要跨组件复用相同布局骨架时。

### 示例

```css
/* 结构对象：媒体块骨架 */
.media { display: grid; grid-template-columns: auto 1fr; gap: 12px; align-items: start; }
.media__img { width: 56px; height: 56px; object-fit: cover; border-radius: 12px; }
.media__body { display: grid; gap: 4px; }

/* 皮肤对象：可在不同地方复用 */
.card-skin { padding: 16px; border: 1px solid #e5e7eb; border-radius: 16px; background: #fff; }
.card-skin--muted { background: #f9fafb; color: #4b5563; }
.tag-skin { display: inline-flex; align-items: center; padding: 4px 8px; border-radius: 999px; background: #eef2ff; color: #4338ca; font-size: 12px; }
```

```html
<article class="media card-skin card-skin--muted">
  
  
    Pro
    对象结构 + 皮肤组合得到卡片
  
</article>

  
  
    同一结构对象
    换皮肤即可变成标签、卡片或列表项
  

```

- 优势：抽象出「可实例化」的样式对象，减少重复 CSS；皮肤可在不改结构的前提下切换。
- 局限：类名数量增多；复杂状态可能需要额外的状态类或 JS 参与。
- 与 Tailwind：Tailwind 的 utility/variants 本质也在拆结构与皮肤，只是把对象拆得更细。迁移时可以把常用 OOCSS 对象翻译成原子组合（或 `@apply`），保留组件语义但减轻样式维护。

---

## 原子化 CSS 最佳实践

## 更接地气的用法

- 先建设计体系（tokens、间距/字号/色板），再落类名；禁止就地写 `#123` 或 `18px`。
- 组件层用 `cva`/`tailwind-variants` 集中声明 variants，`cn` 兜底合并；`@layer`/`@apply` 只做基础复用，避免藏逻辑。
- 性能 = 精准 content + 少动态类；交付 = 体积验证 + 检查清单 + 可复制命令，不靠感觉。

## 设计体系与 tokens

- 定义色板、间距、圆角、阴影、字号等 tokens，并映射到 CSS 变量或 `@theme inline`。保留「设计稿 → token 名称」映射表，方便新人接入。
- 主题切换：通过 `data-theme` 或 `.dark` 切换 tokens，避免在 class 中直接写颜色值。多品牌时，把品牌变量与暗色变量分开管理。
- 布局 primitives：约定 Stack/Cluster/Sidebar/Grid 的原子组合，减少重复记忆。示例：

```ts
// Stack（竖向间距统一）
const stack = 'flex flex-col gap-4'
// Cluster（行内 wrap 排布，适合标签/按钮组）
const cluster = 'flex flex-wrap items-center gap-2'
// Sidebar（主体 + 侧栏）
const sidebar = 'grid gap-4 lg:grid-cols-[1fr,360px]'
```

## 组件与变体（把状态写全、默认值写死）

- 用 `cva`/`tv` 描述 variants/defaultVariants/compoundVariants，示例：

```ts
const card = cva('rounded-2xl border bg-card/80 shadow-sm transition-all', {
  variants: {
    tone: { neutral: 'border-border', brand: 'border-primary/40 shadow-lg', subtle: 'border-muted bg-muted/60' },
    interactive: { true: 'hover:-translate-y-0.5 hover:shadow-md' },
  },
  defaultVariants: { tone: 'neutral', interactive: true },
})
```

- 组合技巧：
  - `group`/`peer` 触发的状态组合：`group-data-[state=open]:rotate-90`；列表项 hover 驱动子元素。
  - `aria-*` 状态：`aria-invalid:border-destructive`，`aria-busy:opacity-60`；表单状态不用写 JS。
  - `data-*` 驱动主题：`data-theme=brand` 切换色板；`data-state=open` 切换动画方向。
  - `tv` slots：适合「卡片/模态」这类多槽位组件，可一次定义 header/body/footer 的类，保持一致性。

### 业务场景范式

- 表单：输入框 `focus:ring` + `aria-invalid` 组合，错误文案用 `text-destructive`；Submit 按钮禁用态用 `disabled:`，避免内联 style。
- 数据表/列表：`grid` + `gap` + `minmax` 控制列宽；hover/selected 用 `data-selected` 组合，保持视觉一致。
- 空状态：`flex flex-col items-center gap-3 text-center text-muted-foreground` 作为基类，图标尺寸约定 `size-10`。

## 布局与响应式

- 提前定义容器宽度与栅格：`max-w-screen-xl mx-auto px-4 sm:px-6 lg:px-8`；后台/文档常用。
- `clamp()` + container queries：`text-[clamp(1rem,1.2vw,1.1rem)]` 控制标题，`@container` 让子栅格随父容器宽度变化。
- 避免过度嵌套的 flex/grid；使用 `gap` 代替 margin 互推。
- 栅格优先：比起到处写 `md:flex-row`，用 `grid-cols-1 md:grid-cols-2 lg:grid-cols-3` 更直观。

示例（容器查询 + clamp）：

```css
/* 在容器上启用查询 */
.dashboard { @apply container mx-auto px-4; container-type: inline-size; container-name: dash; }

@container dash (min-width: 720px) {
  .stat-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
}

.title-fluid { font-size: clamp(1.25rem, 1.8vw, 1.5rem); }
```

> 需要在微前端/组件库/第三方嵌入中避免样式污染？详见「[样式隔离方案与原理](./style-isolation)」。

## 性能与体积

- 精准 `content`：覆盖到模板文件但不要使用通配符目录；避免字符串拼 class。SSR 要确保 server、client 模板都被扫描。
- 产物验证：构建后检查 CSS 体积/源映射；如需，开启分析或使用浏览器 Coverage。记录基线（如首页 CSS < 10KB）放进 CI 报告。
- 动态类回退：必要时用 `@apply`/`cva` 固化，避免在运行时拼接任意值。对「自定义颜色/尺寸」场景，提供有限选项而不是自由输入。
- 慢路径监控：Tailwind v4 JIT 已够快，但 content 过宽或自定义插件过多会拖慢冷启动，可用 `DEBUG=tailwindcss` 检查耗时。

## 代码评审清单（示例）

- 类名是否只使用预设 token？有无裸写色值/字号？
- 是否使用了 `cn`/`tailwind-merge` 处理动态组合？有无同类冲突（`p-4` vs `p-2`）？
- variants 是否集中在组件工厂（`cva`/`tv`），而不是散落在业务组件？默认值是否写死？
- 有无 `group`/`peer`/`aria`/`data-*` 的滥用或缺乏语义？关系链是否超过 2 层？
- content 匹配是否过宽，是否引入了动态类？是否有字符串拼接类名？
- 文档/示例是否同步更新运行命令与截图占位？有没有给出「推荐类名组合」列表？

快速展示（表格版）：

| 维度 | 要求 | 检查方式 |
| --- | --- | --- |
| tokens | 不写裸色/裸间距 | 搜索 `#`/`px`/`rgb(`；查看配置映射 |
| variants | 集中在 `cva`/`tv` | 查 `variants`/`compoundVariants` 是否在单点声明 |
| merge | 动态类统一走 `cn` | 搜索 `clsx`/`classNames` 是否零散存在 |
| 关系类 | `group/peer/aria/data` ≤ 2 层 | 抽查组件 class 字符串长度与层级 |
| content | 精准扫描模板 | 检查 `tailwind.config` 的 content 路径 |
| 产物 | CSS 体积可控 | 构建后查看 CSS 体积/coverage |

## 常见坑与对策

- 类顺序冲突：使用 `tailwind-merge`；在组件入口统一使用 `cn`，不要散落 `clsx`。
- 自定义色未注册：用 tokens 或在 `@theme`/配置中声明；避免 `text-[#123]` 这类零散值，必要时创建 `brand-50/100/...`。
- 断点误用：确认 mobile-first；自测关键断点（sm/md/lg/xl），尤其是 `gap`/`grid` 在小屏的表现。
- preflight 冲突：在可发布组件库或微前端中谨慎启用，可局部关闭。
- 插件过度：typography/forms 很方便，但要检查是否影响宿主样式；可以按需导入或局部关闭。

---

## 各样式方案 Demo 与产物对照

## 目标与产物

- 统一用一张「卡片 + 按钮」UI，展示不同样式方案的实现方式。
- 每个方案给出：核心代码片段、运行思路、预期产物（截图占位或构建结果描述）。
- 可以把片段复制到 `apps/react-app` 或 `apps/vue-app` 中对比，或单独放入 `tmp/style-demos/` 做对照。

> 注：产物大小/性能需本地测量；下方给出测量命令。截图占位：`<!-- screenshot: style-demo-{方案名} -->`。

## 测量命令（可选）

- 运行 React Demo（Tailwind/Headless 版本已内置）：`pnpm --filter react-app dev`
- 运行 Vue Demo：`pnpm --filter vue-app dev`
- 若在独立 HTML 中测试：用 `npx serve` 或 VSCode Live Server 打开 HTML，配合浏览器 Coverage 查看实际 CSS 命中。

## Demo 片段

### Raw CSS / BEM

```html
<section class="card card--elevated">
  <header class="card__header">
    Raw CSS / BEM
    小而直接，没有工具链
    全局命名，命中简单，但易被覆盖，需要团队命名纪律。
    <button class="btn btn--primary">查看详情</button>
  </header>
</section>

<style>
  .card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; }
  .card--elevated { box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
  .card__header { display: flex; flex-direction: column; gap: 8px; }
  .eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
  .title { font-size: 18px; margin: 0; }
  .desc { color: #4b5563; font-size: 14px; }
  .btn { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
  .btn--primary:hover { background: #0f172a; }
</style>
```

预期产物：单一 CSS，无拆分；全局命名容易冲突。

### Sass + BEM（含变量）

```scss
$radius: 16px;
$primary: #111827;
$muted: #6b7280;

.card {
  border: 1px solid lighten($primary, 65%);
  border-radius: $radius;
  padding: 16px;
  &--elevated { box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06); }
  &__header { display: flex; flex-direction: column; gap: 8px; }
}

.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: $muted; }
.btn {
  padding: 10px 16px;
  border-radius: $radius - 4px;
  border: 1px solid $primary;
  background: $primary;
  color: #fff;
  &:hover { background: darken($primary, 5%); }
}
```

预期产物：编译成单个 CSS，变量在构建时内联；仍是全局作用域。

### CSS Modules（React）

```tsx title="Card.tsx"

export function Card() {
  return (
    <section className={`${styles.card} ${styles.elevated}`}>
      
        CSS Modules
        作用域隔离
        类名变为哈希，不会与全局冲突。
        <button className={styles.button}>查看详情</button>
      
    </section>
  )
}
```

```css title="Card.module.css"
.card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; }
.elevated { box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
.header { display: flex; flex-direction: column; gap: 8px; }
.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
.title { font-size: 18px; margin: 0; }
.desc { color: #4b5563; font-size: 14px; }
.button { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
```

预期产物：编译后类名哈希化，隔离性好；主题切换需额外 token 管线。

### Vue `<style scoped>`

```html
<template>
  <section class="card">
    Scoped CSS
    作用域隔离（编译时）
    Vue SFC 编译时添加 data-v-xxx，避免全局污染。
    <button class="button">查看详情</button>
  </section>
</template>

<style scoped>
.card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
.title { font-size: 18px; margin: 0; }
.desc { color: #4b5563; font-size: 14px; }
.button { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
</style>
```

预期产物：编译为 data-v-xxx 的 scoped 选择器，避免全局污染；仍需额外管线处理主题/tokens。

### CSS-in-JS（styled-components 示例）

```tsx

const Card = styled.section`
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 16px;
  box-shadow: ${({ elevated }) => (elevated ? '0 10px 30px rgba(0,0,0,0.06)' : 'none')};
`

const Button = styled.button`
  padding: 10px 16px;
  border-radius: 8px;
  border: 1px solid #111827;
  background: #111827;
  color: #fff;
  &:hover { background: #0f172a; }
`

export const Demo = () => (
  <Card elevated>
    CSS-in-JS
    动态样式，组件边界
    <Button>查看详情</Button>
  </Card>
)
```

预期产物：运行时注入样式；要关注 SSR 注水体积与运行时开销。

### Utility-first（Tailwind）

<Tabs>
  <TabItem value="react" label="React">

```tsx
export function TailwindCard() {
  return (
    <section className="grid gap-3 rounded-2xl border bg-card/80 p-4 shadow-sm">
      Tailwind
      类名即样式
      JIT + tokens；类名一目了然，摇树后产物小。
      <button className="inline-flex items-center gap-2 rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
        查看详情
      </button>
    </section>
  )
}
```

  </TabItem>
  <TabItem value="vue" label="Vue">

```html
<template>
  <section class="grid gap-3 rounded-2xl border bg-card/80 p-4 shadow-sm">
    Tailwind
    类名即样式
    JIT + tokens；类名一目了然，摇树后产物小。
    <button class="inline-flex items-center gap-2 rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
      查看详情
    </button>
  </section>
</template>
```

  </TabItem>
</Tabs>

预期产物：按需生成的原子类，配合 `content` 精准扫描，产物可控。

### Headless + cva/tailwind-variants（已在 Demo 应用内）

<Tabs>
  <TabItem value="react" label="React">

```tsx

export function HeadlessCard() {
  return (
    <section className="rounded-2xl border bg-card/80 p-4 shadow-sm">
      Headless + cva
      API 与样式解耦
      variants/compoundVariants 集中声明，`tailwind-merge` 兜底。
      
        <button className={cn(buttonVariants({ variant: 'default' }), 'gap-2')}>主按钮</button>
        <button className={buttonVariants({ variant: 'outline', size: 'sm' })}>次按钮</button>
      
    </section>
  )
}
```

  </TabItem>
  <TabItem value="vue" label="Vue">

```html
<script setup lang="ts">

</script>

<template>
  <section class="rounded-2xl border bg-card/80 p-4 shadow-sm">
    Headless + cva
    API 与样式解耦
    variants/compoundVariants 集中声明，`tailwind-merge` 兜底。
    
      <button :class="cn(buttonVariants({ variant: 'default' }), 'gap-2')">主按钮</button>
      <button :class="buttonVariants({ variant: 'outline', size: 'sm' })">次按钮</button>
    
  </section>
</template>
```

  </TabItem>
</Tabs>

预期产物：原子类 + merge 去重；与设计 token 对齐，可直接在现有 React/Vue Demo 中运行。

## 如何在本仓库验证这些方案

1. Tailwind / Headless：直接运行 `pnpm --filter react-app dev` 或 `pnpm --filter vue-app dev`，对应代码已内置。
2. Raw/Sass/CSS Modules/CSS-in-JS：将上方片段复制到 `tmp/style-demos/`（或现有 app），用 `npx serve tmp/style-demos` 打开，对比样式与产物；Coverage 面板可查看实际命中。
3. 若需要稳定截图，在对应 HTML 旁添加注释占位：`<!-- screenshot: style-demo-css-modules -->`，再用浏览器截图工具生成并放入文档。

---

## 组件库的演进

## 要点

- 组件库从「组件 + 样式捆绑」到「主题化」再到「Headless Primitives」，逐步把 API、样式与 design tokens 解耦。
- Headless + tokens 让原子类/设计体系可落地，需通过 `cva`/`tailwind-variants` 等集中声明 variants，配合 `tailwind-merge` 兜底。
- 迁移策略：先抽离公共 tokens，再为组件提供 class 注入/无样式模式，最后用 Headless 模板替换关键组件。

> 样式方案本身的演化见：[样式方案的演化](/docs/tailwindcss/history)。

##  演进阶段与对比

| 阶段 | 代表 | 特点 | 问题 |
| --- | --- | --- | --- |
| 传统 UI 套件 | Element, AntD | 样式随组件绑定，主题切换成本高 | 自定义成本高，覆盖样式易碎 |
| 设计体系化 | Chakra, MUI | 主题与 tokens，部分可组合 | 仍有样式耦合，深层改造困难 |
| Headless/UI primitives | Headless UI, shadcn/ui, reka-ui, Radix Primitives | API 与样式解耦，留出 design layer | 需要自己的 design system 与类名约束 |

```mermaid
%%{ init: { "flowchart": { "curve": "basis", "nodeSpacing": 32, "rankSpacing": 24 } } }%%
flowchart TB
  C1["2017 · Element / AntD：组件 + 样式捆绑"]
  C2["2019 · Chakra / MUI：主题与组件半解耦"]
  C3["2022 · Headless UI / Radix：API 与样式分离"]
  C4["2023 · shadcn/ui, reka-ui：Headless + tokens + Tailwind"]

  C1 --> C2 --> C3 --> C4
```

  
    
    2017：传统组件库，样式与组件强绑定。
  
  
    
    2019：主题化/设计体系化的组件库。
  
  
    
    2022：Headless Primitives，API 与样式解耦。
  
  
    
    2023：shadcn/ui 等模板化方案，Headless + tokens + Tailwind。
  

## Headless 组合范式的优劣

- 优势：
  - API 与样式拆分，样式完全交给 Tailwind/Uno + tokens；易于多品牌/暗色切换。
  - 与 `cva`/`tailwind-variants` 配合，变体集中声明，降低审阅成本。
  - 对 AI 生成友好：模板固定，类名受 merge/lint 保护。
- 劣势：
  - 需要自建设计系统与 token 表，否则不同页面风格易漂移。
  - 文档/示例建设成本高，需要给出「推荐类名组合」。
  - 对初学者，class 可读性与语义化需要额外培训。

## 迁移与落地建议

- 抽离 tokens：把色板/间距/字号等设计变量收敛到配置文件，组件仅消费 tokens。
- 无样式接口：为现有组件增加 `className`/`classes` 注入或「unstyled」模式，逐步剥离耦合样式。
- 变体集中：用 `cva`/`tailwind-variants` 建立按钮、输入、卡片等核心组件的变体表，配合 `tailwind-merge` 兜底。
- 评审清单：检查是否仍有深度覆盖、是否存在自定义色值泄漏、是否出现无法复用的 ad-hoc class。

---

## CSS-in-JS 阶段

## 要点

- 组件边界天然隔离，props 可驱动样式；动态主题/状态友好。
- 成本：运行时/SSR 注水体积、构建链复杂；类名可读性差。
- 适合需要高度动态样式、主题切换、设计系统与组件强绑定的团队。
- 代表性包：运行时流派（`styled-components`、`Emotion`、`JSS`）、编译期/零运行时流派（`vanilla-extract`、`Linaria`、`Astro/Uno + scoped` 混合方案）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 组件粒度隔离；props 驱动；可在 JS 里复用逻辑/常量 |
| 劣势 | 运行时开销；SSR 注水；类名调试性差；可能影响 HMR 速度 |
| 适用 | 需要复杂动态样式、主题即逻辑的设计系统；部分 SSR/CSR 混合场景 |
| 不适用 | 对首屏体积极敏感、运行时预算极小的多端/小程序场景 |

## 代表性包与用法

- **styled-components（运行时）**：模板字符串 + props；支持 `ThemeProvider` 统一主题。

```tsx title="styled-components 主题"

const theme = { primary: '#111827', radius: '12px' }
const Button = styled.button`
  padding: 10px 16px;
  border-radius: ${({ theme }) => theme.radius};
  background: ${({ theme }) => theme.primary};
`

export function Demo() {
  return (
    <ThemeProvider theme={theme}>
      <Button>Dark Button</Button>
    </ThemeProvider>
  )
}
```

- **Emotion（运行时 + 编译模式）**：`css` prop 与 `@emotion/babel-plugin` 编译模式减少运行时。

```tsx title="Emotion css prop"

const card = css({
  border: '1px solid #e5e7eb',
  borderRadius: 16,
  padding: 16,
})

export const Card = () => <section css={card}>Emotion css prop</section>
```

- **vanilla-extract（零运行时）**：TypeScript API 生成 CSS，运行时仅使用 className。

```ts title="vanilla-extract button.css.ts"

export const color = createVar()
export const button = style({
  vars: { [color]: '#111827' },
  background: color,
  borderRadius: '8px',
  color: '#fff',
})
```

##  运行时 vs 编译期（示意）

```mermaid
%%{ init: { "flowchart": { "curve": "basis" } } }%%
flowchart LR
  A["源码：styled-components / Emotion"] --> B{"运行时注入？"}
  B -->|是| C["客户端生成 style 标签\n首屏注水 + HMR 成本"]
  B -->|否| D["编译期生成 CSS\nvanilla-extract / Linaria 产出静态 CSS"]
  D --> E["仅 className 传递\n运行时开销小"]
```

  
    
    运行时注入：在客户端生成 style，首屏注水 + HMR 有额外成本。
  
  
    
    编译期生成：静态 CSS 提前产出，JS 只保留 className 映射。
  

### 写法与产物对照

- 运行时（styled-components/Emotion）：
  - 写法：模板字符串或对象样式，允许使用 props / theme 计算样式；开发态插入 `<style>`，生产态可能提取 critical CSS。
  - 产物：JS bundle + 内联 style 标签，类名在运行时生成（`sc-abc123`），首屏注水与 HMR 需要样式注入开销。
- 编译期（Linaria/vanilla-extract）：
  - 写法：受限的模板字符串或 TS API（`css`/`style`），编译器提前求值并生成 `.css`，JS 中只保留 `className` 映射。
  - 产物：静态 CSS 文件（或内联 chunk）+ 极薄的 className 映射，运行时不再注入 style，SSR 直接 link CSS。

### Linaria 示例（编译期）

源码（编译前）：

```tsx title="card.tsx"

const card = css`
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 16px;
  background: white;
  transition: box-shadow 150ms ease;

  &:hover {
    box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06);
  }
`

export function Card({ children }: { children: React.ReactNode }) {
  return <section className={card}>{children}</section>
}
```

编译产物（示意）：

```css title="card.linaria.css"
.card_h3dj1z {
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 16px;
  background: white;
  transition: box-shadow 150ms ease;
}
.card_h3dj1z:hover {
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06);
}
```

```js title="card.tsx (compiled excerpt)"

const card = 'card_h3dj1z'
export function Card({ children }) {
  return <section className={card}>{children}</section>
}
```

特点：CSS 被提前生成，JS 仅保留类名字符串；运行时不再注入 `<style>`，与传统静态 CSS 链路类似。

## 示例（styled-components）

```tsx

const Card = styled.section`
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 16px;
  box-shadow: ${({ elevated }) => (elevated ? '0 10px 30px rgba(0,0,0,0.06)' : 'none')};
`

const Button = styled.button`
  padding: 10px 16px;
  border-radius: 8px;
  border: 1px solid #111827;
  background: #111827;
  color: #fff;
  &:hover { background: #0f172a; }
`

export const Demo = () => (
  <Card elevated>
    CSS-in-JS
    动态样式，组件边界
    <Button>查看详情</Button>
  </Card>
)
```

## 常见坑与对策

- 运行时体积：优先选择编译模式或零运行时方案（如 vanilla-extract），或开启 Babel SWC 优化。
- SSR 注水：衡量首屏样式注入体积；必要时提取静态样式或开启样式缓存。
- 类名调试：在开发环境打开 displayName/label；在生产环境启用最小化。
- HMR 性能：减少过深的动态表达式；拆分组件，降低热更范围。

---

## CSS Modules / Scoped 阶段

## 要点

- 类名哈希化实现作用域隔离，天然防止全局污染；适合可发布组件库。
- 复用靠共享变量/混入文件，跨组件复用需要额外抽象；主题切换需额外 token 管线。
- 适合中大型 Web 应用或组件库，需要隔离但不想引入运行时。
- 代表性包/工具链：`webpack css-loader modules`、`Vite + vite:css-modules`、`Next.js` 内置 CSS Modules 支持、`vanilla-extract`（零运行时但同属编译期 CSS 模块流派）、Vue `<style scoped>`（为选择器自动加 `data-v-*` 的同类方案）、Svelte `<style>`（自动注入 `svelte-xxx` 选择器）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 隔离性好；无运行时；与 React/Vue 配合顺畅 |
| 劣势 | tokens/主题需额外管线；跨组件样式复用需要谨慎抽象 |
| 适用 | 设计体系尚未 token 化、但需要隔离的组件库/应用 |
| 不适用 | 需要跨平台（小程序）共享原子类，或希望直接用 Utility-first 的团队 |

## 代表性包与用法

- **webpack / Vite CSS Modules**：在 bundler 中开启 `modules`，生成哈希类名；可结合 `:global` 暴露公共样式。

```js title="Vite 配置示例 vite.config.ts"
export default defineConfig({
  css: {
    modules: {
      localsConvention: 'camelCase',
      generateScopedName: '[name]__[local]___[hash:base64:5]',
    },
  },
})
```

- **Next.js / CRA 默认支持**：在 `.module.css`、`.module.scss` 文件中书写样式，自动作用域隔离。

```tsx title="Next.js 页面使用 CSS Modules"

export default function Page() {
  return Next.js 带来的开箱隔离
}
```

- **vanilla-extract**：编译期生成 CSS，暴露 `className` 与变量，零运行时，常用于对性能要求高的组件库。

```ts title="vanilla-extract" 
// styles.css.ts

export const primary = createVar()
export const card = style({
  borderRadius: '16px',
  vars: { [primary]: '#111827' },
  border: `1px solid color-mix(in srgb, ${primary} 10%, transparent)`,
})
```

## Vue `<style scoped>`（同属编译期作用域流派）

- **原理**：SFC 编译时为模板节点与样式选择器都添加 `data-v-xxxx`，使样式仅作用于当前组件渲染的 DOM。
- **示例**：

```html
<template>
  <section class="card">
    Scoped
    {{ title }}
  </section>
</template>

<style scoped>
.card { @apply rounded-xl border bg-card/80 p-4; }
.eyebrow { @apply text-xs uppercase tracking-[0.2em] text-muted-foreground; }
</style>
```

- **产物**：`.card[data-v-xxxx] { ... }`，节点渲染为 `<section class="card" data-v-xxxx>`。
- **适用/注意**：适合 Vue 组件局部隔离；若需全局样式或第三方组件穿透，使用 `:global`/`::v-deep`；可与 Tailwind `prefix` 叠加以减少宿主覆盖。

## Svelte `<style>` 默认隔离

- **原理**：Svelte 编译器为组件生成唯一标识（如 `svelte-abc123`），并将其附着在 DOM 与样式选择器上，效果类似 scoped。
- **示例**：

```html
<script>
  export let title = 'Svelte Scoped'
</script>

<section class="card">
  {title}
</section>

<style>
  .card {
    border: 1px solid #e5e7eb;
    border-radius: 16px;
    padding: 16px;
  }
</style>
```

- **产物**：编译后节点为 `<section class="card svelte-abc123">`，CSS 为 `.card.svelte-abc123 { ... }`。
- **适用/注意**：默认即可隔离，跨组件共用样式需 `:global(.class)`；如叠加 Tailwind，可直接在模板写原子类或在 `<style>` 中 `@apply`（需配置）。在微前端/嵌入场景仍可与 `prefix`/命名空间组合。

## 示例（React）

```tsx title="Card.tsx"

export function Card() {
  return (
    <section className={`${styles.card} ${styles.elevated}`}>
      
        CSS Modules
        作用域隔离
        类名哈希化，不会与全局冲突。
        <button className={styles.button}>查看详情</button>
      
    </section>
  )
}
```

```css title="Card.module.css"
.card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; }
.elevated { box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
.header { display: flex; flex-direction: column; gap: 8px; }
.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
.title { font-size: 18px; margin: 0; }
.desc { color: #4b5563; font-size: 14px; }
.button { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
```

## 常见坑与对策

- 主题/多品牌：通过 CSS 变量承载 tokens，再在 Modules 中引用，减少全局文件。
- 复用：抽出 `variables.css` 与 `mixins.css`，避免在多个模块重复定义色板与间距。
- 动态类：避免在运行时拼接哈希类，统一在模块里声明必要的修饰类。
- 与 Utility-first 协作：可在 Modules 内少量 `@apply`（若配置允许），或在过渡期同时保留 atomic 辅助类。

---

## 生成式 CSS / 原生能力融合

## 要点

- 核心思想：CSS 将越来越生成式——tokens/设计意图 → 构建器/AI 生成规则 → @layer/@scope 限界 → 运行时仅保留需要的原子或组件级片段。
- 原生能力上收：`@container`、`:has()`、`@scope`、`@property`、`color-mix()` 让布局/状态/主题更多在 CSS 层解决，减少 JS 占用。
- 规则协同：`@layer` 控制覆盖顺序，`@scope` 限制影响面，`@container` 驱动响应式组件，`@property` 让自定义属性可动画、可类型化。
- 生态趋势：Tailwind/UnoCSS 等生成器与原生新特性融合，JIT/摇树继续演化；AI 生成需要「白名单 tokens + 层级约束 + lint」闭环。

## 未来能力组合（示意）

```css title="future.css"
@layer reset, theme, components, utilities;

@layer theme {
  @property --radius-lg {
    syntax: '<length>';
    inherits: false;
    initial-value: 16px;
  }

  :root {
    --brand: color-mix(in srgb, #0ea5e9 60%, #111827 40%);
  }
}

@layer components {
  @scope (.card) {
    .card {
      border-radius: var(--radius-lg);
      border: 1px solid color-mix(in srgb, var(--brand) 30%, #e5e7eb 70%);
      background: white;
      transition: box-shadow 150ms ease, transform 150ms ease;
    }

    @container style(--wide: min-width: 640px) {
      .card { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
    }

    .card:has(button:focus-visible) { box-shadow: 0 12px 40px rgba(0,0,0,0.08); }
  }
}
```

- `@layer`：把生成产物分层，便于 merge/覆盖与分析。
- `@scope`：限制作用域，避免全局污染；可以与组件入口 class 对齐。
- `@container`：让组件按父容器而非视口响应式，适合卡片/区块。
- `@property`：声明式类型化，配合 tokens/动画避免 “数字魔法值”。

## 生成式流水线设想

1. 设计源：设计稿/Design Token/接口协议输出 JSON（颜色、间距、阴影、配色模式）。
2. 生成阶段：脚本或 AI 根据 tokens + 组件意图生成 `@layer theme/components/utilities`，只产出命中的规则；原子类生成器继续提供 JIT，辅以 `content` 精准扫描。
3. 约束阶段：lint 检查 `@scope` 边界、动态类白名单、`@property` 类型；merge 规则防止类冲突。
4. 运行时：`@container`/`:has()`/`color-mix()` 在浏览器内完成适配，JS 仅负责交互或数据绑定。
5. 反馈：覆盖率/体积监控回写到生成器，调整 tokens 或 layer 顺序。

> 这条链路的目标是「声明意图→生成→约束→运行」，开发者关注 tokens 与交互，而不是手写长链选择器。

## 对现有工具链的启示

- Tailwind/UnoCSS：保留原子类生态，但补充 `@layer`/`@scope` 输出选项，配合容器查询 preset；JIT 应能理解 `@property`/`color-mix()`。
- RSC/小程序场景：通过预编译生成层化 CSS，运行时只使用容器查询/自定义属性，避免 JS 注水。
- 设计系统：tokens 需要类型（color, length, angle），与 `@property` 对齐；AI 生成 prompt 应包含「可用 tokens」「允许的 layer」清单。

## 更多未来方向与落地思考

- 多维适配：容器查询 + 视口查询 + 环境查询（prefers-reduced-motion、HDR/dynamic-range）组合，减少 JS 监听 resize 的需求。
- 层级版本化：把 `@layer` 视作 “样式 API”，为主题/品牌定制留出独立层，避免升级时破坏核心组件层。
- 作用域化 Islands：`@scope` 与路由/微前端边界绑定，配合 `:has()` 处理局部交互，降低全局选择器对不同应用的干扰。
- 类型化 tokens：通过 `@property` 为长度/颜色/角度声明类型，结合 design-token JSON schema，让生成器/AI 在编译期就能发现非法取值。
- CSS Houdini 与动画：自定义属性 + paint/worklet 组合，替代 JS 动画；配合 `view-transition` 等 API，把 UI 过渡交给浏览器管线。
- 生成式护栏：为 AI/脚本提供 “允许的 tokens + 层级 + scope 边界” 的提示词或配置，输出后再用 lint/visual diff 校验，形成闭环。

## 进一步阅读

- https://developer.mozilla.org/en-US/docs/Web/CSS/@scope
- https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Container_Queries
- https://developer.mozilla.org/en-US/docs/Web/CSS/@property
- https://tailwindcss.com/blog/tailwindcss-v4-alpha

---

## Token 化与 Headless 组件阶段

## 要点

- API 与样式解耦的 Headless 组件（Radix、Headless UI、shadcn/ui、reka-ui）+ Tailwind/Uno，让设计 token 可直连类名。
- `cva`/`tailwind-variants` 集中声明 variants/default/compound，配合 `tailwind-merge` 兜底；最利于 AI/脚本生成。
- 适合多品牌/暗色/大规模设计体系；前提是 tokens、lint/merge/评审链到位。
- 代表性包：Primitives（`@radix-ui/react-*`、`@ark-ui/react`、`@zag-js`）、Headless 组件库（`@headlessui/react`）、样式模板化方案（`shadcn/ui`、`reka-ui`、`vaul`），加上 class 构造器（`class-variance-authority`、`tailwind-variants`、`tailwind-merge`）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | API 与样式分离；变体集中；对 AI/自动化友好；跨品牌/主题低成本 |
| 劣势 | 需要维护 token 表与规范；初学者心智负担高；文档/范式建设成本高 |
| 适用 | 需要统一体验、多产品线、多主题/品牌、希望自动化生成 UI 的团队 |
| 不适用 | 极简站点或无设计体系、无法投入规范建设的团队 |

## 什么是 token？什么是 token 化

- **Design Token**：把颜色、间距、圆角、字号、阴影、动效等设计属性抽象成命名变量（如 `color-primary-500`、`radius-lg`），集中管理，作为唯一取值来源。
- **Token 化**：将设计稿中的具体数值（#123456、18px 等）转译为 token 名称，在代码/样式里只引用 token，不写裸值；同时保留映射表与校验链，确保所有取值来自 token。
- **落地方式**：
  - CSS 变量：`:root { --color-primary-500: #2563eb; --radius-lg: 12px; }`，配合 Tailwind `@theme` 或自定义 theme 读取。
  - Tailwind 配置：在 `theme.colors/spacing/radius` 中声明，生成对应原子类。
  - 多主题/多品牌：通过 `data-theme` 或类名切换一组 token 变量，实现暗色/品牌切换而不改组件逻辑。
- **收益**：统一视觉取值，减少随手取值漂移；便于 lint/merge/脚本校验；支持跨品牌/主题的快速切换。
- **注意**：token 只是基石，还需 `cva`/`tailwind-variants` 把 token 编织成变体，再由 Headless 组件消费。

## 代表性包与组合方式

- **Radix Primitives / Ark UI**：提供无样式、可访问性完善的组件原件。

```tsx title="Radix + Tailwind"

export function TabsDemo() {
  return (
    <Tabs.Root defaultValue="code" className="w-full">
      <Tabs.List className="inline-flex gap-2 rounded-lg bg-muted p-1">
        <Tabs.Trigger value="code" className="rounded-md px-3 py-2 text-sm data-[state=active]:bg-card data-[state=active]:shadow">
          代码
        </Tabs.Trigger>
        <Tabs.Trigger value="preview" className="rounded-md px-3 py-2 text-sm data-[state=active]:bg-card data-[state=active]:shadow">
          预览
        </Tabs.Trigger>
      </Tabs.List>
    </Tabs.Root>
  )
}
```

- **Headless UI**：Vue/React 可组合的无样式组件，常与 Tailwind 搭配。

```tsx title="Headless UI + Tailwind"

export function MenuDemo() {
  return (
    <Menu as="div" className="relative inline-block text-left">
      <Menu.Button className="inline-flex items-center gap-2 rounded-lg border px-3 py-2">操作</Menu.Button>
      <Menu.Items className="absolute right-0 mt-2 w-40 rounded-xl border bg-card p-2 shadow-xl">
        <Menu.Item>
          {({ active }) => <button className={`w-full rounded-lg px-3 py-2 text-sm ${active ? 'bg-muted' : ''}`}>编辑</button>}
        </Menu.Item>
      </Menu.Items>
    </Menu>
  )
}
```

- **shadcn/ui / reka-ui 模板化**：基于 Tailwind + `cva`/`tailwind-variants` 预置 class，直接复制到项目。

```tsx title="tailwind-variants 组合"

const badge = tv({
  base: 'inline-flex items-center gap-1 rounded-full px-3 py-1 text-xs font-medium',
  variants: {
    tone: {
      neutral: 'bg-muted text-foreground',
      success: 'bg-emerald-50 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-100',
      danger: 'bg-rose-50 text-rose-700 dark:bg-rose-900/30 dark:text-rose-100',
    },
  },
  defaultVariants: { tone: 'neutral' },
})

export function Badge({ asChild, className, ...props }: { asChild?: boolean } & React.HTMLAttributes<HTMLElement>) {
  const Comp = asChild ? Slot : 'span'
  return <Comp className={cn(badge(props), className)} {...props} />
}
```

##  tokens → variants → primitives 流程（示意）

```mermaid
%%{ init: { "flowchart": { "curve": "basis" } } }%%
flowchart TD
  Tokens["设计 Token: color / space / radius / typography"] --> Factory["cva/tv 工厂: size / variant / state"]
  Factory --> Primitives["Headless / Primitives 组件"]
  Primitives --> UI["业务组件组合"]
  Tokens --> Lint["lint / merge 校验，防止越界取值"]
```

  
    
    Tokens：统一色板/间距/圆角/排版，作为唯一取值来源。
  
  
    
    Factory：用 cva/tv 把尺寸、语义、状态集中声明。
  
  
    
    Primitives/UI：Headless 组件消费变体，组合成业务 UI。
  
  
    
    Lint/Merge：校验取值合法，合并类名，防止越界与冲突。
  

## 示例（Button with cva，React）

```tsx

const button = cva(
  'inline-flex items-center gap-2 rounded-lg border bg-primary px-4 py-2 text-sm text-primary-foreground shadow-sm transition',
  {
    variants: {
      variant: { default: '', outline: 'bg-transparent text-foreground border-border', ghost: 'bg-transparent hover:bg-muted' },
      size: { sm: 'h-8 px-3', md: 'h-10 px-4', lg: 'h-11 px-5' },
    },
    compoundVariants: [{ variant: 'outline', size: 'lg', class: 'shadow-none' }],
    defaultVariants: { variant: 'default', size: 'md' },
  }
)

export function Button({ className, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) {
  return <button className={cn(button(props), className)} {...props} />
}
```

## 对齐建议

- tokens：颜色/间距/圆角/阴影/字号写成 tokens（CSS 变量或 `@theme`），保持「设计稿 → token 名」映射。
- variants：所有状态/尺寸/语义集中到工厂（`cva`/`tv`），业务组件只消费 builder；默认值写死。
- merge：统一使用 `cn`（含 `tailwind-merge`）兜底，避免 class 冲突。
- 资产：记录推荐组合（例如按钮/表单/卡片的标准类名），便于 AI/新人沿用。

---

## Sass / Less 预处理阶段

## 要点

- 变量/混入/函数提升复用度，BEM/OOCSS 更易落地；仍是全局作用域。
- 嵌套与继承易失控，编译体积可能膨胀；设计 token 对齐仍需额外规范。
- 适合有一定复用需求但尚未组件化的团队，或需快速落地主题的中小项目。
- 代表性包：`Sass/SCSS`（社区最强，`node-sass`/`dart-sass` 编译器）、`Less`（Ant Design 时代的主题变量代表）、`Stylus`（函数式写法灵活）、`PostCSS`（通过插件完成 autoprefixer、nesting）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 变量/混入提升复用；工具链成熟；CSS 输出可控 |
| 劣势 | 仍是全局污染；嵌套地狱；主题切换需额外管线 |
| 适用 | 中小型项目、需要少量主题切换或设计稿映射 |
| 不适用 | 需要强隔离/可发布组件库、希望直接对齐 tokens 的项目 |

## 代表性包与常见场景

- **Sass/SCSS**：主流功能最全，配合 `@use`/`@forward` 进行模块化。
- **Less**：变量 + 计算的主题切换（Ant Design `modifyVars`）经典用法；仍然是全局样式。
- **Stylus**：缩进语法 + 函数式 mixin；在 Vue 早期模板中常见。
- **PostCSS 插件链**：`autoprefixer` + `postcss-nesting` 组合，在不迁移到 CSS-in-JS 的情况下获得新语法支持。

```scss title="Sass 模块化 tokens"
// tokens/_color.scss
$primary: #111827;
$muted: #6b7280;

// tokens/_radius.scss
$card-radius: 16px;

// styles/card.scss
@use '../tokens/color' as *;
@use '../tokens/radius' as *;

.card {
  border: 1px solid lighten($primary, 65%);
  border-radius: $card-radius;
}
```

```less title="Less modifyVars 快速主题切换"
// 通过 webpack/vite 调整 modifyVars
lessOptions: {
  javascriptEnabled: true,
  modifyVars: {
    '@primary-color': '#111827',
    '@btn-border-radius-base': '8px',
  },
}
```

```css title="PostCSS 插件链 (postcss.config.js)">
module.exports = {
  plugins: {
    'postcss-nesting': {},
    autoprefixer: {},
  },
}
```

## 示例（Sass + BEM）

```scss
$radius: 16px;
$primary: #111827;
$muted: #6b7280;

.card {
  border: 1px solid lighten($primary, 65%);
  border-radius: $radius;
  padding: 16px;
  &--elevated { box-shadow: 0 10px 30px rgba(0, 0, 0, 0.06); }
  &__header { display: flex; flex-direction: column; gap: 8px; }
}

.eyebrow { font-size: 12px; letter-spacing: 0.1em; color: $muted; }
.btn {
  padding: 10px 16px;
  border-radius: $radius - 4px;
  border: 1px solid $primary;
  background: $primary;
  color: #fff;
  &:hover { background: darken($primary, 5%); }
}
```

## 常见坑与对策

- 嵌套层级：限制在 3 层以内；通过 lint 阻止深层选择器。
- 变量散落：集中 tokens 到单一文件，防止多处色板分叉。
- 产物体积：避免滥用 `@extend` 与全局混入；定期检查编译后大小。
- 迁移路径：提前用 CSS 变量承载 tokens，便于未来切到 Utility-first/组件化。

---

## Raw CSS / BEM / OOCSS

## 要点

- 全局样式 + 命名约定（BEM/OOCSS）降低心智负担，工具链简单。
- 成本：覆盖链条难排查、命名冲突频发，复用依赖团队纪律。
- 适合一次性页面/静态站点或极小体量项目；越过一定规模后维护成本陡增。
- 代表性包：`normalize.css`/`reset.css` 负责基线统一，`Bootstrap 3/4` 带着 "组件 + 全局样式" 的典型模式，`Pure.css`/`Bulma` 以小体积展示了语义化 class 的上限。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 无构建依赖，浏览器直读；类名语义清晰；入门成本低 |
| 劣势 | 全局污染；覆盖顺序难控；难对齐 design token；重复样式多 |
| 适用 | Landing/活动页、小型展示站点；无复杂主题/状态需求 |
| 不适用 | 中大型应用、需要强隔离或多主题的项目 |

## 代表性包与典型用法

- **normalize.css / reset.css**：放在入口，统一不同浏览器的默认样式；之后才叠加自己的命名体系。

```html title="入口引入"
<link rel="stylesheet" href="/static/normalize.css" />
<link rel="stylesheet" href="/static/site.css" />
```

- **Bootstrap 3/4**：全局命名 + 组件样式绑定，适合快速拼页面。

```html title="Bootstrap 卡片"
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@4/dist/css/bootstrap.min.css" />

  
    Bootstrap
    全局 + 组件绑定
    通过 utility 辅助类和组件 class 组合完成 UI。
    <button class="btn btn-dark">查看详情</button>
  

```

- **Bulma / Pure.css**：语义化 class + 轻量体积，适合无需强定制的小站点。

```html title="Bulma 按钮示例"
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css" />

  <button class="button is-dark">Dark</button>
  <button class="button is-outlined is-dark">Outline</button>
  <button class="button is-light">Light</button>

```

## 示例（BEM）

```html
<section class="card card--elevated">
  <header class="card__header">
    Raw CSS
    简单但全局
    命名靠约定，覆盖与复用全靠纪律。
    <button class="btn btn--primary">查看详情</button>
  </header>
</section>

<style>
  .card { border: 1px solid #e5e7eb; border-radius: 16px; padding: 16px; }
  .card--elevated { box-shadow: 0 10px 30px rgba(0,0,0,0.06); }
  .card__header { display: flex; flex-direction: column; gap: 8px; }
  .card__eyebrow { font-size: 12px; letter-spacing: 0.1em; color: #6b7280; }
  .card__title { font-size: 18px; margin: 0; }
  .card__desc { color: #4b5563; font-size: 14px; }
  .btn { padding: 10px 16px; border-radius: 8px; border: 1px solid #111827; background: #111827; color: #fff; }
  .btn--primary:hover { background: #0f172a; }
</style>
```

## 常见坑与对策

- 命名冲突：统一前缀或分块（如 `layout-`/`component-`）。
- 覆盖链条：禁止超过 3 层嵌套；避免 `!important` 堆叠。
- 设计对齐：提前抽出色板/间距变量，即便是 CSS 变量也能减少漂移。
- 可维护性：为组件化迁移预留出口（拆分局部文件，减少跨文件覆盖）。

---

## Utility-first / Tailwind / UnoCSS 阶段

## 要点

- 类名即样式，JIT + content 精准摇树；与设计 tokens/variants 易对齐。
- 生态差异：Tailwind（插件/merge/社区资产） vs UnoCSS（高度自定义、需自养规则）。
- 风险：可读性、class 爆炸、content 过宽、动态类失控；需要 tokens/variants/merge 的约束。
- 代表性包：`Tailwind CSS`（JIT + 官方插件）、`Windi CSS`（早期即时模式）、`UnoCSS`（preset/attributify + 自定义规则）、`twin.macro`（将 Tailwind 写在 CSS-in-JS 内）。

## 优势 / 劣势 / 何时使用

| 项 | 内容 |
| --- | --- |
| 优势 | 低认知切换；JIT 产物小；生态丰富；与 Headless 组合好 |
| 劣势 | 约束缺失时可读性差；动态类膨胀；需 lint/merge/评审配合 |
| 适用 | 高迭代速度、需要设计体系对齐、跨端/多产品线场景 |
| 不适用 | 极简静态站点、无法建立 tokens/规范的团队 |

## 代表性包与用法

- **Tailwind CSS**：官方插件/merge/IDE 提示最完善，适合团队基线。

```js title="tailwind.config.ts"
export default {
  content: ['./src/**/*.{ts,tsx,html}'],
  theme: {
    extend: {
      colors: { brand: '#111827' },
      borderRadius: { xl: '16px' },
    },
  },
  plugins: [require('@tailwindcss/typography'), require('@tailwindcss/forms')],
}
```

- **UnoCSS**：preset + 自定义规则；`attributify` 让属性即类名。

```ts title="UnoCSS 配置 unocss.config.ts"

export default defineConfig({
  presets: [presetUno(), presetAttributify(), presetIcons()],
  rules: [['btn', { padding: '10px 16px', 'border-radius': '8px', background: '#111827', color: '#fff' }]],
})
```

```html title="UnoCSS attributify"
<section grid gap-3 rounded-2xl border p-4 shadow-sm>
  UnoCSS
  Attributify + Preset
  <button btn hover="bg-#0f172a">查看详情</button>
</section>
```

- **twin.macro**：在 styled-components/Emotion 中写 Tailwind，兼顾原子化与 CSS-in-JS 开发体验。

```tsx title="twin.macro"

const Card = styled.section(() => [tw`grid gap-3 rounded-2xl border bg-white/80 p-4 shadow-sm`])

export function TwinDemo() {
  return (
    <Card>
      twin.macro
      Tailwind 写在 CSS-in-JS 里
    </Card>
  )
}
```

##  JIT 摇树流程示意

```mermaid
%%{ init: { "sequence": { "mirrorActors": false } } }%%
sequenceDiagram
  participant Source as "模板源码"
  participant Scanner as "content 扫描"
  participant JIT as "JIT 生成器"
  participant CSS as "精简 CSS 产物"
  Source->>Scanner: "扫描类名（含 cva/tv 静态值）"
  Scanner->>JIT: "传递匹配到的原子类"
  JIT-->>CSS: "生成仅用到的规则"
  CSS-->>Source: "产出 build 结果，摇树完成"
```

  
    
    Scanner：只扫描模板里的静态类名（含 cva/tv 输出），避免 content 过宽。
  
  
    
    JIT：按需生成规则，删除未命中的原子类。
  
  
    
    产物：构建出的 CSS 只保留使用过的类，体积可控。
  

## 示例（Tailwind 基础卡片）

```tsx
export function TailwindCard() {
  return (
    <section className="grid gap-3 rounded-2xl border bg-card/80 p-4 shadow-sm">
      Tailwind
      类名即样式
      JIT + tokens；类名一目了然，摇树后产物小。
      <button className="inline-flex items-center gap-2 rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90">
        查看详情
      </button>
    </section>
  )
}
```

## Tailwind vs UnoCSS（补充要点）

- 生态：Tailwind 拥有 typography/forms/animate 等插件、`tailwind-merge`、丰富的 preset 和组件范式；UnoCSS 更灵活但规则/merge/IDE 提示需自养。
- 类型提示：Tailwind 官方 language-service 覆盖全面；UnoCSS 依赖 preset/插件质量。
- Merge 去重：Tailwind 配合 `tailwind-merge` 规则完善；Uno 默认不处理 class 去重，需要自定义。
- 运行时：Tailwind v4 产物稳定，适配 RSC/SSR；UnoCSS 即时模式极快，适合高度定制。

## 常见坑与对策

- content 过宽：精确到模板目录，避免全局通配导致产物膨胀。
- 动态类：优先 `cva`/`tailwind-variants` 参数化，禁用字符串自由拼接。
- 可读性：建立 tokens/variants/推荐组合，评审时对齐；必要时为复杂关系类加注释。
- 体积：构建后查看 CSS 体积或浏览器 Coverage；必要时开启分析工具。
- 设计稿映射：把常用 spacing/颜色/圆角提炼为设计 token，并在 `cva` 默认值上锁定，避免“随手取值”。

---

## 样式方案的演化

## 要点

- 样式方案从「全局命名」走向「模块化/组件化」再到「原子化」，每一步都在降低耦合与认知成本。
- 原子化 CSS 的价值：更好的可组合性与摇树优化；风险在于约束失效后的 class 泛滥与设计漂移。它不是风口产物，而是长期向「更小粒度、更好约束」演进的结果。
- 多 runtime（Web/RSC/小程序）下，需要把 tokens 抽象到样式方案之外，避免在构建或运行时动态拼类。

> 组件库部分已拆为独立页面：[组件库的演进](/docs/tailwindcss/history/component-evolution)。

##  样式方案时间轴

```mermaid
%%{ init: { "flowchart": { "curve": "basis", "nodeSpacing": 32, "rankSpacing": 24 } } }%%
flowchart TB
  A["2010 · Raw CSS / BEM / OOCSS"]
  B["2013 · 预处理器 Sass/Less，变量/混入，BEM 体系化"]
  C["2015 · CSS Modules，局部作用域"]
  D["2017 · CSS-in-JS（styled-components/Emotion），组件边界 + 运行时成本"]
  E["2020 · Utility-first (Tailwind/Windi/Uno)，JIT、摇树优化、设计 token 对齐"]
  F["2024 · Token/原子类与多 Runtime（Web/RSC/Mini Program）协作"]

  A --> B --> C --> D --> E --> F
```

  
    
    2010：Raw CSS / BEM / OOCSS，语义命名 + 手写层级。
  
  
    
    2013：Sass/Less 变量与混入，BEM 体系化。
  
  
    
    2015：CSS Modules 作用域隔离。
  
  
    
    2017：CSS-in-JS，组件边界 + 运行时成本。
  
  
    
    2020：Utility-first，JIT、摇树、tokens 对齐。
  
  
    
    2024：Token/原子类跨 Web/RSC/小程序协作。
  

### 现场感：几段常见的「升级理由」

- BEM 项目重构时，遇到 `.btn--primary` 在四个文件里被覆盖，且 hover 颜色不一致；引入 Utility-first 后把按钮拆成变体，类名归到 `cva` 工厂，审阅时一眼能看出状态组合。
- CSS-in-JS 方案在 SSR 下首屏注水 60KB，改为 Tailwind + tokens 后，首屏 CSS 控制在 8KB 以内，且通过 `content` 精准扫描避免动态膨胀。
- Mini Program 场景 class 长度有限，原子类 + 预生成模板替换了动态拼接的 style 字符串，稳定性提高，构建速度更快。

## 各阶段优势 / 劣势 / 适用场景

| 阶段 | 核心优势 | 主要劣势 | 适用场景 | 常见坑 & 规避 |
| --- | --- | --- | --- | --- |
| Raw CSS + BEM/OOCSS | 简单直观；命名带语义 | 全局污染、样式覆盖难排查；复用弱 | 小体量页面、低复杂度站点 | 命名规则不统一 → 制定前缀/分块；避免长选择器链 |
| 预处理器（Sass/Less） | 变量/混入/函数提高复用；BEM 更容易落地 | 仍是全局；易出现嵌套地狱；编译体积膨胀 | 需要一定复用，但没有组件边界要求 | 限制嵌套层级；lint 禁止 `#id`/深度选择器；保持色板集中 |
| CSS Modules | 作用域隔离，防止全局污染；类名可组合 | 样式与组件耦合，跨组件复用要额外抽象；难对齐统一 design token | 可发布组件库、需要隔离的中大型项目 | 建立 shared variables 文件；避免在组件内声明全局变量；主题切换需额外管线 |
| CSS-in-JS | 组件边界天然隔离；props 驱动样式；SSR 友好（视库而定） | 运行时开销；编译链复杂；类名可读性差；热更/缓存成本 | 需要强动态样式、主题切换、设计系统与组件强绑定 | 使用零运行时方案（vanilla-extract）或编译模式；监控包体；限定动态样式范围 |
| Utility-first（Tailwind/Uno） | 类名即样式，低认知切换；JIT/摇树；与 tokens 对齐；生态丰富 | 可读性与约束依赖团队规范；content 不精准会膨胀；动态类易失控 | 需要高迭代速度、设计体系对齐、组件组合化的前后端/多端项目 | 建立 tokens/variants 规范；统一 `cn` + merge；禁止字符串拼类；content 精准匹配；保留「推荐组合」文档 |
| Token + Headless 组件（shadcn/ui, reka-ui） | API 与样式解耦；通过 `cva`/`tailwind-variants` 集中管理变体；易被 AI/脚本生成 | 需要自建 design system；无约束时风格漂移 | 需要统一体验的多产品线、希望可插拔主题/品牌的团队 | 维护 tokens 表；评审类名；为 AI 提示加入黑名单/白名单；保留 merge/lint 校验链 |

> 迁移建议：如果已有 CSS Modules/组件库想拥抱原子化，可先将公共 tokens 抽出，再在 Headless 组件上叠加 `cva`/`tailwind-variants`，逐步替换局部样式。

## 深入阅读（按阶段拆分）

- [Raw CSS / BEM / OOCSS](/docs/tailwindcss/history/raw-css)
- [Sass / Less 预处理](/docs/tailwindcss/history/preprocessors)
- [CSS Modules 阶段](/docs/tailwindcss/history/css-modules)
- [CSS-in-JS 阶段](/docs/tailwindcss/history/css-in-js)
- [Utility-first / Tailwind / UnoCSS](/docs/tailwindcss/history/utility-first)
- [Token 化与 Headless 组件](/docs/tailwindcss/history/headless-tokens)
- [生成式 CSS / 原生能力融合](/docs/tailwindcss/history/future-generative-css)

## 阶段代表性包速览与跳转

| 阶段 | 包 | 常见用法 | Demo/图表 |
| --- | --- | --- | --- |
| Raw CSS | normalize.css, Bootstrap, Bulma | 全局命名 + 组件 class | 本页 BEM 例子 + Reset 引入 |
| 预处理器 | Sass, Less, PostCSS, Stylus | 变量/混入、`modifyVars` 主题 | Sass 片段 & PostCSS 插件链 |
| CSS Modules | webpack/Vite modules, Next.js, vanilla-extract | 作用域哈希、零运行时 | 模块化 Card 组件 |
| CSS-in-JS | styled-components, Emotion, JSS, vanilla-extract | 运行时/编译期动态样式 | 主题 Button + 运行时 vs 编译期图 |
| Utility-first | Tailwind, Windi, UnoCSS, twin.macro | JIT 原子类、attributify、宏模式 | Tailwind 卡片 + Uno attributify + JIT 时序图 |
| Headless + tokens | Radix, Headless UI, shadcn/ui, tailwind-variants | tokens → variants → primitives | Radix Tabs、Menu Demo、tokens 流程图 |

## 阶段 Demo：把「方式」落到机制

### Raw CSS / BEM：零构建 + 约定

```html title="index.html"
<link rel="stylesheet" href="/reset.css" />
<section class="card card--elevated">
  Raw CSS
  全局命名
</section>
```

### 预处理器：脚本化编译与 tokens 复用

```json title="package.json"
{
  "scripts": {
    "build:css": "sass src/styles/index.scss dist/index.css --no-source-map && postcss dist/index.css -o dist/index.css",
    "watch:css": "sass --watch src/styles/index.scss:dist/index.css"
  }
}
```

```scss title="src/styles/index.scss"
@use './tokens' as *;
.card { border: 1px solid lighten($color-primary, 65%); border-radius: $radius-lg; }
```

### CSS Modules：编译期隔离 + 组件消费

```ts title="vite.config.ts"
export default { css: { modules: { generateScopedName: '[name]__[local]___[hash:base64:5]' } } }
```

```tsx title="Card.tsx"

export const Card = () => <section className={`${styles.card} ${styles.elevated}`}>CSS Modules</section>
```

### CSS-in-JS：主题运行时 + 编译模式

```tsx title="styled-components + ThemeProvider"

const theme = { primary: '#111827', radius: '12px' }
const Button = styled.button`border-radius: ${({ theme }) => theme.radius}; background: ${({ theme }) => theme.primary};`
export const Demo = () => <ThemeProvider theme={theme}><Button>动态主题</Button></ThemeProvider>
```

### Utility-first：Tailwind + cva 生成变体

```ts title="tailwind.config.ts"
export default { content: ['./src/**/*.{ts,tsx,html}'], theme: { extend: { colors: { brand: '#111827' } } } }
```

```tsx title="components/button.tsx"

const button = cva('rounded-lg px-4 py-2 text-sm font-medium', { variants: { tone: { brand: 'bg-brand text-white' } }, defaultVariants: { tone: 'brand' } })
export const Button = ({ tone = 'brand', ...props }) => <button className={button({ tone })} {...props} />
```

### Token + Headless：tokens 文件 + Headless 组件装饰

```css title="src/styles/tokens.css"
:root { --color-primary: #111827; --radius-lg: 12px; }
[data-theme="dark"] { --color-primary: #e5e7eb; }
```

```tsx title="components/menu.tsx"

const item = tv({ base: 'flex items-center rounded-lg px-3 py-2 text-sm', variants: { active: { true: 'bg-muted text-foreground' } } })
export const MenuDemo = () => (
  <Menu>
    <Menu.Button className="rounded-lg border px-3 py-2">操作</Menu.Button>
    <Menu.Items className="mt-2 w-40 rounded-xl border bg-card p-2 shadow-xl">
      <Menu.Item>{({ active }) => <button className={item({ active })}>编辑</button>}</Menu.Item>
    </Menu.Items>
  </Menu>
)
```

###  决策树：选择样式方案

```mermaid
flowchart TD
  A["团队现状？"] --> B{"需要高度动态/多品牌吗？"}
  B -->|是| C["CSS-in-JS 或 Headless + Tailwind"]
  B -->|否| D{"已有 design tokens？"}
  D -->|有| E["Tailwind / Uno + tokens"]
  D -->|无| F["CSS Modules / Vue scoped 先隔离"]
  C --> G{"关注运行时/SSR 体积？"}
  G -->|是| H["Tailwind + cva/tv，减少运行时"]
  G -->|否| I["styled-components / Emotion 编译模式"]
  E --> J{"生态资产重要？"}
  J -->|重要| K["Tailwind（插件 / merge / 社区资产）"]
  J -->|不重要| L["UnoCSS（更灵活自定义）"]
```

## 原子化 CSS 解决/未解决的问题

- ✅ 解决：
  - 认知负担：类名即样式，无需跳转文件。
  - 漂移与覆盖：减少全局样式泄漏；`content` 精准扫描，摇树删除未用类。
  - 设计对齐：tokens 与 variants 让「设计 → 类名」有映射。
- ⚠️ 风险：
  - 可读性：类名过长、无约束导致审阅困难。
  - 一致性：不同人随意取值，导致色板/间距失控。
  - 体积：动态类或 content 过宽会失去摇树收益。
- 🚫 不推荐使用的场景：
  - 需要强隔离的可发布组件库（可用 CSS Modules/vanilla-extract）。
  - 极简静态站点，对运行时无需求，模板类名冗长反而成本高。
  - 无法建立 design token/规范的团队，原子类易失控。

## 与运行时/平台的适配

- Web/RSC：优先静态生成、`content` 精准匹配 server 侧模板；避免在服务器计算随机类名。
- 小程序/多端：注意 class length 限制；预生成静态类，不依赖动态模板拼接。
- SSR/HMR：Tailwind v4 JIT 足够快；UnoCSS 具更灵活的即时模式，但生态/插件差异需权衡。

---

## 原子化 CSS 专题导览

## 为什么读这份专题

- 原子化 CSS 是工程化的折衷：用小而精的类名替代组件级样式，降低认知和维护成本，同时配合设计 token、variants 与摇树优化。
- Tailwind 的强项在生态：JIT、variants、插件、`tailwind-merge`/`clsx`/`cva`/`tailwind-variants` 组合，以及可直接复用的社区资产（预设、主题、UI 套件）。
- 它不是银弹：缺少约束时会 class 爆炸、可读性差、设计漂移。本专题会给出「少走弯路」的做法。
- AI 友好：原子类是可组合的语料，配合提示模板和 lint/merge 校验，可以让模型安全地产出 UI，并且可被人类审阅。

## 你会获得什么

- 历史与生态：从 Raw CSS → 预处理器 → CSS-in-JS → Utility-first 的关键转折，以及组件库从 Element/AntD 走向 Headless UI/shadcn/ui/reka-ui。
- 方法论：Tailwind 设计理念、与 UnoCSS 的取舍、`tailwind-merge`、`cva`、`tailwind-variants` 的封装策略。
- 最佳实践：设计 token、`data-*` 驱动的 variants、`group/peer/aria` 组合、性能/体积验证、代码评审清单。
- AI 友好工作流：可直接复用的提示模板、常见错误与防护、自动化校验建议。
- Demo：React（shadcn/ui 风格）与 Vue（shadcn-vue/reka-ui 风格）的小型页面，含主题切换、响应式卡片、表单/数据块示例，可作为「让 AI 续写」的基准。

{/* ## 快速命令与讲稿提纲

- 安装依赖：`pnpm install`
- 运行 React Demo：`pnpm --filter react-app dev`；运行 Vue Demo：`pnpm --filter vue-app dev`
- 构建文档：`pnpm --filter website build`（或 `pnpm build:docs` 若存在别名）
- 若需拍照/截图：在对应页面保留 `<!-- screenshot: tailwindcss-{section} -->` 占位

参考提纲（45-60 分钟）：
- 开场（5m）：样式方案为何不断演进，展示时间轴与组件库演进。
- 原子化价值/风险（10m）：解决/未解决的问题 + 不适用场景。
- Tailwind 设计（10m）：JIT、variants、分层、插件与 `tailwind-merge`。UnoCSS 取舍。
- 最佳实践（10m）：tokens、`cva`/`tv`、关系类、性能/体积验证。
- AI 友好（10m）：提示模板、校验链，React/Vue 代码演示。
- Demo & Q&A（10-15m）：React/Vue 实机运行与对照代码。 */}

> 阅读顺序建议：如果你正在做迁移或评审代码，先看「最佳实践」；如果你要说服团队或输出分享，先看「历史与演进」「设计理念与对比」。

## 导航

1. [历史与组件库演进](tailwindcss/history)
2. [Tailwind 设计理念与对比](tailwindcss/tailwind-core)
3. [原子化 CSS 最佳实践](tailwindcss/best-practices)
4. [样式隔离方案与原理](tailwindcss/style-isolation)
5. [AI 友好提示与 Demo 运行指南](tailwindcss/ai-friendly-and-demos)
6. [各样式方案 Demo 与产物对照](tailwindcss/demos)

## React/Vue 代码快速预览

<Tabs>
  <TabItem value="react" label="React (shadcn/ui 风格)">

```tsx

export function Hero() {
  return (
    
      
        Atomic CSS
        让设计系统与类名对齐
        `cva`/`tailwind-variants` 集中声明 variants，`tailwind-merge` 兜底合并，搭配 tokens 保持一致。
        
          <Button>开始体验</Button>
          <Button variant="secondary" className={cn('gap-1')}>
            预览代码
          </Button>
        
      
      
        <pre className="whitespace-pre-wrap">
{`const button = cva('inline-flex items-center px-4 py-2', {
  variants: { intent: { primary: 'bg-primary text-primary-foreground', ghost: 'hover:bg-accent' } },
  compoundVariants: [{ intent: 'primary', size: 'lg', class: 'shadow-lg' }],
})`}
        </pre>
      
    
  )
}
```

  </TabItem>
  <TabItem value="vue" label="Vue (shadcn-vue/reka-ui 风格)">

```html
<script setup lang="ts">

</script>

<template>
  <section class="grid gap-4 rounded-2xl border bg-card/80 p-6 shadow-sm md:grid-cols-2">
    
      Atomic CSS
      组合变体，保持一致
      用 `cva` 或 `tailwind-variants` 宣告变体，再用 `cn`/`twMerge` 兜底。
      
        <Button>开始体验</Button>
        <Button variant="secondary" class="gap-1">预览代码</Button>
      
    
    
      <pre class="whitespace-pre-wrap">buttonVariants({ intent: 'primary', size: 'lg' })</pre>
    
  </section>
</template>
```

  </TabItem>
</Tabs>

---

## tailwind-merge、cva、tailwind-variants 精要

## 要点

- `tailwind-merge` 负责 class 冲突/去重，是安全拼 class 的底座；推荐封装 `cn = twMerge(clsx(...))`。
- `cva`/`tailwind-variants` 把 variants/default/compound 集中声明，输出 class builder，避免状态散落；`tv` 内置 merge + slots，适合多槽组件。
- 闭环：tokens → 原子类/variants → builder → 组件 → content 扫描 → JIT → merge → 产物。

## tailwind-merge：去重与边界

- 定义：一段针对 Tailwind 类名的「冲突解析器」，根据官方生成顺序和自定义配置判断哪些类互斥、保留最后一条有效值。
- 意义：让「后写覆盖前写」成为可预测规则，避免动态组合时出现 `p-4 p-2` 这类冲突导致的随机样式；类名越多越需要去重。也是 shadcn/ui 这类组件库能安全暴露 `className` 扩展点的基石。
- 典型用法：封装 `cn = twMerge(clsx(...))`，组件内部先写好「官方默认」，调用方传入的 `className`/`slot` 覆盖时，`tailwind-merge` 会清理掉冲突类，只留下最后的意图。

### 为什么它是「基石」

- 组件库必须开放 `className` 让消费者定制，如果没有 merge，任何「兜底样式」都可能被调用方的冲突类覆盖，且覆盖关系取决于 Tailwind 内部排序而非调用方意图。
- shadcn/ui 的所有组件都通过 `cn` 暴露覆盖点，`tailwind-merge` 才能保证「库默认 + 用户覆盖」是可预期的；不然需要禁止调用方使用部分类名或写大量 `!important`。
- 对 tokens 自定义（例如新增 `radius-4xl` 或品牌色）时，`tailwind-merge` 也能根据扩展配置正确识别冲突，避免出现「自定义类永远不会覆盖掉默认类」的问题。
- 作用：`p-4 p-2` → `p-2`；自定义 tokens/尺寸时需同步规则。
- 建议：在所有 class 拼接入口统一用 `cn`；对常见自定义（色板、spacing、radius）写额外 merge config 并加用例验证。
- 快测：在 Demo 按钮里故意写 `p-4 p-2`，观察输出；对自定义色板 class 也做覆盖测试。

### 没有 tailwind-merge 时

```tsx

function Button({ size = 'md', className, ...props }) {
  // 难以保证调用方不会传入冲突类（如 px-2），只能靠约定
  const base = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-medium'
  const sizeClass = size === 'lg' ? 'px-4 py-2.5 text-base' : 'px-3 py-2 text-sm'
  return <button className={clsx(base, sizeClass, className)} {...props} />
}

// 使用方
// 这里传了 px-2，最终输出 class 顺序取决于 props 位置，样式不可控
;<Button className="px-2 text-red-600" />
```

#### 示例：生成产物的「顺序陷阱」

Tailwind 会按内部规则排序候选（如 `p-0 → p-1 → p-2 → p-4 ...`），与 class 字符串的顺序无关：

```html
<!-- 期待 p-2 覆盖 p-4，但生成的 CSS 顺序仍是 p-2 在前、p-4 在后 -->
<button class="p-4 p-2 bg-blue-500 bg-red-500">示例</button>
```

```css
/* Tailwind 生成的片段（节选） */
.p-2 { padding: 0.5rem; }
.p-4 { padding: 1rem; } /* 出现在后面，仍然生效，覆盖掉 p-2 */
.bg-blue-500 { background-color: #3b82f6; }
.bg-red-500 { background-color: #ef4444; } /* 同样覆盖蓝色 */
```

即便 class 写成「后者想覆盖前者」，最终仍由 Tailwind 的排序决定，无法满足「调用方最后一项赢」的诉求。

### 引入 tailwind-merge 之后

```tsx

const cn = (...inputs: clsx.ClassValue[]) => twMerge(clsx(...inputs))

function Button({ size = 'md', className, ...props }) {
  const base = 'inline-flex items-center rounded-md px-3 py-2 text-sm font-medium'
  const sizeClass = size === 'lg' ? 'px-4 py-2.5 text-base' : 'px-3 py-2 text-sm'
  return <button className={cn(base, sizeClass, className)} {...props} />
}

// 使用方
// 即便传入 px-2，tailwind-merge 也会保留「最后的有效值」，变为 px-2，行为可预测
;<Button className="px-2 text-red-600" />
```

#### 示例：merge 后的产物

```html
<button class="p-2 bg-red-500">示例</button>
```

```css
.p-2 { padding: 0.5rem; }
.bg-red-500 { background-color: #ef4444; }
```

通过删除冲突类，最终产物只包含用户期望的「最后一份声明」，不再受 Tailwind 内部排序影响。

### shadcn 风格组件的常见模式

```tsx
// utils/cn.ts

export const cn = (...inputs: ClassValue[]) => twMerge(clsx(...inputs))

// components/button.tsx
const base = 'inline-flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium'
const tones = {
  default: 'bg-primary text-primary-foreground hover:bg-primary/90',
  ghost: 'bg-transparent text-foreground hover:bg-accent',
}
const sizes = { sm: 'h-8 px-2.5', md: 'h-10 px-3', lg: 'h-12 px-4 text-base' }

export function Button({ tone = 'default', size = 'md', className, ...props }) {
  return (
    <button
      className={cn(base, tones[tone], sizes[size], className)}
      {...props}
    />
  )
}

// 使用方：随意传入自定义类，默认与覆盖可预测
;<Button tone="ghost" className="px-10 bg-yellow-400 text-black" />
```

在上例中，调用方传入的 `px-10` 会去掉默认的 `px-3/px-4`，`bg-yellow-400` 也会覆盖默认的 `bg-primary`。`tailwind-merge` 让「库的默认 + 用户的覆盖」成为可靠的组合，避免写 `!important` 或约束文档里硬性禁止某些类名，从而成为这类可扩展组件模式的基石。

## cva：轻量变体工厂

```ts

export const badge = cva('inline-flex items-center rounded-md text-xs font-medium', {
  variants: {
    tone: {
      subtle: 'bg-muted text-muted-foreground border border-border',
      brand: 'bg-primary text-primary-foreground',
      danger: 'bg-destructive text-white',
    },
    size: { sm: 'px-2 py-1', md: 'px-2.5 py-1.5' },
  },
  compoundVariants: [{ tone: 'brand', size: 'md', class: 'shadow-sm' }],
  defaultVariants: { tone: 'subtle', size: 'md' },
})
```

- 场景：单槽组件（按钮、Badge、Input 等）；与 `cn` 组合解决冲突。

## tailwind-variants (tv)：内置 merge + slots

```ts

export const card = tv({
  base: 'rounded-2xl border bg-card/80 shadow-sm transition',
  slots: {
    header: 'flex items-center justify-between gap-2',
    body: 'space-y-2 text-sm text-muted-foreground',
    footer: 'flex items-center gap-2',
  },
  variants: {
    tone: { neutral: 'border-border', brand: 'border-primary/40 shadow-lg', subtle: 'border-muted bg-muted/60' },
    interactive: { true: 'hover:-translate-y-0.5 hover:shadow-md' },
  },
  defaultVariants: { tone: 'neutral', interactive: true },
})
```

- 场景：多槽组件（Card、Modal、List item），需要 slots/recipes 与自动 merge。

## cva vs tv 对照

| 项 | cva | tailwind-variants |
| --- | --- | --- |
| Merge | 无内置，需要 `cn` 包装 | 内置 tailwind-merge |
| 多槽 | 不支持 slots | 支持 slots/recipes |
| 心智负担 | 轻，语法简单 | 略重，类型更严格 |
| 适用 | 按钮/Badge 等单槽 | 卡片/模态/多槽组件，设计系统 |

##  从设计到产物（示意图）

```mermaid
%%{ init: { "flowchart": { "curve": "basis" } } }%%
flowchart LR
  Tokens["Design Tokens / @theme"] --> Variants["原子类 + variants"]
  Variants --> Builders["cva / tailwind-variants"]
  Builders --> Components["React/Vue 组件"]
  Components --> Content["content 精准扫描"]
  Content --> JIT["Tailwind JIT 生成按需 CSS"]
  JIT --> Merge["tailwind-merge 去重"]
  Merge --> Output["最终 CSS/HTML 产物"]
```

  
    
    Tokens：色板/间距/半径/排版等设计变量。
  
  
    
    Variants/Builders：用 cva/tv 封装 size、tone、state 等变体。
  
  
    
    Components/Content/JIT：组件消费 builder，content 精准扫描驱动 JIT 生成。
  
  
    
    Merge/Output：tailwind-merge 清理冲突，产出可预期的最终样式。
  

## 实用检查清单

- 所有动态 class 是否经 `cn`（含 `tailwind-merge`）合并？
- 是否存在散落的 `clsx`/字符串拼接 class？是否可迁移到 `cva`/`tv`？
- `variants/defaultVariants/compoundVariants` 是否集中在 builder 文件，业务组件不再拼装状态？
- 自定义 tokens 是否同步到 merge 规则？是否有用例验证覆盖顺序？

---

## shadcn/ui 的出现与意义

## 背景：复制源码，而非安装依赖

- 模式：shadcn/ui 不发布 npm 包，而是提供可复制的源码和 CLI，生成组件文件后由团队自行维护、改造。
- 影响：避免被包版本锁定，组件完全归团队所有；更新节奏、Breaking 变更都变成「你自己合并」，风险可控。
- 底座：Radix UI（无样式、可访问性交互） + Tailwind（视觉）+ `tailwind-merge`（冲突解析）+ `cva`/`variants`（变体），形成清晰的组合范式。

## 核心范式

1) 设计 tokens：通过 Tailwind 主题或 CSS 变量定义颜色、半径、间距。  
2) 变体声明：用 `cva` 或 `tailwind-variants` 管理 `size/tone/state` 等。  
3) merge 兜底：封装 `cn = twMerge(clsx(...))`，所有组件 `className` 都经由 merge。  
4) 可复制：CLI 产出 `Button.tsx` 等源码，直接落在仓库，便于二次定制和代码审查。

## 与其他 Headless UI 的结合

- Radix 不是唯一选项，同样模式可套到 Headless UI、Ark UI、Ariakit、React Aria/Headless、TanStack 状态机等无样式基座上。
- 关键在于：交互/可访问性由基座提供，视觉与变体由 Tailwind + `tailwind-merge` + `cva`/`variants` 接管。换基座时，仅需调整属性映射与状态类名。
- 示例：将 Ark UI 的 `Popover` 包装为 `cn + variants`，或用 Ariakit 的 Dialog 组件配合自定义 tokens，依然保持「复制源码、可改造、可覆盖」的模式。

## 什么是 Headless UI？常见基座与定位

- 定义：只提供交互逻辑与可访问性，不附带样式（或极少样式）的组件/Hook；通过 render props、slots 或原生元素组合让你自行决定 DOM 结构与 class。
- 典型代表：
  - Radix UI：无样式交互原件，搭配任意样式层。
  - Headless UI（Tailwind Labs）：提供 render props/slots 的交互组件。
  - Ark UI / Kobalte / Ariakit：无样式 + 可访问性，适合自定义主题。
  - React Aria / React Stately：Hook 形式提供交互与状态。
  - TanStack Table：表格/数据表逻辑完全 headless，可与任意样式库组合。
  - TanStack Form（原 React Form）：表单状态/校验 Hook，不负责视觉。
- 不算严格 headless 的场景：带默认主题/样式的 UI kits（如部分 reka UI 套件）通常已经封装视觉层，虽可定制但不属于纯 headless 范畴。

## Headless UI 库划分（速查）

- 交互原件型（组件 primitives）：Radix UI、Headless UI、Ark UI、Ariakit、Kobalte —— 提供 DOM 结构/状态机/可访问性，样式全由你决定。
- Hook/逻辑型：React Aria + React Stately（ARIA + 状态）、TanStack Form（表单状态），只暴露 Hook，不负责 DOM。
- 数据逻辑型：TanStack Table（表格/数据表逻辑，渲染自定义），近似纯逻辑层。
- 半 Headless/带样式的 kits：如部分 reka UI 或带主题的 UI 套件，提供默认皮肤但可替换，严格意义上不算纯 headless。

## 组件示例（缩写版）

```tsx
// utils/cn.ts

export const cn = (...inputs: ClassValue[]) => twMerge(clsx(...inputs))

// components/button.tsx

const button = cva(
  'inline-flex items-center gap-2 rounded-md font-medium transition-colors',
  {
    variants: {
      tone: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        ghost: 'bg-transparent text-foreground hover:bg-accent',
      },
      size: { sm: 'h-8 px-2.5 text-sm', md: 'h-10 px-3 text-sm', lg: 'h-12 px-4 text-base' },
    },
    defaultVariants: { tone: 'default', size: 'md' },
  }
)

type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof button>

export function Button({ tone, size, className, ...props }: ButtonProps) {
  return <button className={cn(button({ tone, size }), className)} {...props} />
}
```

- 通过 `cva` 统一管理 `tone/size`，`cn` 确保用户传入的类（如 `px-10`、`bg-yellow-400`）能可预测地覆盖默认值。
- 组件文件在项目内，可随团队规范调整（如换色板、改 radius、增加 slots），而不是等待上游发版。

## 行业意义

- **模板化脚手架**：为 Tailwind 场景提供「可复制源码 + merge + variants」的即插架构，成为大量团队的默认起点。
- **所有权转移**：将组件所有权从包作者转回使用团队，降低依赖风险，方便安全审计与定制化。
- **事实标准**：使 `tailwind-merge` 成为类名冲突解决的默认方案，催生各类 `cn` 封装与自定义 merge 规则。
- **无样式交互的普及**：推广了「Radix 等无样式交互 + 原子化样式」的组合，证明无需高度封装也能快速产出高可用组件。
---

> 想要深挖「merge 解决什么问题」？见「[tailwind-merge、cva、tailwind-variants 精要](./merge-and-variants)」章节。

---

## 样式隔离方案与原理

## 什么时候需要隔离

- 微前端/Widget/站外嵌入：宿主可能有全局 reset 或 UI 库，必须避免互相覆盖。
- 可发布组件库：希望类名可读但不污染全局，或交付「带样式的组件」给第三方。
- 多团队共用容器：同一页面叠加多套样式（营销区、业务区）时，需要给各自套壳。

> 大部分普通页面无需额外隔离；优先保证 tokens、variants、一致的 class 习惯即可。

## 方案速览

- 命名空间：`prefix` + `important`；选择器优先级隔离，最轻量但不改变层叠本质。
- 编译期哈希：CSS Modules/vanilla-extract；类名重写，天然不污染全局。
- 作用域容器：`data-*` + `:where` / `@scope`；为局部 DOM 套壳，提高特定区域优先级。
- Vue `scoped`：编译时给选择器自动加 `data-v-*`，局部生效。
- Shadow DOM / iframe：浏览器级边界；最强隔离，但需在边界内独立注入样式。
- preflight 控制：关闭/改写 base，避免 reset 污染宿主；常与以上方案组合。

## 命名空间（Tailwind prefix + important）

- **原理**：给所有生成类名加前缀（如 `tw-btn`），并通过 `important: '#app'` 或 `[data-scope=root]` 提升选择器优先级，减少宿主样式覆盖。
- **配置示例**：

```ts
// tailwind.config.ts
export default {
  prefix: 'tw-',
  important: '[data-scope=widget]', // 或 '#app'
  content: ['./src/**/*.{tsx,vue,html}'],
}
```

- **适用**：微前端、第三方嵌入、只需「不被覆盖」的场景。
- **注意**：仍是全局样式，宿主的 `!important` 仍可能干扰；preflight 仍会影响宿主（可关闭）。

## 编译期哈希（CSS Modules / vanilla-extract）

- **原理**：构建时把类名重写为哈希，JS 通过映射引用，默认不泄漏到全局；Tailwind 类可以在 `.module.css` 中用 `@apply` 复用。
- **示例（CSS Modules）**：

```css
/* card.module.css */
.card {
  @apply rounded-xl border bg-card/80 p-4;
}
```

```tsx

export function Card() {
  return 隔离的卡片
}
```

- **适用**：可发布组件库、中大型应用，希望「类名可读 + 不污染全局」。
- **注意**：跨组件复用 tokens 要单独导出变量；主题切换需额外变量管线。

## Vue `<style scoped>`

- **原理**：SFC 编译器为当前文件的元素和样式选择器都加上 `data-v-xxxx`，样式仅作用于本组件渲染出的 DOM。
- **示例**：

```html
<template>
  <section class="card">
    {{ title }}
  </section>
</template>

<style scoped>
.card {
  @apply rounded-xl border bg-card/80 p-4;
}
</style>
```

- **产物**：模板生成的节点带 `data-v-xxxx`，CSS 选择器编译为 `.card[data-v-xxxx]`。
- **适用**：Vue SFC 局部隔离，尤其是中小组件或局部定制。Tailwind 原子类可直接写在模板，也可在 scoped 样式里 `@apply`。
- **注意**：
  - 需要跨组件的全局样式用 `:global(.class)` 包裹；第三方组件需显式穿透（`::v-deep`）。
  - scoped 不重写类名本身，若要避免外部覆盖，可与 `prefix`/命名空间组合。

## 作用域容器（data-* + :where / @scope）

- **原理**：在根节点加标识，再用强选择器把样式限定在此容器内；`:where` 不增加特异性，便于覆盖；`@scope` 是未来方案（渐进支持）。
- **示例**：

```css
:where([data-scope=mini]) .card {
  @apply rounded-xl border bg-card/80 p-4;
}
```

```html
<section data-scope="mini">
  局部作用域
</section>
```

- **适用**：在宿主页面局部注入样式，或需要多套区域并存。
- **注意**：仍共用同一张 CSS，需手动管理作用域选择器；与 `prefix`/哈希可组合。

## Shadow DOM / iframe

- **原理**：利用浏览器原生隔离边界，Shadow DOM/iframe 内的样式默认不影响外部。
- **实现要点**：
  - Shadow DOM：在 Web Component 内注入 Tailwind 产物（可内联 `<style>`）；注意构建时把 CSS 携带进入组件。
  - iframe：在子页面独立引入 Tailwind 产物；通信/事件需额外桥接。
- **适用**：强隔离要求的 Widget、广告位、跨团队微前端。
- **注意**：每个边界都需要单独注入样式，打包与运行时体积可能增加；预渲染/SSR 时需处理样式注入。

## preflight 控制（可选组合）

- **原理**：关闭或局部启用 Tailwind preflight，避免全局 reset 影响宿主。
- **做法**：
  - 在 `tailwind.config.ts` 配置 `corePlugins: { preflight: false }`，或仅在特定入口引入 `@tailwind base;`。
  - 在组件库中不引入 preflight，让宿主自行决定全局 reset。
- **适用**：可发布组件库、微前端、与现有 UI 库共存时。

## 选择建议

- 嵌入第三方页面：`prefix` + `important` 起步；若宿主样式复杂，再加作用域容器。
- 组件库：优先 CSS Modules/vanilla-extract（编译期哈希），可关闭 preflight。
- Widget/广告位/微前端：Shadow DOM 或 iframe 提供最强隔离，视体积和运行时成本选择。
- 需要渐进策略：先用命名空间和 preflight 控制，确认仍有冲突再升级到容器/Shadow DOM。

---

## Tailwind 设计理念

## Tailwind 本质是什么

- 它是一个“把设计语义压平成原子类，再在组件里组装回语义”的流水线。
- 入口是设计 token（色板、间距、圆角、字号），中段是 JIT 按 content 生成类，出口是组件接口用 variants/merge 把类重新打包。
- 目标是：样式可组合、可控，切换主题或品牌时只改 token，组件 API 依旧可读。

**Demo（整体串联）**

```ts
// tailwind.config.ts
export default {
  content: ['./src/**/*.{tsx,jsx,html}'],
  theme: {
    extend: {
      colors: { brand: { 50: '#f1f5ff', 500: '#3b82f6' } },
      spacing: { 3.5: '0.875rem' },
      borderRadius: { pill: '999px' },
    },
  },
  plugins: [require('@tailwindcss/typography')],
}
```

```tsx
// src/components/Button.tsx

const button = tv({
  base: 'inline-flex items-center justify-center font-medium transition-colors',
  variants: {
    tone: {
      primary: 'bg-brand-500 text-white hover:bg-brand-500/90',
      ghost: 'bg-transparent text-brand-500 hover:bg-brand-50',
    },
    size: { md: 'h-10 px-4 rounded-pill', lg: 'h-11 px-5 rounded-pill text-base' },
  },
  defaultVariants: { tone: 'primary', size: 'md' },
})

export function Button({ tone, size, className, ...props }) {
  return <button {...props} className={button({ tone, size, class: className })} />
}
```

## 入口：设计语义的单一来源

- 先把设计值写成 token（CSS 变量或 `@theme`），Class 只引用 token，不直接写裸值。
- 约束梯度和命名，避免随便一个数字就进主题；换品牌/暗黑只动这份 token。
- 保证“设计稿和 Tailwind 主题是一份真相”，更新 token 时同步配置。

**Demo：token 定义**

```ts
// tailwind.config.ts 片段
export default {
  theme: {
    extend: {
      colors: {
        brand: { 50: 'var(--brand-50)', 500: 'var(--brand-500)' },
      },
      spacing: { 3.5: 'var(--space-3_5)' },
      borderRadius: { pill: 'var(--radius-pill)' },
    },
  },
}
```

```css
/* src/styles/theme.css */
:root {
  --brand-50: #eef2ff;
  --brand-500: #4f46e5;
  --space-3_5: 0.875rem;
  --radius-pill: 999px;
}
```

## 中段：Tailwind 的生成逻辑

- **JIT + content**：扫描模板只生成用到的类；content 越精准，产物越瘦，动态拼接要收敛。
- **@layer**：`base/components/utilities` 管覆盖关系，`@apply` 只在同层或下层用，冲突先用 variants 解决。
- **Variants/关系类**：`md:`、`hover:`、`group-`、`peer-`、`aria-`、`data-` 覆盖常见状态，深度别乱堆。
- **插件**：官方插件覆盖常用模式，自定义插件把你们的设计规则翻译成类。

**Demo：content 精准 + 局部 @layer**

```ts
// tailwind.config.ts 片段
export default {
  content: ['./src/app/**/*.{tsx,jsx}', './src/pages/**/*.{tsx,jsx}'],
  plugins: [],
}
```

```css
/* src/styles/components.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .card {
    @apply rounded-xl border border-slate-200 bg-white shadow-sm;
  }
  .card-title {
    @apply text-lg font-semibold text-slate-900;
  }
}
```

```tsx
// src/app/Card.tsx
export function Card({ title, children }) {
  return (
    
      {title}
      {children}
    
  )
}
```

**Demo：关系类和状态类**

```tsx
// src/components/Nav.tsx
export function Nav() {
  return (
    <nav className="flex items-center gap-4">
      <button className="relative group px-3 py-2 text-sm font-medium text-slate-600 hover:text-slate-900">
        Home
        
      </button>
      <button className="px-3 py-2 text-sm text-slate-600 data-[active=true]:text-brand-600 data-[active=true]:font-semibold">
        Docs
      </button>
    </nav>
  )
}
```

**Demo：自定义插件扩展一个工具类**

```ts
// tailwind.config.ts 片段

export default {
  // ...
  plugins: [
    plugin(({ matchUtilities, theme }) => {
      matchUtilities(
        {
          'grid-auto-fill': (value) => ({
            gridTemplateColumns: `repeat(auto-fill, minmax(${value}, 1fr))`,
          }),
        },
        { values: theme('spacing') },
      )
    }),
  ],
}
```

```tsx
// 使用自定义工具类

  {/* 自动填充列，最小 12rem */}

```

## 出口：组件重新长出语义

- 用 `cva` 或 `tailwind-variants(tv)` 定义组件的尺寸、色板、状态、slot，不要直接暴露一长串类。
- 用 `tailwind-merge` 收尾，防止外部 class 无声覆盖核心样式。
- 组件 API 保持克制，只留必要的开关和插槽，既能扩展又不失读。

**Demo：用 tailwind-variants 简化 variants**

```tsx
// src/components/Badge.tsx

const badge = tv({
  base: 'inline-flex items-center gap-1 rounded-full font-medium',
  variants: {
    tone: {
      success: 'bg-emerald-50 text-emerald-700 ring-1 ring-emerald-100',
      warning: 'bg-amber-50 text-amber-700 ring-1 ring-amber-100',
    },
    size: { sm: 'px-2 py-1 text-xs', md: 'px-3 py-1.5 text-sm' },
  },
  defaultVariants: { tone: 'success', size: 'sm' },
})

export function Badge({ tone, size, className, ...props }) {
  return 
}
```

> 延伸阅读：
> - [Tailwind vs UnoCSS 对比](./tailwind-vs-unocss)
> - [tailwind-merge、cva、tailwind-variants 精要](./merge-and-variants)

---

## Tailwind vs UnoCSS 对比

## 要点

- Tailwind 提供「开箱即用」的 preset、插件、`tailwind-merge`、IDE 支持和社区范式；UnoCSS 提供高度可定制的 rules/variants/preset，但 merge/提示需自养。
- 选择标准：是否要复用社区资产、是否有资源维护规则库、对运行时/编译速度的需求、是否需要极度自定义的类名语义。

## 决策表（精简版）

| 维度 | Tailwind | UnoCSS |
| --- | --- | --- |
| 生态/社区 | 官方插件 + 大量社区 preset/组件范式，`tailwind-merge` 成熟 | rule/variant 任意扩展，高度灵活；预设较少，需要自养 |
| 类型提示 | 官方 language-service，IDE 友好 | 依赖 preset/插件质量，需额外配置 |
| Merge 去重 | `tailwind-merge` 针对 Tailwind 语义完善 | 默认不做去重，需自写或引入规则 |
| 运行时/JIT | v4 JIT 稳定，RSC/SSR 产物成熟 | 即时模式极快，自定义自由；规则库越大越需维护 |
| 迁移/资产 | 现成组件库（shadcn/ui、reka-ui）、设计体系示例丰富 | 灵活性高，迁移成本取决于自建规则与团队习惯 |

## 什么时候选 Tailwind？

- 不想维护 merge/variant/IDE 提示规则，倾向「拿来即用」。
- 需要快速复用社区资产、Preset、组件库（shadcn/ui、reka-ui 等）。
- 关注 RSC/SSR 稳定性、插件完备度，或需要让外部协作者迅速上手。

## 什么时候选 UnoCSS？

- 希望完全自定义类名语义（甚至 DSL），或已有内部 preset 库。
- 产物/规则必须极度可控（小程序/低码等），团队可维护规则和 merge 逻辑。
- 需要极快的即时模式，能接受自行实现去重/类型提示。

## 集成/实践差异

- IDE：Tailwind 语言服务即插即用；Uno 需根据 preset 配置提示插件。
- Merge：Tailwind 配 `tailwind-merge`，遇自定义 tokens/尺寸需更新规则；Uno 默认不去重，需要自写或组合。
- content 扫描：两者都需精准 content，Tailwind v4 JIT 对 SSR/RSC 产物更成熟；Uno 自定义时也要防止通配放大产物。
- 插件链：Tailwind 官方 typography/forms/animate 等即用；Uno 插件生态较少但可自由拼接规则。

## 简易选择流程（文本版）

1) 是否要复用现成组件/范式？要 → Tailwind；无所谓 → 继续。
2) 是否有维护规则库的人力？没有 → Tailwind；有 → 继续。
3) 是否需要极短类名/DSL？需要 → UnoCSS；不需要 → Tailwind。
4) 是否首屏/产物极限压缩并可自管规则？是 → UnoCSS；否则 Tailwind。

## 常见坑与对策

- Tailwind：content 过宽、动态类膨胀 → 收紧扫描范围，使用 `cva/tv` 参数化；自定义 tokens 记得更新 `tailwind-merge` 规则。
- UnoCSS：规则/merge/提示需要自养 → 建 preset 仓库 + merge 规则；对 DSL 做 lint，避免团队分叉。
- 两者：关系类嵌套过深可读性差 → 约束 `group/peer/aria/data` 深度；保持 tokens 映射表。

---

## Tailwindcss 原子类维护指南


## 前言

很多开发者，看到 `Tailwindcss` 的写法，或者初步使用它的时候，第一感觉可能就是 `写是真的爽，维护火葬场`。

诚然，软件工程中没有银弹，原子化有原子化的问题，但这不意味着像 `Tailwindcss`/`Unocss` 这类工具背后的原子化 `CSS` 思想本身没有价值。

最起码，原子化 `CSS` 在一定程度上帮助我们解决了: 类的命名，复用，以及迁移的问题，甚至也能避免了一定程度上的样式污染。

但是这似乎也带来了代码冗余，可读性差的问题。所以接下来的内容就是来帮助大家更好的认识，和维护 `Tailwindcss` 原子类。

## 语义化 CSS

首先要声明的是，原子化 `CSS` 和内联 `CSS` 一点关系都没有！内联 `CSS` 的优先级更高，但是复用性，可维护性要差很多。

其次 原子化CSS 不是绝对意味着一个 `class` 对应着一条CSS声明(`Declaration`)，比如 `w-0` 对应 `width: 0px;`

但是 `line-clamp-2` (效果为文字超过2行显示 `...` ) 这类一个就对应多个`CSS` 声明:

```css
.line-clamp-2{
  overflow: hidden;
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 2;
}
```

所以原子化 `CSS` 中的原子化三个字，实际上指代的是 `CSS` **语义上** 效果的原子化。

## 本质

就本质上而言，其实不论是 `Tailwindcss` 还是 `Unocss`，你都可以把它们想象成一个漏斗，它们从你编写的代码中，通过正则，匹配到符合规则的字符串，然后再生成对应的 `CSS`，就这么简单。

其中，`Tailwindcss` 大部分时候是作为 `postcss` 插件来使用的，它可以和众多 `postcss` 插件很好的配合起来使用。

而 `Tailwindcss` 中的 `@tailwind` 指令，本质上也就是把当前 `@tailwind` 所在文件所属的 `Tailwindcss` 上下文中的 `base`,`components`,`utilities` 这些 `layer` 依次展开罢了。

所以你在一个文件里这样写:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
/* 再写一遍 @tailwind 会导致重复展开，造成大量的代码冗余 */
@tailwind base;
@tailwind components;
@tailwind utilities;
```

是没有意义的行为。

但是假如你通过 `@config` 指令，给不同CSS文件指定 `tailwindcss` 配置文件，类似于:

```css
/* app.css 文件, 应用全局的 tailwind.config.js */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* prose.css 文件,应用当前文件下的 tailwind.prose.config.js */
@config "./tailwind.prose.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;
```

那么，这种一个项目，多 `tailwindcss` 配置，多 `tailwindcss` 上下文的方式，将给你带来很大的自由性。

## 类名冗余问题

类名冗余可能是我们使用 `Tailwindcss` 中经常遇到的问题，比如下面这段 `HTML`:

```html

  
    <input placeholder="Email" class="w-full rounded-lg border border-gray-300 bg-white px-4 py-3 focus:outline-none focus:ring-2 focus:ring-gray-700 focus:ring-offset-2 focus:ring-offset-gray-100" />
    <label class="flex cursor-pointer items-center justify-between p-1">
      Accept terms of use
      
        <input type="checkbox" class="peer h-6 w-12 cursor-pointer appearance-none rounded-full border border-gray-300 bg-white checked:border-gray-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-900 focus-visible:ring-offset-2" />
        
      
    </label>
    <label class="flex cursor-pointer items-center justify-between p-1">
      Submit to newsletter
      
        <input type="checkbox" class="peer h-6 w-12 cursor-pointer appearance-none rounded-full border border-gray-300 bg-white checked:border-gray-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-900 focus-visible:ring-offset-2" />
        
      
    </label>
    <button class="inline-block cursor-pointer rounded-md bg-gray-700 px-4 py-3.5 text-center text-sm font-semibold uppercase text-white transition duration-200 ease-in-out hover:bg-gray-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-700 focus-visible:ring-offset-2 active:scale-95">Save</button>
  

```

这段代码看着看着就晕了，虽然你可以通过 `class` 很直观的了解到了每个元素的样式，但是数量一多，理解成本还是会指数级上升的。

为了缓解这个问题，`Windicss` / `Unocss` 还设计了 [Attributify 模式](https://unocss.dev/presets/attributify#attributify-mode)，使得它们可以依据属性进行分组归类，使得原子化类显得非常直观:

```html
<button
  bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
  text="sm white"
  font="mono light"
  p="y-2 x-4"
  border="2 rounded blue-200"
>
  Button
</button>
```

而且 `Unocss` 还利用它能够在编译时，改变用户代码的能力，构建了许多转化语法糖，比如 `transformer-variant-group`:

```html

```

这些在一定程度上，都能缓解类名冗余的问题，但是无法解决这个问题。

那么，在 `Tailwindcss` 遇到这样的问题，应该如何处理呢？

## 最简单方式: `@apply` 提取

[`@apply`](https://tailwindcss.com/docs/functions-and-directives#apply) 是 `Tailwindcss` 里的一个 `CSS` 指令，它可以把多个原子类给合并到一个你自定义的 `CSS` 节点中。

而且，写法上它也遵从 `HTML` 里的写法。你可以很容易的从 `HTML` 中复制你的原子类到 `CSS` 中，再把它们提取成一个单独的类。

```css
@layer components {
  /* 使用 utilities 里的 inline-flex-center */
  .btn {
    @apply inline-flex-center font-bold py-2 px-4 rounded cursor-pointer;
  }
  /* 使用 components 里的 btn */
  .btn-pink {
    @apply btn bg-pink-600 hover:bg-pink-900 text-white;
  }
}

@layer utilities {
  .inline-flex-center {
    @apply inline-flex items-center justify-center;
  }
}
```

效果如下所示:

<button class="btn">btn</button>
<button class="btn-pink">btn-pink</button>

这样，通过提取和组合，我们可以对原子类进行更高程度上的封装，值得一提的是 `Tailwindcss` 中最流行的 UI 框架: `daisyUI` 原理上也是类似的，不过它进行了进一步的处理和预提取，并最终把它们封装成了一个 `Tailwindcss` 插件罢了。

最终，我们把大量的原子化类，进行提取组合，并最终提炼出了原子化的CSS组件 `card`,`label`,`btn`,`input`组件，那么上面的 `HTML` 就被改造成了:

```html

  
    <input placeholder="Email" class="input input-bordered" />
    <label class="label cursor-pointer">
      Accept terms of use
      <input type="checkbox" class="toggle" />
    </label>
    <label class="label cursor-pointer">
      Submit to newsletter
      <input type="checkbox" class="toggle" />
    </label>
    <button class="btn btn-neutral">Save</button>
  

```

此为最简单，最直接的方式去减小类名的冗余程度，但是这种方式也存在一定的缺陷。比如 `@apply` 这种本质上还是基于 `CSS AST` 的，用得多会有性能问题，另外智能提示也不友好。

所以刚开始可以这样使用，到出现性能问题的时候，我们就需要进行更高一部分的封装: 提炼成 Tailwindcss 插件

## 提炼成 Tailwindcss 插件

`Tailwindcss` 官方文档实际上希望我们把样式，提炼成 [Tailwindcss Plugin](https://tailwindcss.com/docs/plugins)

这样做有许多的好处，比如智能提示友好，性能也比 `@apply` 要高。

它的编写方式也非常简单:

```js
const plugin = require('tailwindcss/plugin')

module.exports = {
  plugins: [
    plugin(function({ addUtilities, addComponents, e, config }) {
      addUtilities({
        '.content-auto': {
          'content-visibility': 'auto',
        },
        '.content-hidden': {
          'content-visibility': 'hidden',
        },
        '.content-visible': {
          'content-visibility': 'visible',
        },
      })
    }),
  ]
}
```

其中 `addUtilities`/`addComponents`/`matchUtilities`/`matchComponents` 这些函数都是用来添加对应的样式到 `tailwindcss` 中。

它们参数中，添加的 `CSS` 对象遵从 [`CSS-in-JS 语法`](https://tailwindcss.com/docs/plugins#css-in-js-syntax)。

幸运的是，我们无需重新编写代码，便可以直接把之前 `@apply` 部分的代码，转化成 `CSS-in-JS` 对象。这一切都只需要我们用到 [`postcss-js`](https://github.com/postcss/postcss-js) 这个工具。

[`postcss-js`](https://github.com/postcss/postcss-js) 作为 `postcss` 生态的组成部分，它能够解析 `CSS-in-JS` 对象，同样它也能够把 `postcss` 解析的 `AST` 转化成 `CSS-in-JS` 对象。

所以它自然可以把 `CSS` 字符串，直接转化成 `CSS-in-JS` 对象。这正是我们想要达到的效果。大体的执行脚本如下:

```js
const postcss = require('postcss')
const path = require('path')
const fs = require('fs')
const tailwindcss = require('tailwindcss')
const postcssJs = require('postcss-js')

async function main () {
  const { root } = await postcss([
    tailwindcss()
  ]).process('@tailwind components;' + `@layer components{
    .btn{
      @apply inline-block cursor-pointer rounded-md bg-gray-700 px-4 py-3.5 text-center text-sm font-semibold uppercase text-white transition duration-200 ease-in-out  focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 active:scale-95;
    }
    /* more... */
  }`,
    {
      from: undefined
    })
  fs.writeFileSync(path.resolve(__dirname, './output.json'), JSON.stringify(postcssJs.objectify(root)), 'utf8')
}

main()
```

对应的 `tailwind.config.js` 添加 `raw` 来提取 `btn` 类。

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [{
    raw: 'btn'
  }],
}

```

当然这是保存到本地磁盘的方式，接着我们编写的 `Tailwindcss Plugin` 只需要去引用这样的对象，把它们作为参数添加到 `addUtilities`/`addComponents` 中，即可正常使用。

例如这样的生成结果为:

```json
{
  ".btn": {
    "display": "inline-block",
    "cursor": "pointer",
    "borderRadius": "0.375rem",
    "--tw-bg-opacity": "1",
    "backgroundColor": "rgb(55 65 81 / var(--tw-bg-opacity))",
    "paddingLeft": "1rem",
    "paddingRight": "1rem",
    "paddingTop": "0.875rem",
    "paddingBottom": "0.875rem",
    "textAlign": "center",
    "fontSize": "0.875rem",
    "lineHeight": "1.25rem",
    "fontWeight": 600,
    "textTransform": "uppercase",
    "--tw-text-opacity": "1",
    "color": "rgb(255 255 255 / var(--tw-text-opacity))",
    "transitionProperty": "color, background-color, border-color, text-decoration-color, fill, stroke, opacity, box-shadow, transform, filter, backdrop-filter",
    "transitionDuration": "200ms",
    "transitionTimingFunction": "cubic-bezier(0.4, 0, 0.2, 1)"
  },
  ".btn:focus-visible": {
    "outline": "2px solid transparent",
    "outlineOffset": "2px",
    "--tw-ring-offset-shadow": "var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color)",
    "--tw-ring-shadow": "var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color)",
    "boxShadow": "var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow, 0 0 #0000)",
    "--tw-ring-offset-width": "2px"
  },
  ".btn:active": {
    "--tw-scale-x": ".95",
    "--tw-scale-y": ".95",
    "transform": "translate(var(--tw-translate-x), var(--tw-translate-y)) rotate(var(--tw-rotate)) skewX(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))"
  }
}
```

不过这种方式其实也完全可以更进一步，接下来进入下一个章节: `postcss` 预生成产物。

## postcss 预生成产物

其实在上一章中，我们已经使用到了一些预先生成的思想了。

毕竟 `tailwindcss` 本身不过是个 `postcss` 插件，我们自然可以通过编写脚本的方式，预先的把 `CSS` 先生成出来，直接交给项目进行使用的。

比如我们要从 `utilities` 提炼出一些 `flex` 相关的工具类出来，那么我们就可以写一段脚本:

```js
const path = require('path')
const fs = require('fs')
const postcss = require('postcss')
const tailwindcss = require('tailwindcss')

async function main () {
  const { css } = await postcss([
    tailwindcss()
  ]).process('@tailwind utilities',
    {
      from: undefined
    })
  fs.writeFileSync(path.resolve(__dirname, './output.css'), css, 'utf8')
}

main()
```

对应的 `tailwind.config.js` 配置:

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [{
    raw: 'flex flex-1 flex-none flex-auto flex-initial'
  }],
}
```

生成的 `output.css` 产物

```css
.flex {
    display: flex
}
.flex-1 {
    flex: 1 1 0%
}
.flex-auto {
    flex: 1 1 auto
}
.flex-initial {
    flex: 0 1 auto
}
.flex-none {
    flex: none
}
```

所以按照这种方式，我们也可以把之前那些 `@apply` 直接复制过来，进行处理，生成出 `CSS`，交给项目来进行使用。同样也能通过这种方式来提炼出 `CSS` 组件。或者把插件里面的 `CSS` 代码，比如 `daisyUI` 里面的样式给 “倒出来”。

## `Unocss` 对比 `Tailwindcss`

`Unocss` 相比 `Tailwindcss` 强大之处，在于 `Tailwindcss` 仅仅只是一个 `postcss` 插件，而 `Unocss` 不是。

`Tailwindcss` 功能简单到，它只是从我们的源代码 `(content)` 中，提取到字符串，然后去生成 `CSS` 节点。

而 `Unocss` 更多时候作为一个打包插件去使用，它可以复用我们打包的产物，并从里面进行提取字符生成 `CSS` 节点，甚至它有能力去修改我们的代码 `(transformer)`。这样的能力 `Tailwindcss` 是不具备的，这也是 `Unocss` 快且功能丰富的原因。

不过单纯这样比较是没有意义的，就像名义上 `Unocss` 快是因为它不用解析 `AST`，但是你一旦想用到 `@apply` 这样的 `directives` 功能，`Unocss` 也不可避免的去使用 `css-tree` 去解析和操纵 `AST`。而这个功能是作为 `postcss` 插件的 `Tailwindcss` 内置的，而 `Unocss` 需要额外的包去实现。

所以比较公平的比较方式，应该是用 `Unocss` 的 `postcss` 插件来和 `Tailwindcss` 做比较。

不过，作为 `Windi CSS` 思路继承者的 `UnoCSS`，在原子化 `CSS` 各个方面都做的更加极致也是不争的事实。而且由于作者 `antfu` 在国内国外的高人气，也吸引了许多志同道合的开发者，积极的为 `UnoCSS` 做贡献，使得生态也生机勃勃，未来可期，真是羡煞旁人啊!

而 `Tailwindcss` 作为一个成功商业化的开源产品，虽然不如 `UnoCSS` 激进，但出的比较早，相对来说生态更丰富，使用人数更多一些，相对应的前人踩过的坑，解决方案也完备一些，而且有公司和资金支持，理论上不会烂尾。

所以希望 `Unocss` 多为我们探索更多原子化的极限，也希望 `Tailwindcss` 多争点气，虚心多学习学习别人的优势。

## More

更多的方法论 Coming Soon...

---

## 旧有uni-app项目升级webpack5指南


:::caution
目前 `uni-app` 默认创建的 `vue2` 项目,已经全面使用 `@vue/cli-service@5` 了(2023-10)，所以目前正常升级即可，本指南废弃! 留作归档处理

使用 uni-app vite vue3 的开发者可以忽略此指南
:::

由于目前 `uni-app` `hbuilderx`和`cli`默认创建的 `vue2` 项目，还是使用的 `@vue/cli-service@4`

为了使用更先进更有生产力的 `webpack5` 和 `postcss8` 我们必须要升级到 `@vue/cli-service@5`

那么旧有的老项目应该如何升级呢？

### 1. 升级 `@dcloudio/*` 相关的包

在项目根目录，执行:

```bash npm2yarn
npx @dcloudio/uvm alpha
```

然后选择 `y` 后，出现提示，选择你项目使用的包管理器，运行即可。

此时你所有的 `@dcloudio/*` 相关的包，被升级到了 `2.0.2-alpha-xxxxxxxxxxxx` 的版本。

### 2. 升级 `@vue/cli-*` 相关的包

使用你的包管理器，升级 `@vue/*`,`@vue/cli-*` 相关的包到 `5.x` 版本。

```json
{
  "@vue/babel-preset-app": "^5.0.8",
  "@vue/cli-plugin-babel": "~5.0.8",
  "@vue/cli-plugin-typescript": "5.0.8",
  "@vue/cli-service": "~5.0.8",
}
```

### 3. 升级你所有的 `webpack` `plugin` 和 `loader`

由于你使用了最新版本的 `webpack` 你可以把那些相关的包，升级到最新的版本，

比如 `sass-loader`, `copy-webpack-plugin` 等等

而且由于你使用了 `5.x` 版本的 `@vue/cli`，里面默认依赖了 `postcss8`

所以你也按需应该升级一下你所依赖的 `postcss` 插件版本。

### 4. 配置文件升级

比如 `babel.config.js` 这个就需要修改，[参考代码](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/blob/main/demo/uni-app-webpack5/babel.config.js)

比如 `postcss.config.js` 这个，也需要更新一下，[参考代码](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/blob/main/demo/uni-app-webpack5/postcss.config.js)

诸如这种类似的，都可以新创建一个的 `uni-app alpha` 的项目，然后把里面的配置直接复制过来，再改改 `postcss.config.js` 把 `tailwindcss` 注册进去即可。

### 5. 运行排错

接下来就是，删掉你的 `lock` 文件，重新安装所有包，并运行你的项目！

当然运行时，很有可能报各种各样的错误: 比如 `babel-xxx` 插件找不到，这种安装即可。

或者什么 `webpack` 插件报错，这种可以暂时去除看看能不能打包成功。

:::tip
假如你使用了 `uni-app` 的同时使用了云函数，云函数导致编译到微信出现 `TypeError: I18n is not a constructor`

解决方案详情见: <https://ask.dcloud.net.cn/question/170057>

相关 issue : [issues/74#issuecomment-1573033475](https://github.com/sonofmagic/weapp-tailwindcss/issues/74#issuecomment-1573033475)
:::

---

## 重新思考 weapp-tailwindcss 的未来


大家好，我是 [weapp-tailwindcss](https://github.com/sonofmagic/weapp-tailwindcss)、[weapp-vite](https://github.com/weapp-vite/weapp-vite) 的作者 icebreaker。

最近我一直在思考 `weapp-tailwindcss` 的未来，以至于都没有怎么玩，最近回归的星际争霸2。

## 巨大的阻碍

为什么？因为之前有一个很重要的问题，严重阻碍了 `weapp-tailwindcss` 发展的脚步。

那就是 `tailwind-merge` / `class-variance-authority` / `tailwind-variants` 这些极其重要的原子化样式基础包，没有什么很好的办法在小程序里使用。

### 为什么无法在小程序里使用？

简短一点来说，核心原因是，小程序 `wxml` 类名中，不允许很多特殊字符串，比如 `!`、`[`、`]`、`#` 等字符。

所以 `weapp-tailwindcss` 根据这个设计，在**编译时**，就对 `tailwindcss` 类名进行转换，从而达到了兼容市面上众多小程序的编译插件。

比如用户写的是 `bg-[#123456]`，被 `weapp-tailwindcss` 捕获到了之后，在**编译**的时候，就会同时把 `wxml`、`js`、`wxss` 里面的这个类名转换成小程序可以接受的 `bg-_h123456_`。

而 `tailwind-merge` 它们都是在**运行时**进行计算的，那时候它们接收到的，已经是 `bg-_h123456_` 这种转译之后的字符串，自然合并不了，导致到处出错。

为了兼容，我做了非常多的尝试！给大家展示一下我的受苦之路吧！

## 1. tailwind-merge plugin / createTailwindMerge

最直观的念头，就是给 `tailwind-merge` 写一个 `weapp-tailwindcss` 专用插件就好了!

于是我开始阅读 `tailwind-merge` 源代码，并尝试使用 `extendTailwindMerge` 和 `createTailwindMerge` 完全创建出一个属于我自己的 `weapp-tailwind-merge` 来。

在尝试过程中，我把 `tailwind-merge` 的内部冲突表导出，尝试用自定义 `escape hook` 覆盖那些非法字符；甚至写了一个半成品的 `createTailwindMerge` 变体，希望能在编译阶段就生成完全符合小程序命名规则的类名。

然而，现实很快给了我当头棒喝：`tailwind-merge` 对**运行时**字符串的依赖极强，部分字符是强依赖，根本无法替换。

下面这几个字符串都是写在常量里的，无法通过配置更换

```ts
export const IMPORTANT_MODIFIER = '!' // 小程序不行
const MODIFIER_SEPARATOR = ':' // 小程序不行
```

详见 https://github.com/dcastil/tailwind-merge/blob/v3.3.1/src/lib/parse-class-name.ts。

所以这已经不是 `extendTailwindMerge` 和 `createTailwindMerge` 能够解决的问题了。

摆在我面前的，是一条看不到未来的路：为了强行兼容，我需要重写它的核心，fork 一个全新的包，这个成本是巨大的。

## 2. 编译期豁免

第二条路看起来更务实：沿用我熟悉的编译期管线，给 `twMerge` / `twJoin` / `cva` 等函数做“豁免处理”。

我当时是这样想的，只要在**编译时**忽略它们内部的转义，**运行时**拿到的就是完整的 class 字符串，那 tailwind-merge 不就能工作了吗？

然后我再包装一下 `twMerge` 函数，让它获取最后的结果的时候 escape 不就行了吗？

大概长这样：

```ts
export function cn(...inputs: ClassValue[]) {
  const result = twMerge(inputs)
  return escape(result)
}
```

然后我让 `cn` 里面的字面量和模板字符串跳过转义不就行了吗？

```ts
// 第一个是字符串，第二个是模板字符串，它们对应的 ast 类型不同，需要分开处理
// 里面的不转译
cn('bg-[#123456]',`bg-[#987654]`)

// 假如转译那么，结果如下
// cn('bg-_h123456_',`bg-_h987654_`)
```

看上去运行良好，然而情况正在变得越来越复杂：

嘿，变量引用来了：

```ts
const a = 'bg-[#123456]';
cn(a,"xx","yy")
```

嘿嘿，变量引用 + 表达式来了：

```ts
const a = 'bg-[#123456]' + ' bb' + ` text-[#123456]`;
cn(a,"xx","yy")
```

嘿嘿嘿，变量引用链路 + 表达式 + 模板插值来了：

```ts
const b = 'after:xx';const a = 'bg-[#123456]' + ' bb' + `${b} text-[#123456]`;
cn(a,"xx","yy")
```

哈哈，只是在考验我操作 ast 进行预编译的水平而已！

吃我一拳：`ASTNodePathWalker` + `scope.getBinding` + `WeakMap`，哈哈轻松消灭！

于是我以为这条思路可行，编写了 `@weapp-tailwindcss/merge` 的 v1 版本。

直到用户提交了新的 case！

### 新的挑战

什么，怎么还有你们这种相互引用的情况！

```js
// shared2.js
export const ddd = 'bg-[#123456]';

const a = 'bg-[#123456]';

export {
  a as default
}
```

```js
// shared.js
export const a = 'bg-[#123456]';

const b = 'bg-[#123456]';

const c = 'bg-[#123456]';

const d = 'bg-[#123456]';

export default d

export {
  b
}

export {
  c as xaxaxaxa,
}

export * from './shared2'
```

```js
// main.js

cn(bb, cc, aa, shared.default, shared.a, "[]", "()")
```

……我吐了，这是要我自己去实现一个 webpack / rollup 打包器嘛？有点搞不定啊！

不过困难怕什么，我要迎难而上！于是我仿照了 `rollup` 的思路，收集了每个模块的 `import` / `export` 这里面大量的 ast 节点，并构建出了一个 `ModuleGraph`。

另外表面上看这条路是可行的，我甚至找到了几个 `demo` 可以跑通，我还把豁免名单抽离出来，变成了 `ignoreCallExpressionIdentifiers` 配置项，以为自己解决了问题。

### 然而理想很丰满，现实很骨感

这套方案高度依赖 AST 解析和构建工具的配合，我写的插件无法保证**运行时**得到的类名永远完整。构建链路上的任一环节——Terser、esbuild、rollup 插件甚至手写 Babel 宏——都可能把函数名或模板字符串的标识符压缩重命名，导致最后留给**运行时**的是一个残缺的字符串。

用人话说就是 `cn` , `twMerge`, `tv` 这种方法，在产物里面被重命名成 `e`/`a`/`c` 这种玩意，所以我必须在压缩之前就进行豁免操作，但是那时候我似乎无法去准确收集产物的模块依赖情况(可能是水平不够导致的)。

那一刻我意识到，所谓“编译期豁免”只是在延迟爆炸时间，而不是解除危机。

在两条路都走到尽头之后，只剩下一个选择：彻底重构 merge，让逃逸逻辑回归**运行时**，让编译阶段恢复简单纯粹。

## 为什么要重写 merge？

复盘 1.x 旧版 merge，我发现我当时的设计基于两个假设：一是 `tailwind-merge` 的输入输出始终可控，二是编译器可以精准标记所有“需要放行”的调用。这两个假设已经被现实击碎。

早期的 `@weapp-tailwindcss/merge` 主要目标是“把 tailwind-merge 的结果变成小程序合法类名”。我采取的策略是：

- 继续使用 `tailwind-merge` 做冲突解析；
- 在编译阶段通过函数名黑名单 `ignoreCallExpressionIdentifiers` 跳过对 `twMerge` / `twJoin` / `cva` 等调用的转义；
- 把责任交给开发者：**运行时**得到的类名包含非法字符，需要手动再 escape。

这种模式在 Tailwind CSS v3 勉强能用，但一到 v4 就崩溃了：

1. **编译期豁免并不等于安全**  
   `twMerge('text-[#ececec]', 'text-(--my-custom-color)')` 最终仍然输出原始字符串。稍微复杂一点的条件拼接、链式调用、动态导入，编译器根本判断不出来该不该跳过。
2. **函数名黑名单无法覆盖新的 API**  
   新版本开始导出 `create()`、variants（`tv`）等工厂，调用形式千奇百怪，编译阶段根本匹配不到。
3. **任意值语法越来越灵活**  
   Tailwind v4 的任意值可以是 `text-[theme(my.scale.foo)]` 这种无法静态推断类型的写法。靠黑名单永远落后，反而让用户更困惑。

## 新版 merge 的核心思路

决定“把锅背回**运行时**”以后，我做的第一件事就是把入口全部进行统一：`twMerge` / `twJoin` / `createTailwindMerge` / `extendTailwindMerge` / `cva` / `variants`……统统绑进同一套 transformer 里。

思路很简单：先找出它们共有的“进场”和“退场”动作，再把逃逸拆成前后两个钩子， `escape` 和 `unescape`。

```ts
const transformers = resolveTransformers(options)

const aggregators = {
  escape: transformers.escape,
  unescape: transformers.unescape,
}
```

在实现里我刻意把 escape 和 unescape 拆成两个“齿轮”。不管是用户直接手点 `twMerge`，还是 variants 工厂兜一圈回来，都会先进统一的预处理，再丢给 tailwind-merge。

这等于在**运行时**补了一层“语义编译器”。

### 双向处理链

所以现在每次 merge 现在都得过一遍 `unescape -> tailwind-merge -> escape` 这样的流程：

```ts
 const normalized = transformers.unescape(clsx(...inputs))
 return transformers.escape(fn(normalized))
```

但是这样还不够，为了实现 `escape` 和 `unescape` 我还必须从源头上出发，更改 `@weapp-core/escape` 的转译规则，才能让每一个字符串映射变得独一无二

### 重写 @weapp-core/escape

老 escape 工具一直挂在 `@weapp-core/escape` 上，它走的是“多对一”映射，贴一段旧代码大家感受一下：

```ts
export const MappingChars2String: MappingStringDictionary = {
  '[': '_',
  ']': '_',
  // for tailwindcss v4
  '(': 'y',
  ')': 'y',
  '{': 'z',
  '}': 'z',
  '+': 'a',
  ',': 'b',
  ':': 'c',
  '.': 'd',
  '=': 'e',
  ';': 'f',
  '>': 'g',
  '#': 'h',
  '!': 'i',
  '@': 'j',
  '^': 'k',
  '<': 'l',
  '*': 'm',
  '&': 'n',
  '?': 'o',
  '%': 'p',
  '\'': 'q',
  '$': 'r',
  '/': 's',
  '~': 't',
  '|': 'u',
  '`': 'v',
  '\\': 'w',
  '"': 'x',
}
```

问题马上就来了：它完全做不到配对 `unescape`。`[` 和 `]` 被一起砸成 `_`，`(` / `)`、`{` / `}` 也全堆在同一个值上，**运行时**根本还原不回去。举个让人头疼的例子：`escape('[bg:red]') === '__bg_red_'`。

所以我直接把 `@weapp-core/escape` 推倒重练，写成一个可逆的“状态机”。每个非法字符都分到独一无二的逃逸片段，还带长度前缀，跑完 `unescape(escape(input))` 就一定回到原样。为了防止它在极端输入上翻车，我拉了十几组 property-based 测试，emoji、空格、重复 escape 全安排上写了大量的单元测试，确保往返都符合预期。

下面是当前版本的核心映射表，展示了我如何为每个非法字符分配唯一的 escape 片段，便于和旧版多对一的写法做对比：

```ts
export const MappingChars2String = {
  '[': '_b',
  ']': '_B',
  '(': '_p',
  ')': '_P',
  '#': '_h',
  '!': '_e',
  '/': '_f',
  '\\': '_r',
  '.': '_d',
  ':': '_c',
  '%': '_v',
  ',': '_m',
  '\'': '_a',
  '"': '_q',
  '*': '_x',
  '&': '_n',
  '@': '_t',
  '{': '_k',
  '}': '_K',
  '+': '_u',
  ';': '_j',
  '<': '_l',
  '~': '_w',
  '=': '_z',
  '>': '_g',
  '?': '_Q',
  '^': '_y',
  '`': '_i',
  '|': '_o',
  '$': '_s',
} as const
```

文章里我只放这份“简化表”，因为它才是**运行时**默认用的版本，开发者平时看到的也是它。更复杂的兼容映射我留在文档和测试里。

### **运行时**配置

新的 `create()` 可以随手关掉任意环节，这是和社区聊得最多的诉求。有团队想“开箱默认就好”，也有老项目背着一堆历史包袱，得慢慢迁移。所以我直接给了一排明确开关，想保守就保守，想激进就激进。

```ts
const { twMerge: passthrough } = create({ escape: false, unescape: false })
```

配合 SSR 或老数据兼容的时候，也不用再额外写工具函数：服务端直接把 escape 全关掉，只做 merge 校验；到小程序再开回完整逃逸步奏，迁移过程就能一步一步踩稳。

另外还开放了 `map` 字段，用于统一用自己的字符映射。

## 发布 4.7.x 版本

绕了这么多弯，所有成果最终都塞进了 `weapp-tailwindcss@4.7.x` 和 `@weapp-tailwindcss/merge@2.x` 中。算是 weapp-tailwindcss **运行时**时代的第一声号角。

欢迎大家把新版 `@weapp-tailwindcss/merge` 用到真实项目里，更欢迎在社区继续砸想法，我会把这些反馈当作下一轮迭代的燃料，让 Tailwind CSS 在小程序世界里始终“开箱即用”。

有时候我也在想，为小程序这个逐渐感觉不怎么活跃的生态，花了这么多时间，感觉有点不值。但是转念一想，起码在我这个领域我已经通过不断的学习，真的掌握了很多东西。

起码，对 Tailwind CSS 进行符合中国小程序技术特色的改造方面，我也算是第一人了吧。每每想到这，就感觉自己好像还稍微有这么一点点自豪呢，哈哈哈。

如果你也在思考工具链，编译，AST 等等方面的问题，希望这篇文章能给你一点启发。

## 源代码附录

- [tailwind-merge 插件文档](https://github.com/dcastil/tailwind-merge/blob/v3.3.1/docs/writing-plugins.md)
- [NodePathWalker](https://github.com/sonofmagic/weapp-tailwindcss/blob/main/packages/weapp-tailwindcss/src/js/NodePathWalker.ts)
- [ModuleGraph](https://github.com/sonofmagic/weapp-tailwindcss/blob/main/packages/weapp-tailwindcss/src/js/ModuleGraph.ts)

---

## 4.0.0 🚀

weapp-tailwindcss v4.0 正式发布，核心亮点是兼容 `tailwindcss@4` 并引入 `tailwind-merge` 运行时整合能力。文章总结了升级背后的思路，并提供 uni-app 示例帮助你快速落地。

<!-- truncate -->

![4.0 release](https://cdn.jsdelivr.net/gh/sonofmagic/static/mbpv4-release.png)

# weapp-tailwindcss v4.0 发布了！

## **总结**

经历了一番自虐式开发后，`weapp-tailwindcss` **v4.0** 终于发布了！

在清理了一些自己当初写的屎山代码后，我终于实现了心心念念的两个大功能：

1. **支持 `tailwindcss@4.x` 版本**
2. **支持 `tailwind-merge`**

> 因为 `tailwindcss@4` 直接变成了一个样式预处理器，定位上类似 `Sass` / `Less`，所以相关的改动还是挺大的。目前 `weapp-tailwindcss@4` 版本也同时兼容 `tailwindcss 4+3+2(jit)` 三个版本了。

想快速上手集成？欢迎访问 [weapp-tailwindcss 官网](https://tw.icebreaker.top/)！
如果你想进一步了解细节，下面有个示例，看看就懂了。

---

## **uni-app 快速集成示例**

这里我们以 **`uni-app`（Vue3 + Vite）** 为例。

### **1. 安装依赖**

```bash npm2yarn
npm install -D tailwindcss @tailwindcss/vite weapp-tailwindcss
```

然后，把下面这段脚本加入 `package.json` 的 `scripts` 字段里：

```json title="package.json"
{
  "scripts": {
    // highlight-next-line
    "postinstall": "weapp-tw patch"
  }
}
```

> 这个补丁是为了让 `tailwindcss@4` 认识 `rpx` 单位，否则它会以为 `rpx` 是个颜色单位，导致 `text-[40rpx]` 这样的样式翻车。

---

### **2. 配置 `vite.config.ts`**

```ts title="vite.config.ts"

export default defineConfig(async () => {
  // 这里必须这样引用，因为 uni 只提供 cjs 版本，而 @tailwindcss/vite 只提供 esm 版本
  const { default: tailwindcss } = await import('@tailwindcss/vite')
  return {
    plugins: [
      uni(),
      tailwindcss(),
      UnifiedViteWeappTailwindcssPlugin({ rem2rpx: true })
    ],
  }
})
```

---

### **3. 添加样式**

在项目目录下创建 `main.css`，然后添加以下内容：

```css title="main.css"
@import 'weapp-tailwindcss';
```

接着在 `main.js` 里引用这个文件作为全局样式，然后直接运行：

```bash npm2yarn
npm run dev:mp-weixin
```

在微信开发者工具中导入这个项目，在项目中使用 `tailwindcss` 原子类，即可看到效果。

---

## **遇到的问题以及解决方案**

### **1. `tailwindcss@4` 的样式兼容性问题**

`tailwindcss@4` 生成的样式广泛使用了 `@layer`、`color-mix`、`oklch` 等新特性，现代浏览器兼容性都不咋地，更别说小程序了。

所以无论是 H5 还是小程序，都需要 `postcss-preset-env` 来降级这些样式的生成结果。降级的程度取决于你的 `browserslist` 配置。

---

### **2. `tailwind-merge` 样式合并问题**

`tailwind-merge` 是一个 `tailwindcss` 运行时样式合并工具，它能自动合并重复的样式。不过，小程序端用 `tailwind-merge` 有点挑战，因为：

- `weapp-tailwindcss` **在编译时** 对 `tailwindcss` 样式做转义。
- `tailwind-merge` **在运行时** 处理样式合并。

这导致 `tailwind-merge` 处理已转义的 `class` 时，误以为它们是普通 `class`，而不是 `tailwindcss` 的原子类。

### **解决方案：编译时感应 + 运行时合并转义**

我研究了一下 `tailwind-merge` 的源码，尝试写一个 `plugin` 来解决这个问题，结果发现路走不通，因为：

- `tailwind-merge` 内部有一些硬编码规则，比如 `!` 代表 `!important`，无法通过 `plugin` 自定义。

于是，我换了个思路，**采用编译时感应、忽略转义，运行时合并转义的方式** 解决了这个问题，这就是 **`@weapp-tailwindcss/merge`** 诞生的原因。

#### **编译时感应的原理**

我利用 `babel` 的 `scope`（作用域） 和 `binding`（绑定） 增强了识别能力

`scope` 简而言之就是 `js` 基础里的大括号, `binding` 就是一个变量真正的绑定

比如：

```js
const b = 'after:xx'
const a = `${b} text-[#123456]`
cn(a, 'xx', 'yy')
```

这段代码的作用域是全局，然后 `cn` 中 `a` 的绑定是一个 `VariableDeclaration` 它的 `init` 中，又引用了 `b` ，它的绑定也是一个 `VariableDeclaration` 初始化是一个 `StringLiteral`

于是，在编译时，我们可以从 `cn` 递归向上找到 `a` 和 `b`，识别出完整的样式链。

当然，另一种方式是 **自上而下查找**，通过 `import` 语句分析模块依赖关系，甚至可以利用打包工具的模块分析图进行静态分析。

当然这块的实现被用在了 **`@weapp-tailwindcss/merge`** 中，详见 [tailwind-merge 快速开始](https://tw.icebreaker.top/docs/community/merge)。

---

## **开发心得**

在开发的时候，一定要把可能影响结果的方式，拆成多多阶段运行，比如在修改 `js ast` 的时候，不应该一边 `traverse` ，一边再用 `MagicString` 去修改，而是应该把需要修改的地方，先全部收集出来，然后在一个阶段统一去修改。

另外鉴别一个 `ast` 工具的成熟度，也应该考虑一下，作用域和绑定的关系，能否被解析出来。比如我们都知道 `js` 里面大概有 `5` 种行为会产生作用域:

- **Program**：全局作用域，整个文件的顶层作用域。
- **FunctionDeclaration / FunctionExpression / ArrowFunctionExpression**：函数作用域（包括箭头函数）。
- **BlockStatement**：块级作用域（由 `{}` 包裹，例如 if、for、while 中的块，在 ES6 中支持 let 和 const）。
- **ClassDeclaration / ClassExpression**：类作用域（类的主体和方法会引入作用域）。
- **CatchClause**：try-catch 中 catch 块的作用域。

而绑定本身也是通过 `scope` 和它的 `parent` 依次向上去找的。

## 最后一点碎碎念

转眼我也到了而立之年，在这个行情下，毕业（失业）随时可能发生，当然也不敢毕业，毕竟上有老下有小，还有各种贷款。

技术学得越多，越觉得是个无底洞。而且掌握的东西多了，好像也没什么收益。更何况前端技术和那种 AI 技术相比，就像是过家家一样的。

开源呢？搞了半天也没啥产出，想成为开源明星，但自己技术水平也没到那个级别。

最近，我开始深入学习 **云原生**，因为我意识到，国内这种国情下 **"技术是工具，业务才是目的"**。

这导致我们技术人员的地位是非常低的，这点只要还在国内混就无法改变。

所以我们自己也不要对自己或者团队写的东西，搞得有多好多完美的似的。够用就行，多尝试，先快速搞他个 100 个应用，然后挑没死的去进行进一步的开发。

举个例子，现在让我从 0 到 1 搭建一个完整的业务系统，我可以全程自主搞定：

- **前端**：`Vue` / `React`
- **后端**：`Node.js`（任意框架）
- **数据库**：`MongoDB` / `PostgreSQL`
- **运维**：`Docker` / `Serverless`

但问题是——**开发成本和时间成本太高了！**

这种情况，我要自己去设计数据库，写 `openapi.yml` ，然后实现接口，还要自己写前端，和自己对接。写的差不多了还要测试，又是一堆 `bug`。

而且还可能遇到技术难点，之前我在 `Node.js` 中实现 `PostgreSQL` 的 `GraphQL` 方案，就折腾了好久。这种情况，为什么不直接上 `pg_graphql` 这种成熟的中间件呢？

所以，从商业角度来看：

1. **写尽可能少的代码**，尽量利用成熟方案快速搭建业务。
2. **赚钱才是第一要务**，哪里有问题，先堆机器解决，实在搞不定了，再招专业人才处理。
3. **多利用AI来降本增效**，AI 成本比人低，所以招个高级，不如招个初级的，会用 AI 的，学习能力好的程序员，毕竟前端静态页面，AI 生成可快了

所以，从一个程序员的视角出发:

**这是最好的时代，也是最坏的时代。**

---

## **参考链接**

- [weapp-tailwindcss 迁移文档](https://tw.icebreaker.top/docs/migrations/v3)
- [Tailwindcss@4 各个框架集成方式](https://tw.icebreaker.top/docs/quick-start/v4)
- [Tailwindcss@4 升级指南](https://tailwindcss.com/docs/upgrade-guide)
- [uni-app-tailwindcss-v4 参考模板](https://github.com/icebreaker-template/uni-app-tailwindcss-v4)

---

## 4.2.0 🚀

weapp-tailwindcss@4.2.x 现已适配 `uni-app x` 的多端构建能力，让 Tailwind CSS 原子类能够无缝跨端使用。本文梳理了从项目初始化到插件配置的完整流程，帮助你快速完成集成与发布。

<!-- truncate -->

# weapp-tailwindcss 已支持 uni-app x 多端构建

## 前言

[`uni-app x`](https://doc.dcloud.net.cn/uni-app-x/) 是 `DCloud` 团队开发的跨平台编译方案，可将同一份代码编译到 Web、小程序、Android、iOS、鸿蒙等多端。

最近，我很荣幸在 `weapp-tailwindcss@4.2.x` 版本中，适配了 `uni-app x` 的多端构建，使 `Tailwind CSS` 的原子化样式能够无缝应用于多端项目。

所以就有了这篇文章，给大家介绍(**秀**)一下怎么在 `uni-app x` 项目中，集成 `weapp-tailwindcss` 这个样式解决方案。

## 快速集成

### 0. 创建项目

使用最新版本 `Hbuilderx` 创建一个 `uni-app x` 项目，然后在项目根目录执行

```bash
npm init -y
```

初始化一个 `package.json` 文件 (当然你也可以手动创建)

### 1. 安装并引入 tailwindcss@3

```bash
# 安装 tailwindcss@3 版本的依赖
npm i -D tailwindcss@3 postcss autoprefixer
# 初始化一个 tailwind.config.js 文件
npx tailwindcss init
```

然后，在你的根目录中的 `App.uvue` 中引入 `tailwindcss` 使它在应用全局生效

```html title="App.uvue"
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>
```

### 2. 安装 weapp-tailwindcss

在项目目录下，执行:

```bash
npm i -D weapp-tailwindcss
```

然后把下列脚本，添加进你的 `package.json` 的 `scripts` 字段里:

```json title="package.json"
 "scripts": {
    // highlight-next-line
   "postinstall": "weapp-tw patch"
 }
```

想知道原因的同学可以查看 [**这个链接**](https://tw.icebreaker.top/docs/quick-start/this-plugin)

### 3. uni-app x 中注册 weapp-tailwindcss

#### 3.0. 创建辅助函数

在项目中创建 `shared.js` 文件，用于存放一些工具函数：

```js title="shared.js"
const path = require('node:path')
// 绝对路径处理
function r(...args) {
  return path.resolve(__dirname, ...args)
}

module.exports = {
  r,
}
```

#### 3.1. 配置 `Vite`

创建 `vite.config.ts` 文件，注册插件：

> 这里特别注意 `uniAppX` 是从 `weapp-tailwindcss/presets` 这个预设中导出的

```js title="vite.config.ts"

export default defineConfig({
    plugins: [
        uni(),
        UnifiedViteWeappTailwindcssPlugin(
            uniAppX({
                base: __dirname,
                rem2rpx: true,
            }),
        ),
    ],
    css: {
        postcss: {
            plugins: [
                tailwindcss({
                    config: r('./tailwind.config.js'),
                }),
            ]
        }
    }
});
```

#### 3.2. 更改 `tailwindcss` 配置

你需要在 `tailwind.config.js` 的 `content` 配置中，使用绝对路径去包括所有的提取文件

```js title="tailwind.config.js"
const { r } = require('./shared')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    r('./pages/**/*.{uts,uvue}'),
    r('./components/**/*.{uts,uvue}') 
  ],
  corePlugins: {
    preflight: false,
  },
}

```

> 如需从更多目录提取样式 `token`，可按需扩展 `content`。

---

在完成这些步骤之后， `uni-app x` 就集成 `tailwindcss` 原子化样式解决方案。

## 如何运行

目前 `uni-app x` 并没有提供任何 `cli` 的方式去使用它，所以目前我们使用 `Hbuilderx` 去进行开发和构建的。

这里可以使用 `Hbuilderx` 的运行，来运行到各个平台。

### 优先使用安卓进行开发

一般来说，`CSS` 平台的兼容程度，是 `Web` > `小程序` > `App`(安卓/IOS/鸿蒙)

所以，假如你有跨多端的需求，建议你一开始使用 `安卓模拟器` 来进行开发和调试，这是综合考虑下来 **成本最低** 的方案。

#### 🧐为什么?

因为 `uni-app x` 开发原生 `app` 是有一些限制的，

1. 比如文字必须包括在 `<text>` 标签中，文字的样式(比如 `text-2xl text-center text-red-400`) 也必须设置在这个元素上，设置在 `<view>` 上是没有效果的。而 `Web` 和 `小程序` 都是兼容的。

2. 还有很多 `css` 的样式，目前 `uni-app x` 暂时是不兼容的，强行使用 `Hbuilderx` 的控制台会爆出警告，要求你进行更改。

这就相当于，你写的代码，能够满足了 `安卓` 这一端，那就大概率能满足 `小程序` 端，甚至 `Web` 端了(当然实战中还需要很多条件编译处理)

#### 🧐为什么不是 IOS 或者鸿蒙? 

IOS 模拟器，需要你有 Mac 才能运行，IOS 调试需要你有苹果手机，考虑到大部分开发应该都是用的 Windows 机器，所以选择 Android 模拟器开发，相对成本低一些，你都有的话当我没说

至于鸿蒙，uni-app x 官方文档上都写着:

> 鸿蒙整体处于发展初期，能用，有坑，大部分坑有规避方案。但开发者应建议其领导、客户、质量部门降低期望，不能严格比照Android和iOS的验收标准要求鸿蒙。

不如安卓/IOS 稳定的话，自然优先选择安卓平台

## 常见问题

### Vscode uvue/uts 代码染色

安装 `DCloud` 自己推出的 `uni-app x语言服务`, 插件市场一搜 `uni-app x` 就搜到了
- ID: dcloud-ide.hbuilderx-language-services
- 说明: 支持uni-app x项目的代码提示、悬浮、转到定义、查找引用、大纲、校验等
- 发布者: DCloud
- VS Marketplace 链接: https://marketplace.visualstudio.com/items?itemName=dcloud-ide.hbuilderx-language-services

### Tailwindcss 智能提示

目前 `Tailwindcss` 智能提示最好的还是 `vscode`，但是 `vscode Tailwindcss` 肯定是不认识 `uvue/uts` 文件的，

要让插件认识，只需要在你的项目中添加 `.vscode/settings.json` 文件

```json
{
    "tailwindCSS.includeLanguages": {
        "uvue": "html",
        "uts": "javascript"
    }
}
```

当然，你直接全局修改你的 `vscode Tailwindcss` 插件配置肯定也是可以的。

## 尾言

`uni-app x` 是一个 **庞大的工程**, `DCloud` 团队能做出这样的技术解决方案，令人倾佩。

假如你遇到什么问题，可以在 [weapp-tailwindcss](https://github.com/sonofmagic/weapp-tailwindcss) 的 `issue/disscussions` 中提出。

## 配置好的模板

https://github.com/icebreaker-template/uni-app-x-hbuilderx

使用方式见这个项目中的 `README.md`

## 参考文档

[uni-app x 官方文档](https://doc.dcloud.net.cn/uni-app-x/)

[weapp-tailwindcss 官网](https://tw.icebreaker.top/)

[weapp-tailwindcss 的 uni-app x 专题](https://tw.icebreaker.top/docs/uni-app-x)

---

## 4.3.0 🚀

weapp-tailwindcss@4.3.0 默认开启 CSS 变量计算模式，并补充了更细粒度的 `cssCalc`、`px2rpx` 等配置，显著提升了多端 `rpx` 与 `calc` 的兼容性。本文带你了解这些变化的原理与使用方法。

<!-- truncate -->

# weapp-tailwindcss@4.3.0 🚀

## CSS变量计算模式

在 `tailwindcss@4` 下，默认启用 CSS 变量计算模式。`tailwindcss@3` 默认不启用。

此模式下会去预编译所有的 `css` 变量和 `calc` 计算表达式。

比如 `tailwindcss@4` 下原先生成的样式为:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: calc(var(--spacing) * 2);
}
```

在CSS变量计算模式启动，进行预编译之后，现在的结果为:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
  height: calc(var(--spacing) * 2);
}
```

这个模式可以解决很多手机机型 `calc` `rpx` 单位的兼容问题

> 可通过给插件，传入 `cssCalc` 配置项 `false` 来手动关闭这个功能

假如这时候你需要去除 CSS 变量的声明，你可以传入

```js
{
  cssCalc: ['--spacing']
}
// 或者更精确的
{
  cssCalc: {
    includeCustomProperties: ['--spacing']
  }
}
```

> 你也可以传入正则表达式

这样生成的结果就是:

```css
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
}
```

通过这种方式可以解决手机机型 `calc` `rpx` 单位的兼容问题

详见: https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#csscalc

## 新增配置项

### px2rpx

添加 `px2rpx` 配置项， 用于控制是否将 `px` 单位转换为 `rpx` 单位， 默认为 `false`

传入 `true` 则会将所有的 `px` 单位, `1:1` 转换为 `rpx` 单位

假如需要更多的转化方式，可以传入一个 `object`, 配置项见 https://www.npmjs.com/package/postcss-pxtransform

### logLevel

添加 `logLevel` 配置项，用于控制日志输出级别， 默认为 `info`