跳到主要内容

Interface: UserDefinedOptions

0.重要配置​

cssPreflight?​

optional cssPreflight: CssPreflightOptions

Issue​

https://github.com/sonofmagic/weapp-tailwindcss/issues/7

Description​

在所有 view节点添加的 css 预设，可根据情况自由的禁用原先的规则，或者添加新的规则。默认预置 css 同 tailwindcss 类似，详细用法如下:

// default 默认，这代表会添加给所有的 view / text 元素, 受到 cssPreflightRange 配置项影响 :
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:185

cssPreflightRange?​

optional cssPreflightRange: "all"

Issue​

https://github.com/sonofmagic/weapp-tailwindcss/pull/62

Description​

全局dom选择器，只有在这个选择器作用范围内的dom会被注入 cssPreflight 的变量和默认样式。只对所有的 view,text 和伪元素生效，想要对所有的元素生效，可切换为 'all',此时需要自行处理和客户端默认样式的冲突

Defined in​

types.ts:192

cssSelectorReplacement?​

optional cssSelectorReplacement: object

root?​

optional root: string | false | string[]

Default​

'page'

Description​

把css中的全局选择器 :root 替换为指定值，默认替换为 'page'，设置为 false 时不进行替换

universal?​

optional universal: string | false | string[]

Issue​

https://github.com/sonofmagic/weapp-tailwindcss/issues/81

Default​

['view','text']

Description​

把css中的全局选择器 * 替换为指定值，默认替换为 'view','text'，设置为 false 时不进行替换，此时小程序会由于不认识*选择器而报错

Description​

用于处理 css 选择器的替换

Defined in​

types.ts:412

customAttributes?​

optional customAttributes: ICustomAttributes

Description​

这是一个重要的配置!

它可以自定义wxml标签上的attr转化属性。默认转化所有的class和hover-class，这个Map的 key为匹配标签，value为属性字符串或者匹配正则数组。

如果你想要增加，对于所有标签都生效的转化的属性，你可以添加 *: (string | Regexp)[] 这样的键值对。(* 是一个特殊值，代表所有标签)

更复杂的情况，可以传一个 Map<string | Regex, (string | Regex)[]>实例。

假如你要把 className 通过组件的prop传递给子组件，又或者想要自定义转化的标签属性时，需要用到此配置，案例详见：issue#129,issue#134

