Skip to content

Commit 4f1120a

Browse files
baiwusanyu-cbaiwusanyu-c
committed
docs: update README.md
1 parent 97024c0 commit 4f1120a

File tree

7 files changed

+59
-157
lines changed

7 files changed

+59
-157
lines changed

‎README.ZH-CN.md‎

Lines changed: 21 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,16 @@
66
## Feature
77

88
* 🧩 它是一个 vue 的功能扩展，让你能够在 css 文件中使用 v-bind
9-
* 🌈 支持全平台打包工具构建
9+
* 🌈 支持全平台打包工具构建（vite、webpack）
1010
* ⛰ 支持 css, sass, scss, less, stylus
1111
* ⚡ 轻量且快速
1212

13-
## Core Process
13+
## Core Strategy
14+
1.在使用开发服务器时，`unplugin-vue-cssvars`会从组件开始分析引用的css文件，
15+
并在`@vitejs/plugin-vue` 的转换代码中进行注入样式
16+
2.在打包时`unplugin-vue-cssvars`会从组件开始分析引用的css文件，并将其注入到
17+
sfc 中，别担心会产生多余的代码，打包工具（例如 vite）会自动处理它。
1418

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))
2619
```
2720
2821
## Install
@@ -45,13 +38,18 @@ pnpm add unplugin-vue-cssvars -D
4538

4639
```ts
4740
// vite.config.ts
48-
import { resolve } from 'path'
4941
import { defineConfig } from 'vite'
5042
import { viteVueCSSVars } from 'unplugin-vue-cssvars'
5143
import type { PluginOption } from 'vite'
44+
import vue from '@vitejs/plugin-vue'
5245
export default defineConfig({
5346
plugins: [
54-
viteVueCSSVars(/* options */) as PluginOption,
47+
vue(),
48+
viteVueCSSVars({
49+
include: [/.vue/],
50+
includeCompile: ['**/**.scss'],
51+
server: false,
52+
}) as PluginOption,
5553
],
5654
})
5755
```
@@ -63,7 +61,6 @@ export default defineConfig({
6361

6462
```ts
6563
// rollup.config.js
66-
import { resolve } from 'path'
6764
import { rollupVueCSSVars } from 'unplugin-vue-cssvars'
6865
export default {
6966
plugins: [
@@ -127,6 +124,7 @@ export interface Options {
127124
* @default process.cwd()
128125
*/
129126
rootDir?: string
127+
130128
/**
131129
* 需要转换的文件名后缀列表（目前只支持.vue）RegExp or glob
132130
*/
@@ -151,64 +149,16 @@ export interface Options {
151149
* @default ['** /**.css']
152150
*/
153151
includeCompile?: Array<string>
152+
153+
/**
154+
* 标记是否为开发服务器使用
155+
* 因为 unplugin-vue-cssvars uses 在开发服务器上和打包中使用了不同策略
156+
* @default true
157+
*/
158+
server?: boolean
154159
}
155160
```
156161

157-
### 关于 revoke 详细说明
158-
> 💡 正式版本以解决重复代码问题，正式版本不再需要设置
159-
160-
有如下两个文件 `App.vue` 和 `test.css`
161-
````
162-
<script setup lang="ts">
163-
const color = 'red'
164-
</script>
165-
166-
<template>
167-
<div class="test">
168-
TEST
169-
</div>
170-
</template>
171-
172-
<style scoped>
173-
@import "./assets/test";
174-
</style>
175-
176-
````
177-
````
178-
/** test.css **/
179-
div {
180-
color: v-bind(color);
181-
}
182-
````
183-
当未使用 `unplugin-vue-cssvars` 使用 `vite` 构建后
184-
````
185-
/** test.css **/
186-
div[data-v-2e7c9788] {
187-
color: var(--8bcabd20);
188-
}
189-
````
190-
其中 `color: var(--8bcabd20);` 的哈希并不会出现在组件打包产物中，因为 `vue` 不支持在文件中使用 `v-bind`。
191-
当使用 `unplugin-vue-cssvars` 使用 `vite` 构建后（`minify: false`）
192-
````
193-
/** test.css **/
194-
div[data-v-1dfefb04] {
195-
color: var(--516b0d4a);
196-
}
197-
198-
/* created by @unplugin-vue-cssvars */
199-
/* <inject start> */
200-
div[data-v-1dfefb04]{color:var(--516b0d4a)}
201-
/* <inject end> */
202-
````
203-
可以看到通过 `unplugin-vue-cssvars` 会生成注入代码，并且依赖于 `@vue/compiler-dom`，其哈希值能够出现在组件打包产物中。
204-
但是观察发现，这段代码是重复的。因此，开启 `revoke` 选项，将移除重复代码
205-
````
206-
/** test.css **/
207-
div[data-v-1dfefb04] {
208-
color: var(--516b0d4a);
209-
}
210-
````
211-
212162
## Tips
213163

214164
### ● 转换分析时的约定规则

‎README.md‎

Lines changed: 25 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,17 @@ English | [中文](https://github.com/baiwusanyu-c/unplugin-vue-cssvars/blob/mas
66
## Feature
77

88
* 🧩 It is a function extension of vue
9-
* 🌈 Compatible with multiple bundled platforms（vite、rollup、esbuild、webpack）
9+
* 🌈 Compatible with multiple bundled platforms（vite、webpack）
1010
* ⛰ Support css, sass, scss, less, stylus
1111
* ⚡ light and fast
1212

13-
## Core Process
13+
## Core Strategy
1414

15-
```mermaid
16-
graph LR
17-
A[vite] -- plugin --> B((unplugin-vue-cssvars))
18-
B -- 1.Preprocess css files in the project --> C(Generate CSS Module Map to obtain information such as css code including v-bind)
19-
C --> D
20-
B -- 2.Based on step 1 with vue compiler --> D(Obtain the referenced CSS Module according to the SFC component information)
21-
D --> E
22-
B -- 3.Based on vue compiler --> E(Extract SFC component tags)
23-
E --> F
24-
B -- 4.inject code --> F(Match CSS Module and SFC variable injection code)
25-
F --> G((vitejs/plugin-vue))
26-
```
15+
1.When using the development server,
16+
`unplugin-vue-cssvars` will analyze the referenced css file from the component,
17+
and inject styles in the transformation code of `@vitejs/plugin-vue`
18+
2.When building, `unplugin-vue-cssvars` will analyze the referenced css file from the component and inject it into
19+
sfc, don't worry about generating redundant code, packaging tools (such as vite) will automatically handle it.
2720

2821
## Install
2922

@@ -45,13 +38,18 @@ pnpm add unplugin-vue-cssvars -D
4538

4639
```ts
4740
// vite.config.ts
48-
import { resolve } from 'path'
4941
import { defineConfig } from 'vite'
5042
import { viteVueCSSVars } from 'unplugin-vue-cssvars'
5143
import type { PluginOption } from 'vite'
44+
import vue from '@vitejs/plugin-vue'
5245
export default defineConfig({
5346
plugins: [
54-
viteVueCSSVars(/* options */) as PluginOption,
47+
vue(),
48+
viteVueCSSVars({
49+
include: [/.vue/],
50+
includeCompile: ['**/**.scss'],
51+
server: false,
52+
}) as PluginOption,
5553
],
5654
})
5755
```
@@ -63,12 +61,11 @@ export default defineConfig({
6361

6462
```ts
6563
// rollup.config.js
66-
import { resolve } from 'path'
6764
import { rollupVueCSSVars } from 'unplugin-vue-cssvars'
6865
export default {
69-
plugins: [
70-
rollupVueCSSVars(/* options */),
71-
],
66+
plugins: [
67+
rollupVueCSSVars(/* options */),
68+
],
7269
}
7370
```
7471

@@ -124,10 +121,10 @@ build({
124121
export interface Options {
125122
/**
126123
* Provide path which will be transformed
127-
*
128124
* @default process.cwd()
129125
*/
130126
rootDir?: string
127+
131128
/**
132129
* RegExp or glob to match files to be transformed
133130
*/
@@ -151,63 +148,15 @@ export interface Options {
151148
* @default ['** /**.css']
152149
*/
153150
includeCompile?: Array<string>
151+
152+
/**
153+
* Flag whether to start with server at development time,
154+
* because unplugin-vue-cssvars uses different strategies for building and server development
155+
* @default true
156+
*/
157+
server?: boolean
154158
}
155159
```
156-
### Details about revoke
157-
> 💡 v1.0.0 version to solve the problem of duplicate code, no longer need to set
158-
159-
Suppose there are two files `App.vue` and `test.css`
160-
````
161-
<script setup lang="ts">
162-
const color = 'red'
163-
</script>
164-
165-
<template>
166-
<div class="test">
167-
TEST
168-
</div>
169-
</template>
170-
171-
<style scoped>
172-
@import "./assets/test";
173-
</style>
174-
175-
````
176-
````
177-
/** test.css **/
178-
div {
179-
color: v-bind(color);
180-
}
181-
````
182-
After building with `vite` when `unplugin-vue-cssvars` is not used
183-
````
184-
/** test.css **/
185-
div[data-v-2e7c9788] {
186-
color: var(--8bcabd20);
187-
}
188-
````
189-
Among them, the hash of `color: var(--8bcabd20);` will not appear in the component packaging product, because `vue` does not support the use of `v-bind` in the file.
190-
When built with `vite` using `unplugin-vue-cssvars` (`minify: false`)
191-
````
192-
/** test.css **/
193-
div[data-v-1dfefb04] {
194-
color: var(--516b0d4a);
195-
}
196-
197-
/* created by @unplugin-vue-cssvars */
198-
/* <inject start> */
199-
div[data-v-1dfefb04]{color:var(--516b0d4a)}
200-
/* <inject end> */
201-
````
202-
It can be seen that the code will be injected through `unplugin-vue-cssvars`, and it depends on `@vue/compiler-dom`, whose hash value can appear in the component packaging product.
203-
But observation found that this code is repetitive.
204-
Therefore, turning on the `revoke` option will remove duplicate code
205-
````
206-
/** test.css **/
207-
div[data-v-1dfefb04] {
208-
color: var(--516b0d4a);
209-
}
210-
````
211160

212161
## Tips
213162

‎packages/core/index.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,11 @@ const unplugin = createUnplugin<Options>(
4141
const {
4242
vbindVariableListByPath,
4343
injectCSSContent,
44-
} = getVBindVariableListByPath(descriptor, id, CSSFileModuleMap, !!userOptions.dev)
44+
} = getVBindVariableListByPath(descriptor, id, CSSFileModuleMap, !!userOptions.server)
4545
const variableName = getVariable(descriptor)
4646
vbindVariableList.set(id, matchVariable(vbindVariableListByPath, variableName))
4747

48-
if (!userOptions.dev)
48+
if (!userOptions.server)
4949
code = injectCssOnBuild(code, injectCSSContent, descriptor)
5050
}
5151
return code
@@ -61,7 +61,7 @@ const unplugin = createUnplugin<Options>(
6161
// ⭐TODO: 只支持 .vue ? jsx, tsx, js, ts ？
6262
try {
6363
// transform in dev
64-
if (userOptions.dev) {
64+
if (userOptions.server) {
6565
if (id.endsWith('.vue')) {
6666
const injectRes = injectCSSVars(code, vbindVariableList.get(id), isScriptSetup)
6767
code = injectRes.code

‎packages/core/option/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ const defaultOption: Options = {
1313
exclude: DEFAULT_EXCLUDE_REG,
1414
revoke: true,
1515
includeCompile: SUPPORT_FILE_LIST,
16-
dev: true,
16+
server: true,
1717
}
1818

1919
export function initOption(option: Options) {

‎packages/core/runtime/process-css.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ export const getVBindVariableListByPath = (
3535
descriptor: SFCDescriptor,
3636
id: string,
3737
cssFiles: ICSSFileMap,
38-
dev: boolean) => {
38+
server: boolean) => {
3939
const vbindVariable: Set<string> = new Set()
4040
const injectCSSContent = new Set<{ content: string, lang: string }>()
4141
// 遍历 sfc 的 style 标签内容
@@ -56,7 +56,7 @@ export const getVBindVariableListByPath = (
5656
// 根据 @import 信息，从 cssFiles 中，递归的获取所有在预处理时生成的 cssvars 样式
5757
getCSSFileRecursion(key, cssFiles, (res: ICSSFile) => {
5858
if (res.vBindCode) {
59-
!dev && injectCSSContent.add({ content: res.content, lang: res.lang })
59+
!server && injectCSSContent.add({ content: res.content, lang: res.lang })
6060
res.vBindCode.forEach((vb) => {
6161
vbindVariable.add(vb)
6262
})

‎packages/core/types.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@ import type { FilterPattern } from '@rollup/pluginutils'
33
export interface Options {
44
/**
55
* Provide path which will be transformed
6-
*
76
* @default process.cwd()
87
*/
98
rootDir?: string
9+
1010
/**
1111
* RegExp or glob to match files to be transformed
1212
*/
@@ -30,10 +30,13 @@ export interface Options {
3030
* @default ['** /**.css']
3131
*/
3232
includeCompile?: Array<string>
33+
3334
/**
34-
* TODO
35+
* Flag whether to start with server at development time,
36+
* because unplugin-vue-cssvars uses different strategies for packaging and server development
37+
* @default true
3538
*/
36-
dev?: boolean
39+
server?: boolean
3740
}
3841

3942
export declare type SearchGlobOptions = Options

‎play/vite.config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export default defineConfig({
2929
viteVueCSSVars({
3030
include: [/.vue/],
3131
includeCompile: ['**/**.scss'],
32-
dev: false,
32+
server: false,
3333
}),
3434
],
3535
})

0 commit comments

Comments
 (0)