Skip to content

Commit c6ce9f5

Browse files
sonofmagicsonofmagic
committed
docs: 重写快速使用指南
1 parent 6b3c1f3 commit c6ce9f5

10 files changed

Lines changed: 375 additions & 171 deletions

File tree

‎website/docs/intro.md‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -52,19 +52,17 @@ keywords:
5252

5353
## 快速开始 :rocket:
5454

55-
### 🔥 Tailwind CSS @3.x
55+
### 👉 [快速使用](/docs/quick-start/install)
5656

57-
`weapp-tailwindcss` 主要提供了 `3` 种使用方式:
57+
先选择 `tailwindcss@3` 或 `tailwindcss@4`，再按 `uni-app`、`Taro`、`Mpx`、原生小程序等框架注册 `WeappTailwindcss` 构建器插件。
5858

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

61-
#### 👉 [2. 原生小程序开发的快速开始](/docs/quick-start/native/install)
61+
如果你想直接对照可运行项目，可以优先查看模板项目。
6262

63-
#### 👉 [3. 可直接使用的各个框架的小程序模板](/docs/community/templates)
63+
### 👉 [Tailwind CSS 4.x 参考](/docs/quick-start/v4)
6464

65-
### 🧪 Tailwind CSS @4.x
66-
67-
#### 👉 [Tailwindcss@4.x 快速开始](/docs/quick-start/v4)
65+
如果你已经确定使用 `tailwindcss@4`，这里有 CSS-first、`@source`、`@apply`、`@layer` 和 IntelliSense 的补充说明。
6866

6967
## 演示视频
7068

‎website/docs/quick-start/frameworks/api.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,24 @@ keywords:
2424
2525
有时候,我们不一定会使用 `webpack/vite/gulp`，可能是直接使用 `nodejs` 去构建应用，或者封装更高阶的工具，这时候可以使用`api`去转义你的应用。
2626

27+
:::caution
28+
`weapp-tailwindcss@5` 的推荐接入方式仍然是 `weapp-tailwindcss/vite` 或 `weapp-tailwindcss/webpack`。Node.js API 适合自研构建器、批处理脚本、Gulp 插件封装等场景。
29+
30+
如果你只是普通 `uni-app`、`Taro`、`Mpx`、`Rax` 或原生小程序项目，请优先使用对应框架页的构建器插件。
31+
:::
32+
33+
## Tailwind CSS 3.x 前置步骤
34+
35+
API 只负责转译代码文本，不会替你自动运行完整框架构建。Tailwind CSS 3.x 项目仍然需要先让入口 CSS 完成生成：
36+
37+
```css title="app.css"
38+
@tailwind base;
39+
@tailwind components;
40+
@tailwind utilities;
41+
```
42+
43+
`tailwind.config.js` 的 `content` 要包含实际源码，并排除 `node_modules`、`dist`、`unpackage` 等产物目录。只有 Tailwind 已经提取到的类名，后续 `transformJs` 才能精确命中并转译。
44+
2745
## 如何使用
2846

