Skip to content

Commit 96fe4a1

Browse files
baiwusanyu-cbaiwusanyu-c
authored
docs: update README.ZH-CN.md (#7)
1 parent 7e93772 commit 96fe4a1

File tree

5 files changed

+281
-25
lines changed

5 files changed

+281
-25
lines changed

‎README.ZH-CN.md‎

Lines changed: 138 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,21 @@
1010
* 🌊 TODO
1111
* ⛰ TODO
1212

13+
## Core Process
14+
15+
```mermaid
16+
graph LR
17+
A[vite] -- plugin --> B((unplugin-vue-cssvars))
18+
B -- 1.预处理项目中css文件 --> C(生成CSS Module Map获得包含 v-bind 的 css 代码等信息)
19+
C --> D
20+
B -- 2.基于步骤1与vue编译器 --> D(根据 SFC 组件信息获得其引用的 CSS Module)
21+
D --> E
22+
B -- 3.基于vue编译器 --> E(提取 SFC 组件变量)
23+
E --> F
24+
B -- 4.注入提升代码 --> F(匹配CSS Module 与 SFC 变量注入代码)
25+
F --> G((vitejs/plugin-vue))
26+
```
27+
1328
## Install
1429

1530
```bash
@@ -108,31 +123,142 @@ build({
108123
```typescript
109124
export interface Options {
110125
/**
111-
* Provide path which will be transformed
112-
*
126+
* 需要转换的路径，默认是项目根目录
113127
* @default process.cwd()
114128
*/
115129
rootDir?: string
116130
/**
117-
* RegExp or glob to match files to be transformed
131+
* 需要转换的文件名后缀列表（目前只支持.vue）RegExp or glob
118132
*/
119133
include?: FilterPattern
120134

121135
/**
122-
* RegExp or glob to match files to NOT be transformed
136+
* 不需要转换的文件名后缀列表（目前只支持.vue）RegExp or glob
123137
*/
124138
exclude?: FilterPattern
125139

126140
/**
127-
* unplugin-vue-cssvars depends on the vue compiler,
128-
* there may be duplicate css after packaging, here we clear it
141+
* `unplugin-vue-cssvars` 只是做了样式提升注入，其编译依旧依赖于 `@vue/compiler-dom`
142+
* 在某些时候可能会生成重复的 `css` 代码(一般不会，因为打包时会将重复代码删除)，例如 `vite` 中关闭构建
143+
* 时压缩选项，`revoke` 则可以在打包时将注入的代码删除
129144
*/
130145
revoke?: boolean
131146
}
132147
```
133-
## Tips TODO
134-
### 转换分析时的约定规则
135-
1. sfc 中，如果 @import 指定了后缀，则根据后缀的文件进行转换分析，否则根据当前 script 标签的 lang 属性（默认css）进行转换分析。
136-
2. css中规则：css文件只能引用 css 文件，只会解析 css 后缀的文件
137-
3. scss、less、stylus 中规则：scss、less、stylus文件可以引用 css 文件、以及对应的scss或less文件或stylus文件，则对同名文件的css文件和对应的预处理器后缀文件进行转换分析
138-
## Thanks TODO
148+
### 关于 revoke 详细说明
149+
有如下两个文件 `App.vue` 和 `test.css`
150+
````
151+
<script setup lang="ts">
152+
const color = 'red'
153+
</script>
154+
155+
<template>
156+
<div class="test">
157+
TEST
158+
</div>
159+
</template>
160+
161+
<style scoped>
162+
@import "./assets/test";
163+
</style>
164+
165+
````
166+
````
167+
/** test.css **/
168+
div {
169+
color: v-bind(color);
170+
}
171+
````
172+
当未使用 `unplugin-vue-cssvars` 使用 `vite` 构建后
173+
````
174+
/** test.css **/
175+
div[data-v-2e7c9788] {
176+
color: var(--8bcabd20);
177+
}
178+
````
179+
其中 `color: var(--8bcabd20);` 的哈希并不会出现在组件打包产物中，因为 `vue` 不支持在文件中使用 `v-bind`。
180+
当使用 `unplugin-vue-cssvars` 使用 `vite` 构建后（`minify: false`）
181+
````
182+
/** test.css **/
183+
div[data-v-1dfefb04] {
184+
color: var(--516b0d4a);
185+
}
186+
187+
/* created by @unplugin-vue-cssvars */
188+
/* <inject start> */
189+
div[data-v-1dfefb04]{color:var(--516b0d4a)}
190+
/* <inject end> */
191+
````
192+
可以看到通过 `unplugin-vue-cssvars` 会生成注入代码，并且依赖于 `@vue/compiler-dom`，其哈希值能够出现在组件打包产物中。
193+
但是观察发现，这段代码是重复的。因此，开启 `revoke` 选项，将移除重复代码
194+
````
195+
/** test.css **/
196+
div[data-v-1dfefb04] {
197+
color: var(--516b0d4a);
198+
}
199+
````
200+
201+
## Tips
202+
203+
### ● 转换分析时的约定规则
204+
1. `sfc` 中，如果 `@import` 指定了后缀，则根据后缀的文件进行转换分析，否则根据当前 `script` 标签的 `lang` 属性（默认 `css` ）进行转换分析
205+
2. `css` 中规则：`css` 文件只能引用 `css` 文件，只会解析 `css` 后缀的文件。
206+
3. `scss`、`less`、`stylus` 中规则：`scss`、`less`、`stylus文件可以引用` `css` 文件、以及对应的 `scss` 或 `less` 文件或 `stylus` 文件，
207+
则对同名文件的 `css` 文件和对应的预处理器后缀文件进行转换分析。
208+
209+
### ● sfc 中变量提取规则
210+
1. 对于 `script setup`, `unplugin-vue-cssvars` 会提取所有变量进行匹配。
211+
````
212+
<script setup>
213+
const color = 'red'
214+
</script>
215+
````
216+
2. 对于 `composition api`, `unplugin-vue-cssvars` 会提取 `setup` 函数返回变量进行匹配。
217+
````
218+
<script>
219+
export default {
220+
setup(){
221+
const color = 'red'
222+
return {
223+
color
224+
}
225+
}
226+
}
227+
</script>
228+
````
229+
3. 对于 `options api`, `unplugin-vue-cssvars` 会提取 `data` 函数返回变量进行匹配。
230+
````
231+
<script>
232+
export default {
233+
data(){
234+
const color = 'red'
235+
return {
236+
color
237+
}
238+
}
239+
}
240+
</script>
241+
````
242+
4. 对于普通的 `script`, `unplugin-vue-cssvars` 会提取所有变量进行匹配。
243+
````
244+
<script>
245+
const color = 'red'
246+
</script>
247+
````
248+
249+
### ● sfc 中变量冲突规则
250+
1. `sfc` 中有 `options api` 与 `composition api`, 所有变量会进行合并
251+
变量出现冲突以后面出现的（比如先写了 `options api`，后写 `composition api`，以 `composition api` 优先）优先
252+
2. `sfc` 中有 `script setup`、`options api` 与 `composition api`, 所有变量会进行合并，变量出现冲突以`script setup`优先
253+
3. `sfc` 中普通的 `script`，不会与`options api` 、 `composition api`同时存在
254+
4. `sfc` 中普通的 `script`若存在，则必存在`script setup`
255+
5. `sfc` 中普通的 `script`与 `script setup` 所有变量会进行合并,变量出现冲突以`script setup`优先
256+
257+
### ● 样式提升后的优先级
258+
1. 从 `sfc` 开始，分析 `style` 标签中引用的 `css` 文件，按照 `css` 文件中的引用顺序，深度优先依次提升并注入到 `sfc` 中。
259+
2. 注入到 `sfc` 后，其优先级完全由 `@vue/compiler-dom` 的编译器决定。
260+
261+
## Thanks
262+
* [vue](https://github.com/vuejs/core)
263+
* [vite](https://github.com/vitejs/vite)
264+
* [unplugin](https://github.com/unjs/unplugin)

‎README.md‎

Lines changed: 139 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# unplugin-vue-cssvars
22
🌀 A vue plugin that allows you to use vue's CSSVars feature in css files
33

4-
English | [中文](https://github.com/baiwusanyu-c/unplugin-vue-cssvars/blob/master/README.ZH-CN.md)
4+
[English](https://github.com/baiwusanyu-c/unplugin-vue-cssvars/blob/master/README.md) | 中文
55

66
## Feature (TODO)
77

@@ -10,6 +10,21 @@ English | [中文](https://github.com/baiwusanyu-c/unplugin-vue-cssvars/blob/mas
1010
* 🌊 TODO
1111
* ⛰ TODO
1212

13+
## Core Process
14+
15+
```mermaid
16+
graph LR
17+
A[vite] -- plugin --> B((unplugin-vue-cssvars))
18+
B -- 1.预处理项目中css文件 --> C(生成CSS Module Map获得包含 v-bind 的 css 代码等信息)
19+
C --> D
20+
B -- 2.基于步骤1与vue编译器 --> D(根据 SFC 组件信息获得其引用的 CSS Module)
21+
D --> E
22+
B -- 3.基于vue编译器 --> E(提取 SFC 组件变量)
23+
E --> F
24+
B -- 4.注入提升代码 --> F(匹配CSS Module 与 SFC 变量注入代码)
25+
F --> G((vitejs/plugin-vue))
26+
```
27+
1328
## Install
1429

1530
```bash
@@ -90,7 +105,7 @@ module.exports = {
90105
</details>
91106
<br>
92107
<details>
93-
<summary>Esbuild</summary>
108+
<summary>esbuild</summary>
94109

95110
```ts
96111
// esbuild.config.js
@@ -108,27 +123,142 @@ build({
108123
```typescript
109124
export interface Options {
110125
/**
111-
* Provide path which will be transformed
112-
*
126+
* 需要转换的路径，默认是项目根目录
113127
* @default process.cwd()
114128
*/
115129
rootDir?: string
116130
/**
117-
* RegExp or glob to match files to be transformed
131+
* 需要转换的文件名后缀列表（目前只支持.vue）RegExp or glob
118132
*/
119133
include?: FilterPattern
120134

121135
/**
122-
* RegExp or glob to match files to NOT be transformed
136+
* 不需要转换的文件名后缀列表（目前只支持.vue）RegExp or glob
123137
*/
124138
exclude?: FilterPattern
125139

126140
/**
127-
* unplugin-vue-cssvars depends on the vue compiler,
128-
* there may be duplicate css after packaging, here we clear it
141+
* `unplugin-vue-cssvars` 只是做了样式提升注入，其编译依旧依赖于 `@vue/compiler-dom`
142+
* 在某些时候可能会生成重复的 `css` 代码(一般不会，因为打包时会将重复代码删除)，例如 `vite` 中关闭构建
143+
* 时压缩选项，`revoke` 则可以在打包时将注入的代码删除
129144
*/
130145
revoke?: boolean
131146
}
132147
```
148+
### 关于 revoke 详细说明
149+
有如下两个文件 `App.vue` 和 `test.css`
150+
````
151+
<script setup lang="ts">
152+
const color = 'red'
153+
</script>
154+
155+
<template>
156+
<div class="test">
157+
TEST
158+
</div>
159+
</template>
160+
161+
<style scoped>
162+
@import "./assets/test";
163+
</style>
164+
165+
````
166+
````
167+
/** test.css **/
168+
div {
169+
color: v-bind(color);
170+
}
171+
````
172+
当未使用 `unplugin-vue-cssvars` 使用 `vite` 构建后
173+
````
174+
/** test.css **/
175+
div[data-v-2e7c9788] {
176+
color: var(--8bcabd20);
177+
}
178+
````
179+
其中 `color: var(--8bcabd20);` 的哈希并不会出现在组件打包产物中，因为 `vue` 不支持在文件中使用 `v-bind`。
180+
当使用 `unplugin-vue-cssvars` 使用 `vite` 构建后（`minify: false`）
181+
````
182+
/** test.css **/
183+
div[data-v-1dfefb04] {
184+
color: var(--516b0d4a);
185+
}
186+
187+
/* created by @unplugin-vue-cssvars */
188+
/* <inject start> */
189+
div[data-v-1dfefb04]{color:var(--516b0d4a)}
190+
/* <inject end> */
191+
````
192+
可以看到通过 `unplugin-vue-cssvars` 会生成注入代码，并且依赖于 `@vue/compiler-dom`，其哈希值能够出现在组件打包产物中。
193+
但是观察发现，这段代码是重复的。因此，开启 `revoke` 选项，将移除重复代码
194+
````
195+
/** test.css **/
196+
div[data-v-1dfefb04] {
197+
color: var(--516b0d4a);
198+
}
199+
````
200+
201+
## Tips
202+
203+
### ● 转换分析时的约定规则
204+
1. `sfc` 中，如果 `@import` 指定了后缀，则根据后缀的文件进行转换分析，否则根据当前 `script` 标签的 `lang` 属性（默认 `css` ）进行转换分析
205+
2. `css` 中规则：`css` 文件只能引用 `css` 文件，只会解析 `css` 后缀的文件。
206+
3. `scss`、`less`、`stylus` 中规则：`scss`、`less`、`stylus文件可以引用` `css` 文件、以及对应的 `scss` 或 `less` 文件或 `stylus` 文件，
207+
则对同名文件的 `css` 文件和对应的预处理器后缀文件进行转换分析。
208+
209+
### ● sfc 中变量提取规则
210+
1. 对于 `script setup`, `unplugin-vue-cssvars` 会提取所有变量进行匹配。
211+
````
212+
<script setup>
213+
const color = 'red'
214+
</script>
215+
````
216+
2. 对于 `composition api`, `unplugin-vue-cssvars` 会提取 `setup` 函数返回变量进行匹配。
217+
````
218+
<script>
219+
export default {
220+
setup(){
221+
const color = 'red'
222+
return {
223+
color
224+
}
225+
}
226+
}
227+
</script>
228+
````
229+
3. 对于 `options api`, `unplugin-vue-cssvars` 会提取 `data` 函数返回变量进行匹配。
230+
````
231+
<script>
232+
export default {
233+
data(){
234+
const color = 'red'
235+
return {
236+
color
237+
}
238+
}
239+
}
240+
</script>
241+
````
242+
4. 对于普通的 `script`, `unplugin-vue-cssvars` 会提取所有变量进行匹配。
243+
````
244+
<script>
245+
const color = 'red'
246+
</script>
247+
````
248+
249+
### ● sfc 中变量冲突规则
250+
1. `sfc` 中有 `options api` 与 `composition api`, 所有变量会进行合并
251+
变量出现冲突以后面出现的（比如先写了 `options api`，后写 `composition api`，以 `composition api` 优先）优先
252+
2. `sfc` 中有 `script setup`、`options api` 与 `composition api`, 所有变量会进行合并，变量出现冲突以`script setup`优先
253+
3. `sfc` 中普通的 `script`，不会与`options api` 、 `composition api`同时存在
254+
4. `sfc` 中普通的 `script`若存在，则必存在`script setup`
255+
5. `sfc` 中普通的 `script`与 `script setup` 所有变量会进行合并,变量出现冲突以`script setup`优先
256+
257+
### ● 样式提升后的优先级
258+
1. 从 `sfc` 开始，分析 `style` 标签中引用的 `css` 文件，按照 `css` 文件中的引用顺序，深度优先依次提升并注入到 `sfc` 中。
259+
2. 注入到 `sfc` 后，其优先级完全由 `@vue/compiler-dom` 的编译器决定。
133260

134-
## Thanks TODO
261+
## Thanks
262+
* [vue](https://github.com/vuejs/core)
263+
* [vite](https://github.com/vitejs/vite)
264+
* [unplugin](https://github.com/unjs/unplugin)

‎packages/core/get-variable/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ import type { Node } from 'estree-walker'
1919
* @param descriptor
2020
*/
2121

22-
export const index = (descriptor: SFCDescriptor) => {
22+
export const getVariable = (descriptor: SFCDescriptor) => {
2323
let variableName = {} as VariableName
2424
// get variable name form setup script
2525
variableName = getVariableNameBySetup(setScriptContent(descriptor, 'setup'))

‎packages/core/index.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import { parse } from '@vue/compiler-sfc'
55
import { preProcessCSS } from './css/pre-process-css'
66
import { createCSSModule } from './css/process-css'
77
import { initOption } from './option'
8-
import { index } from './get-variable'
8+
import { getVariable } from './get-variable'
99
import { injectCSSVars } from './inject/inject-cssvars'
1010
import { revokeCSSVars } from './inject/revoke-cssvars'
1111
import type { IBundle, Options } from './types'
@@ -35,7 +35,7 @@ const unplugin = createUnplugin<Options>(
3535
if (id.endsWith('.vue')) {
3636
const { descriptor } = parse(code)
3737
const importCSSModule = createCSSModule(descriptor, id, preProcessCSSRes)
38-
const variableName = index(descriptor)
38+
const variableName = getVariable(descriptor)
3939
code = injectCSSVars(code, importCSSModule, variableName)
4040
console.log(code)
4141
}

0 commit comments

Comments
 (0)