跳到主要内容

Interface: UserDefinedOptions

0.重要配置

cssPreflight?

optional cssPreflight: CssPreflightOptions

Issue

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

Description

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

// 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转化属性。默认转化所有的classhover-class,这个Mapkey为匹配标签,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,速度会是 babel2 倍左右

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

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

Default

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

Defined in

types.ts:391


mangle?

optional mangle: boolean | IMangleOptions

Description

是否压缩混淆 wxml,jswxss 中指定范围的 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