2947
```js
@@ -63,3 +81,13 @@ const classNames = ['mb-[1.5rem]']
6381

6482
另外使用此种方式，编译缓存需要自行处理，且暂时没有类名的压缩与混淆功能
6583
:::
84+
85+
## 和构建器插件的区别
86+
87+
| 使用方式 | 适合场景 | Tailwind CSS 生成 |
88+
| --- | --- | --- |
89+
| `weapp-tailwindcss/vite` | Vite 框架和 weapp-vite | 插件接管 |
90+
| `weapp-tailwindcss/webpack` | Webpack 框架 | 插件接管 |
91+
| `weapp-tailwindcss/core` | 自研构建器或脚本 | 需要你自己串好生成顺序 |
92+
93+
对于 Tailwind CSS 4.x，自定义构建器还需要显式处理 CSS 入口、`@source`、`cssEntries` 等信息；普通项目建议直接使用 [Tailwind CSS 4.x 各框架注册方式](/docs/quick-start/v4)。

‎website/docs/quick-start/frameworks/native.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,39 @@ keywords:
3939

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

42+
## weapp-vite 模板
43+
44+
如果你希望原生小程序也走 Vite 构建，推荐查看 [纯原生 weapp-vite 接入](/docs/quick-start/native/install)。Tailwind CSS 3.x 项目继续使用 `tailwind.config.js` 的 `content` 扫描范围，入口 CSS 使用：
45+
46+
```css title="app.css"
47+
@tailwind base;
48+
@tailwind components;
49+
@tailwind utilities;
50+
```
51+
52+
然后在 `vite.config.ts` 中注册 `weapp-tailwindcss/vite`：
53+
54+
```ts title="vite.config.ts"
55+
import path from 'node:path'
56+
import { defineConfig } from 'weapp-vite/config'
57+
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
58+
59+
export default defineConfig({
60+
plugins: [
61+
WeappTailwindcss({
62+
rem2rpx: true,
63+
cssEntries: [
64+
path.resolve(import.meta.dirname, './app.css'),
65+
],
66+
}),
67+
],
68+
})
69+
```
70+
71+
`weapp-tailwindcss@5` 生成模式会接管 Tailwind CSS 生成和小程序转译，不需要再注册 `tailwindcss` PostCSS 插件，也不需要执行 `weapp-tw patch`。
72+
73+
如果你使用的是 `tailwindcss@4`，请改看 [Tailwind CSS 4.x / Weapp-vite](/docs/quick-start/v4/weapp-vite)，入口 CSS 需要改成 `@import "tailwindcss";` 和 `@source`。
74+
4275
## 组件样式的隔离性
4376

4477
:::tip

‎website/docs/quick-start/frameworks/rax.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ keywords:
1919
---
2020
# Rax (react)
2121

22+
本文是 `weapp-tailwindcss@5` 配合 `tailwindcss@3` 的 Rax 接入方式。Tailwind CSS 3.x 入口 CSS 使用 `@tailwind` 指令，扫描范围继续写在 `tailwind.config.js` 的 `content` 中。
23+
2224
在根目录下创建一个 `build.plugin.js` 文件，然后在 `build.json` 中注册：
2325

2426
```json title="build.json"

‎website/docs/quick-start/frameworks/taro.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,17 @@ keywords:
3232

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

35+
## Tailwind CSS 版本选择
36+
37+
本文是 `weapp-tailwindcss@5` 配合 `tailwindcss@3` 的 Taro 接入方式：
38+
39+
- `src/app.css` 使用 `@tailwind base; @tailwind components; @tailwind utilities;`
40+
- `tailwind.config.js` 使用 `content` 配置扫描范围
41+
- `config/index.[jt]s` 只注册 `WeappTailwindcss`
42+
- 不再在 PostCSS 中注册 `tailwindcss`
43+
44+
如果你的项目已经使用 `tailwindcss@4`，请改看 [Tailwind CSS 4.x / Taro Webpack](/docs/quick-start/v4/taro-webpack) 或 [Tailwind CSS 4.x / Taro Vite](/docs/quick-start/v4/taro-vite)。
45+
3546
## 使用 Webpack 作为打包工具
3647

3748
### 注册插件

‎website/docs/quick-start/frameworks/uni-app-x.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@ keywords:
2121

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

24+
本文是 `weapp-tailwindcss@5` 配合 `tailwindcss@3` 的 `uni-app x` 接入方式。Tailwind CSS 3.x 继续通过 `tailwind.config.js` 的 `content` 扫描 `uts` / `uvue` 文件。
25+
26+
如果你使用的是 `tailwindcss@4`，请改看 [Tailwind CSS 4.x / uni-app x](/docs/quick-start/v4/uni-app-x)，入口 CSS 需要使用 `@import "tailwindcss";` 和 `@source`。
27+
2428
:::warning 能力边界
2529
`uvue` 原生 App 端不要依赖 `gap`、`gap-x-*`、`gap-y-*`，这些布局能力当前都不支持。
2630

‎website/docs/quick-start/install.mdx‎

Lines changed: 173 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
---
2-
title: Tailwind CSS 3.x 生成模式安装与配置
3-
description: 使用 weapp-tailwindcss v5 默认生成模式接入 Tailwind CSS 3.x。
2+
title: 快速使用
3+
description: 使用 weapp-tailwindcss v5 接入 Tailwind CSS 3.x 或 4.x，并按框架注册构建器插件。
44
keywords:
55
- 快速开始
66
- 安装
77
- 配置
88
- tailwindcss
99
- tailwindcss 3
10+
- tailwindcss 4
1011
- generator
1112
- weapp-tailwindcss
1213
- 小程序
@@ -17,30 +18,62 @@ keywords:
1718
- mpx
1819
---
1920

20-
# Tailwind CSS 3.x 生成模式安装与配置
21+
# 快速使用
2122

22-
`weapp-tailwindcss@5` 默认使用生成模式。Tailwind CSS 3.x 项目继续使用 `tailwind.config.js` 的 `content` 扫描范围，但样式生成由 `WeappTailwindcss` 构建器插件接管，不再把 `tailwindcss` 注册到 PostCSS。
23+
`weapp-tailwindcss@5` 默认使用生成模式。你只需要做两件事：
2324