Example​

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` 的值
 'ice-button': ['testClass']
}

当然你可以根据自己的需求，定义单个或者多个正则/字符串。

甚至有可能你编写正则表达式，它们匹配的范围，直接包括了插件里自带默认的 class/hover-class，那么这种情况下，你完全可以取代插件的默认模板转化器，开启 disabledDefaultTemplateHandler 配置项,禁用默认的模版匹配转化器。

Defined in​

types.ts:260

customReplaceDictionary?​

optional customReplaceDictionary: Record<string, string>

Description​

自定义转化class名称字典，这个配置项用来自定义转化class名称字典,你可以使用这个选项来简化生成的class

插件中默认使用'simple'模式:

  • 'simple'模式: 把小程序中不允许的字符串，转义为相等长度的代替字符串，这种情况不追求转化目标字符串的一比一绝对等价，即无法从生成结果，反推原先的class

当然，你也可以自定义，传一个 Record<string, string> 类型，只需保证转化后 css 中的 class 选择器，不会和自己定义的 class 产生冲突即可，示例见dic.ts

Default​

SimpleMappingChars2String

Defined in​

types.ts:272

disabled?​

optional disabled: boolean

Description​

是否禁用此插件，一般用于构建到多平台时使用，比如小程序时不传，非小程序环境(h5,app)传入一个 true

Defined in​

types.ts:198

injectAdditionalCssVarScope?​

optional injectAdditionalCssVarScope: boolean

Version​

^2.6.0

Description​

是否注入额外的 tailwindcss css var scope 区域，这个选项用于这样的场景

比如 taro vue3 使用 NutUI, 需要使用 @tarojs/plugin-html，而这个插件会启用 postcss-html-transform 从而移除所有带 * 选择器

这会导致 tailwindcss css var scope 区域被移除导致一些样式，比如渐变等等功能失效

这种场景下，启用这个选项会再次重新注入整个 tailwindcss css var scope

Default​

false

Defined in​

types.ts:383

jsAstTool?​

optional jsAstTool: "babel" | "ast-grep"

Version​

^3.1.0

Description​

对解析 js 使用的 ast 工具，默认情况使用 babel，可以通过安装 @ast-grep/napi，同时启用 ast-grep 配置项，来启用 ast-grep 来处理 js，速度会是 babel 的 2 倍左右

Defined in​

types.ts:451

rem2rpx?​

optional rem2rpx: boolean | UserDefinedOptions

Version​

^3.0.0

Description​

rem 转 rpx 配置，默认为 undefined 不开启，可传入 true 启用默认配置项，也可传入自定义配置项，配置项列表见 postcss-rem-to-responsive-pixel

Defined in​

types.ts:437

1.文件匹配​

cssMatcher()?​

optional cssMatcher: (name) => boolean

Parameters​

• name: string

Returns​

boolean

Description​

匹配 wxss 等等样式文件的方法

Defined in​

types.ts:129

htmlMatcher()?​

optional htmlMatcher: (name) => boolean

Parameters​

• name: string

Returns​

boolean

Description​

匹配 wxml等等模板进行处理的方法

Defined in​

types.ts:124

inlineWxs?​

optional inlineWxs: boolean

Experiment​

实验性质，有可能会改变

Description​

是否转义 wxml 中内联的 wxs

tip: 记得在 tailwind.config.js 中，把 wxs 这个格式加入 content 配置项，不然不会生效

Example​

<!-- 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​

false

Defined in​

types.ts:368

jsMatcher()?​

optional jsMatcher: (name) => boolean

Parameters​

• name: string

Returns​

boolean

Description​

匹配编译后 js 文件进行处理的方法

Defined in​

types.ts:134

mainCssChunkMatcher()?​

optional mainCssChunkMatcher: (name, appType?) => boolean

Parameters​

• name: string

• appType?: AppType

Returns​

boolean

Description​

tailwindcss css var inject scope 的匹配方法,用于处理原始变量和替换不兼容选择器。可以不传，但是遇到某些 ::before/::after 选择器注入冲突时，建议传入参数手动指定 css bundle 文件位置

Defined in​

types.ts:140

wxsMatcher()?​

optional wxsMatcher: (name) => boolean

Parameters​

• name: string

Returns​

boolean

Experiment​

实验性质，有可能会改变

Description​

各个平台 wxs 文件的匹配方法,可以设置为包括微信的 .wxs,支付宝的 .sjs 和 百度小程序的 .filter.js

tip: 记得在 tailwind.config.js 中，把 wxs 这个格式加入 content 配置项，不然不会生效

Default​

()=>false

Defined in​

types.ts:345

2.生命周期​

onEnd()?​

optional onEnd: () => void

Returns​

void

Description​

结束处理时调用

Defined in​

types.ts:229

onLoad()?​

optional onLoad: () => void

Returns​

void

Description​

plugin apply 初调用

Defined in​

types.ts:210

onStart()?​

optional onStart: () => void

Returns​

void

Description​

开始处理时调用

Defined in​

types.ts:215

onUpdate()?​

optional onUpdate: (filename, oldVal, newVal) => void

Parameters​

• filename: string

• oldVal: string

• newVal: string

Returns​

void

Description​

匹配成功并修改文件内容后调用

Defined in​

types.ts:224

3.一般配置​

appType?​

optional appType: AppType

Description​

使用的框架类型(uni-app,taro...)，用于找到主要的 css bundle 进行转化，这个配置会影响默认方法 mainCssChunkMatcher 的行为，不传会去猜测 tailwindcss css var inject scope (tailwindcss 变量注入的位置) 的位置

Defined in​

types.ts:294

arbitraryValues?​

optional arbitraryValues: IArbitraryValues

Description​

针对 tailwindcss arbitrary values 的一些配置

Defined in​

types.ts:307

babelParserOptions?​

optional babelParserOptions: ParserOptions

Version​

^3.2.0

Description​

对解析 js 使用的 @babel/parser 工具的配置

Defined in​

types.ts:457

cache?​

optional cache: boolean | ICreateCacheReturnType

Version​

^3.0.11

Description​

缓存策略

Defined in​

types.ts:444

cssChildCombinatorReplaceValue?​

optional cssChildCombinatorReplaceValue: string | string[]

Description​

用于控制 tailwindcss 子组合器的生效标签范围, 这里我们用一个例子来说明这个配置是干啥用的.

我们布局的时候往往会使用 space-x-4 那么实际上会生成这样的css选择器:

.space-x-4>:not([hidden])~:not([hidden]){}

然而很不幸，这个选择器在小程序中是不支持的，写了会报错导致编译失败。 所以出于保守起见，我把它替换为了：

.space-x-4>view + view{}

这同时也是默认值, 而这个选项就允许你进行自定义子组合器的行为

你可以传入一个 字符串，或者字符串数组

  1. 传入字符串数组,比如 ['view','text'] 生成:
.space-y-4>view + view,text + text{}
  1. 传入一个字符串，此时行为变成了整个替换，比如 'view,text,button,input ~ view,text,button,input' 生成:
.space-y-4>view,text,button,input ~ view,text,button,input{}

Default​

'view + view'

Defined in​

types.ts:336

cssRemoveHoverPseudoClass?​

optional cssRemoveHoverPseudoClass: boolean

Version​

^3.2.1

Issue​

https://github.com/sonofmagic/weapp-tailwindcss/issues/293

Default​

true

Description​

是否删除 css :hover 选择器节点，默认为 true, 原因在于，小程序 css :hover 是不生效的，要使用 view 这种标签的 hover-class 属性

Defined in​

types.ts:471

customRuleCallback?​

optional customRuleCallback: CustomRuleCallback

Description​

用于自定义处理 css 的回调函数，可根据 Postcss walk 方法自由定制处理方案的 callback 方法

Defined in​

types.ts:204

disabledDefaultTemplateHandler?​

optional disabledDefaultTemplateHandler: boolean

Version​

^2.6.2

Description​

开启此选项，将会禁用默认 wxml 模板替换器，此时模板的匹配和转化将完全被 customAttributes 接管，

此时你需要自己编写匹配之前默认 class/hover-class，以及新的标签属性的正则表达式regex

Default​

false

Defined in​

types.ts:401

jsPreserveClass()?​

optional jsPreserveClass: (keyword) => undefined | boolean

Parameters​

• keyword: string

Returns​

undefined | boolean

Version​

^2.6.1

Description​

当 tailwindcss 和 js 处理的字面量撞车的时候，配置此选项可以用来保留js字面量，不进行转义处理。返回值中，想要当前js字面量保留，则返回 true。想要转义则返回 false/undefined

Default​

保留所有带 * js字符串字面量

Defined in​

types.ts:391

mangle?​

optional mangle: boolean | IMangleOptions

Description​

是否压缩混淆 wxml,js 和 wxss 中指定范围的 class 以避免选择器过长问题，默认为false不开启，详细配置见 unplugin-tailwindcss-mangle

Url​

https://github.com/sonofmagic/tailwindcss-mangle

Defined in​

types.ts:301

postcssOptions?​

optional postcssOptions: Partial<Omit<Result, "file">>

Version​

^3.2.0

Description​

对解析 css 使用的 postcss 工具的配置

Defined in​

types.ts:463

supportCustomLengthUnitsPatch?​

optional supportCustomLengthUnitsPatch: boolean | ILengthUnitsPatchOptions

Issue​

https://github.com/sonofmagic/weapp-tailwindcss/issues/110

Description​

自从tailwindcss 3.2.0对任意值添加了长度单位的校验后，小程序中的rpx这个wxss单位，由于不在长度合法名单中，于是被识别成了颜色，导致与预期不符，详见：issues/110。所以这个选项是用来给tailwindcss运行时，自动打上一个支持rpx单位的补丁。默认开启，在绝大部分情况下，你都可以忽略这个配置项，除非你需要更高级的自定义。

目前自动检索可能存在一定的缺陷，它会在第一次运行的时候不生效，关闭后第二次运行才生效。这是因为 nodejs 运行时先加载好了 tailwindcss 模块 ，然后再来运行这个插件，自动给 tailwindcss 运行时打上 patch。此时由于 tailwindcss 模块已经加载，所以 patch 在第一次运行时不生效，ctrl+c 关闭之后，再次运行才生效。这种情况可以使用:

"scripts": {
+  "postinstall": "weapp-tw patch"
}

使用 npm hooks 的方式来给 tailwindcss 自动打 patch

Defined in​

types.ts:288

tailwindcssBasedir?​

optional tailwindcssBasedir: string

Version​

^2.9.3

Description​

用于指定路径来获取 tailwindcss 上下文，一般情况下不用传入，使用 linked / monorepo 可能需要指定具体位置，路径通常是目标项目的 package.json 所在目录

Defined in​

types.ts:431