24-
## 1. 安装依赖
25+
1. 选择 `tailwindcss@3` 或 `tailwindcss@4`，准备 Tailwind CSS 入口。
26+
2. 按你的框架注册 `WeappTailwindcss` 构建器插件，并把 `cssEntries` 指向同一个入口 CSS。
2527

26-
```bash npm2yarn
27-
npm i -D tailwindcss@3 weapp-tailwindcss
28+
也就是说，框架注册方式基本是一套；真正不同的是 Tailwind CSS 入口和扫描配置。
29+
30+
## 1. 选择 Tailwind CSS 版本
31+
32+
| 版本 | 推荐场景 | 安装命令 | 样式入口 | 扫描范围 |
33+
| --- | --- | --- | --- | --- |
34+
| Tailwind CSS 3.x | 追求兼容性、存量项目、暂不迁移 CSS-first | `pnpm add -D tailwindcss@3 weapp-tailwindcss` | `@tailwind base;` 等指令 | `tailwind.config.js` 的 `content` |
35+
| Tailwind CSS 4.x | 新项目、希望使用 CSS-first 配置 | `pnpm add -D tailwindcss weapp-tailwindcss` | `@import "tailwindcss";` | CSS 入口里的 `@source` |
36+
37+
:::tip 推荐选择
38+
如果你不确定应该选哪个版本，优先选 `tailwindcss@3`，兼容性更稳。准备新项目并且能接受 Tailwind CSS 4 的 CSS-first 写法时，再选 `tailwindcss@4`。
39+
:::
40+
41+
## 2. 安装依赖
42+
43+
### Tailwind CSS 3.x
44+
45+
```bash
46+
pnpm add -D tailwindcss@3 weapp-tailwindcss
47+
pnpm exec tailwindcss init
2848
```
2949

30-
```bash npm2yarn
31-
npx tailwindcss init
50+
### Tailwind CSS 4.x
51+
52+
```bash
53+
pnpm add -D tailwindcss weapp-tailwindcss
3254
```
3355

34-
如果项目已经有 `postcss.config.js`，可以继续保留 `postcss-import`、`autoprefixer` 或框架内置插件等非 Tailwind 后处理插件；不要再添加 `tailwindcss` PostCSS 插件。
56+
`weapp-tailwindcss@5` 会在构建运行时接管 Tailwind CSS 生成。不要再为了小程序构建额外注册 `tailwindcss`、`@tailwindcss/postcss` 或 `@tailwindcss/vite`。
3557

36-
## 2. 配置扫描范围
58+
如果项目已有 `postcss.config.*`，可以保留业务自己的非 Tailwind 插件。
59+
60+
## 3. 准备 CSS 入口
61+
62+
无论使用 Tailwind CSS 3 还是 4，都建议创建一个纯 `.css` 文件作为小程序 Tailwind 入口，例如 `src/app.css`。后续 `cssEntries` 就指向这个文件。
63+
64+
### Tailwind CSS 3.x 入口
65+
66+
```css title="src/app.css"
67+
@tailwind base;
68+
@tailwind components;
69+
@tailwind utilities;
70+
```
3771

3872
```js title="tailwind.config.js"
3973
/** @type {import('tailwindcss').Config} */
4074
module.exports = {
4175
content: [
42-
'./public/index.html',
43-
'./src/**/*.{html,js,ts,jsx,tsx,vue,wxml,axml,ttml,mpx}',
76+
'./src/**/*.{html,js,ts,jsx,tsx,vue,wxml,axml,ttml,mpx,uts,uvue}',
4477
'!./src/uni_modules/**/*',
4578
'!./node_modules/**/*',
4679
'!./dist/**/*',
@@ -52,39 +85,146 @@ module.exports = {
5285
}
5386
```
5487

55-
`content` 应只覆盖业务源码。`uni_modules`、`node_modules`、`dist`、`unpackage`、文档和构建产物默认都应排除；如果必须扫描某个第三方包，请精确包含承载模板类名的文件。
56-
57-
## 3. 添加 CSS 入口
58-
59-
Tailwind CSS 3.x 入口仍使用 `@tailwind` 指令：
88+
### Tailwind CSS 4.x 入口
6089

6190
```css title="src/app.css"
62-
@tailwind base;
63-
@tailwind components;
64-
@tailwind utilities;
91+
@import "tailwindcss";
92+
@source "./**/*.{html,js,ts,jsx,tsx,vue,wxml,axml,ttml,mpx,uts,uvue}";
93+
@source not "./uni_modules";
94+
@source not "../node_modules";
95+
@source not "../dist";
96+
@source not "../unpackage";
6597
```
6698

67-
这个文件需要在框架入口中引入，并在 `WeappTailwindcss` 的 `cssEntries` 中作为绝对路径传入。这样生成器、模板转译和 JS 转译会共享同一份 classSet。
99+
:::warning
100+
`tailwindcss@4` 的入口请只放在纯 `.css` 文件里，不要直接放进 `scss`、`less`、`sass` 文件。业务预处理样式可以再间接引入这个 CSS 入口。
101+
:::
68102

69103
## 4. 注册构建器插件
70104

71-
不同框架的注册位置不同，但原则一致：只注册 `WeappTailwindcss`，不要再注册 Tailwind 官方生成插件。
105+
这里是所有框架共同的原则：
106+
107+
- Vite 链路使用 `weapp-tailwindcss/vite`
108+
- Webpack 链路使用 `weapp-tailwindcss/webpack`
109+
- `cssEntries` 必须指向 Tailwind CSS 入口文件的绝对路径
110+
- 不要再为小程序构建注册 Tailwind 官方 Vite / PostCSS 生成插件
111+
112+
### Vite 通用写法
113+
114+
适用于 `uni-app Vue3 Vite`、`HBuilderX Vue3 Vite`、`weapp-vite`、`Taro Vite` 等构建链路。`uni-app` 项目中 `WeappTailwindcss` 要放在 `uni()` 后面。
115+
116+
```ts title="vite.config.ts"
117+
import path from 'node:path'
118+
import { defineConfig } from 'vite'
119+
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
72120

73-
| 框架 | 构建入口 | 注册位置 | 文档 |
121+
export default defineConfig({
122+
plugins: [
123+
WeappTailwindcss({
124+
rem2rpx: true,
125+
cssEntries: [
126+
path.resolve(__dirname, 'src/app.css'),
127+
],
128+
}),
129+
],
130+
})
131+
```
132+
133+
### Webpack 通用写法
134+
135+
适用于 `Taro Webpack`、`uni-app CLI Vue2 Webpack`、`Mpx`、`Rax` 等构建链路。不同框架的 Webpack 配置入口不同，请按下方框架表进入对应页面复制完整写法。
136+
137+
```js title="webpack config"
138+
const path = require('node:path')
139+
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')
140+
141+
module.exports = {
142+
plugins: [
143+
new WeappTailwindcss({
144+
rem2rpx: true,
145+
cssEntries: [
146+
path.resolve(__dirname, 'src/app.css'),
147+
],
148+
}),
149+
],
150+
}
151+
```
152+
153+
### uni-app x 写法
154+
155+
`uni-app x` 推荐使用内置预设：
156+
157+
```ts title="vite.config.ts"
158+
import { defineConfig } from 'vite'
159+
import uni from '@dcloudio/vite-plugin-uni'
160+
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
161+
import { uniAppX } from 'weapp-tailwindcss/presets'
162+
163+
export default defineConfig({
164+
plugins: [
165+
uni(),
166+
WeappTailwindcss(
167+
uniAppX({
168+
base: __dirname,
169+
rem2rpx: true,
170+
}),
171+
),
172+
],
173+
})
174+
```
175+
176+
## 5. 各框架完整接入
177+
178+
| 框架 | 构建工具 | Tailwind CSS 3.x | Tailwind CSS 4.x |
74179
| --- | --- | --- | --- |
75-
| uni-app Vue3 Vite | `weapp-tailwindcss/vite` | `vite.config.ts` 的 `plugins` | [uni-app cli vue3 vite](/docs/quick-start/frameworks/uni-app-vite) |
76-
| Taro Webpack | `weapp-tailwindcss/webpack` | `config/index.ts` 的 `mini.webpackChain` | [Taro](/docs/quick-start/frameworks/taro) |
77-
| Taro Vite | `weapp-tailwindcss/vite` | `config/index.ts` 的 `compiler.vitePlugins` | [Taro](/docs/quick-start/frameworks/taro) |
78-
| weapp-vite 原生小程序 | `weapp-tailwindcss/vite` | `vite.config.ts` 的 `plugins` | [原生打包方案](/docs/quick-start/frameworks/native) |
79-
| Mpx | `weapp-tailwindcss/webpack` | `mpx.config.js` / `vue.config.js` 的 `configureWebpack` | [Mpx](/docs/quick-start/frameworks/mpx) |
180+
| uni-app CLI Vue3 | Vite | [uni-app cli vue3 vite](/docs/quick-start/frameworks/uni-app-vite) | [uni-app cli vue3 vite](/docs/quick-start/v4/uni-app-vite) |
181+
| uni-app HBuilderX Vue3 | Vite | [HBuilderX Vue3 Vite](/docs/quick-start/frameworks/hbuilderx) | [HBuilderX Vue3 Vite](/docs/quick-start/v4/uni-app-vite-hbuilder) |
182+
| uni-app CLI Vue2 | Webpack | [CLI Vue2 Webpack](/docs/quick-start/frameworks/uni-app) | [CLI Vue2 Webpack](/docs/quick-start/v4/uni-app-webpack) |
183+
| uni-app x | Vite | [uni-app x](/docs/quick-start/frameworks/uni-app-x) | [uni-app x](/docs/quick-start/v4/uni-app-x) |
184+
| Taro | Webpack | [Taro Webpack](/docs/quick-start/frameworks/taro) | [Taro Webpack](/docs/quick-start/v4/taro-webpack) |
185+
| Taro | Vite | [Taro Vite](/docs/quick-start/frameworks/taro) | [Taro Vite](/docs/quick-start/v4/taro-vite) |
186+
| 原生小程序 | weapp-vite | [原生小程序](/docs/quick-start/native/install) | [Weapp-vite](/docs/quick-start/v4/weapp-vite) |
187+
| Mpx | Webpack | [Mpx](/docs/quick-start/frameworks/mpx) | [Mpx](/docs/quick-start/v4/mpx) |
188+
| Rax | Webpack | [Rax](/docs/quick-start/frameworks/rax) | 暂无单独页面，可参考 Webpack 通用写法 |
189+
| Node.js API | 自定义构建 | [Node.js API](/docs/quick-start/frameworks/api) | [Tailwind CSS 4.x 参考](/docs/quick-start/v4) |
190+
191+
## 6. 运行与验证
192+
193+
完成配置后，运行对应框架的小程序构建命令，例如：
194+
195+
```bash
196+
pnpm dev:mp-weixin
197+
```
198+
199+
或：
200+
201+
```bash
202+
pnpm dev:weapp
203+
```
204+
205+
然后在页面里写一个容易观察的类名：
206+
207+
```html
208+
<view class="mt-4 rounded bg-sky-500 p-4 text-white">Hello weapp-tailwindcss</view>
209+
```
210+
211+
如果样式没有生效，优先检查这几项：
212+
213+
| 检查项 | Tailwind CSS 3.x | Tailwind CSS 4.x |
214+
| --- | --- | --- |
215+
| CSS 入口 | 是否写了 `@tailwind base;` 等指令 | 是否写了 `@import "tailwindcss";` |
216+
| 扫描范围 | `tailwind.config.js` 的 `content` 是否包含源码 | CSS 入口的 `@source` 是否包含源码 |
217+
| 构建器插件 | `cssEntries` 是否指向入口 CSS 绝对路径 | `cssEntries` 是否指向入口 CSS 绝对路径 |
218+
| PostCSS | 是否误注册了 `tailwindcss` | 是否误注册了 `@tailwindcss/postcss` |
219+
| 产物目录 | 是否误扫 `dist` / `unpackage` | 是否误扫 `dist` / `unpackage` |
80220

81-
## 5. 旧项目迁移检查
221+
## 7. 旧项目迁移
82222

83223
| 旧配置 | 新处理方式 |
84224
| --- | --- |
85225
| `postinstall: "weapp-tw patch"` | 删除，v5 不需要手动 patch |
86-
| `postcss.config.js` 中的 `tailwindcss` | 删除，由 `WeappTailwindcss` 生成 |
87-
| 过宽的 `content: ['./src/**/*']` | 收窄到业务目录，并排除第三方和产物目录 |
226+
| `postcss.config.js` 中的 `tailwindcss` / `@tailwindcss/postcss` | 删除，由 `WeappTailwindcss` 生成 |
227+
| 过宽的扫描范围 | 收窄到业务目录，并排除第三方和产物目录 |
88228
| 没有 `cssEntries` | 在构建器插件中传入 Tailwind CSS 入口绝对路径 |
89229

90-
下一步安装与确认 `weapp-tailwindcss`：请继续阅读 [安装 weapp-tailwindcss](/docs/quick-start/this-plugin)。
230+
更多 Tailwind CSS 4.x 的背景、`@apply`、`@layer` 和 IntelliSense 说明，请继续阅读 [Tailwind CSS 4.x 参考](/docs/quick-start/v4)。

0 commit comments

Comments
 (0)