Skip to content

take tailwindcss jit engine to weapp ! 把 tailwindcss jit 引擎,带入小程序开发吧 !

License

Notifications You must be signed in to change notification settings

wozco/weapp-tailwindcss-webpack-demo

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

logo

weapp-tailwindcss-webpack-plugin

star dm license test codecov weapp-tailwindcss-webpack-plug

tailwindcss JIT 思想带入小程序开发吧!

笔者之前写了一个 tailwindcss-miniprogram-preset,可是那个方案不能兼容最广泛的 Just in time 引擎,在写法上也有些变体。

于是笔者又写了一个 weapp-tailwindcss-webpack-plugin,这是一个 plugin 合集,包含 webpack/vite plugin,它会同时处理类 wxmlwxss 文件,从而我们开发者,不需要更改任何代码,就能让 jit 引擎兼容微信小程序。

此方案可兼容 tailwindcss v2/v3webpack v4/v5postcss v7/v8

随着 @vue/cli-service v5 版本的发布,uni-app 到时候也会转为 webpack5 + postcss8 的组合,到时候,我会升级一下 uni-app 的示例,让它从 tailwindcss v2 jit 升级到 tailwindcss v3 jit,相关进度见 uni-app/issues/3723

Usage

uni-app (vue2/3)

使用方式 | @vue/cli4 Demo 项目 | @vue/cli5 Demo 项目

uni-app for vite (vue3)

使用方式 | Demo 项目

Taro v3 (react | vue2/3)

使用方式(webpack4/5) | React Demo 项目 | vue2 Demo 项目 | vue3 Demo 项目

mpx (原生增强)

使用方式 | Demo 项目

remax (react)

使用方式 | Demo 项目

rax (react)

使用方式 | Demo 项目

原生小程序(webpack5 mina)

使用方式 | Demo 项目

HBuilderX 创建的项目

vue2 使用方式 | vue2 Demo 项目 | vue3 使用方式 | vue3 Demo 项目

uni-app 构建成 android/ios app

使用方式

unocss 集成

你可以不使用 tailwindcss,只需正常安装 unocss @unocss/preset-wind@unocss/transformer-directives 即可

unocss 文档方式注册后,安装使用此插件,即可正常使用。

Options 配置项

htmlMatcher

类型: ((assetPath:string)=>boolean)|string|string[]
描述: 匹配 wxml等等模板进行处理的方法

cssMatcher

类型: ((assetPath:string)=>boolean)|string|string[]
描述: 匹配 wxss等等样式文件的方法

jsMatcher

类型: ((assetPath:string)=>boolean)|string|string[]
描述: 匹配 js文件进行处理的方法,用于jsx相关模板

mainCssChunkMatcher

类型: (assetPath:string)=>boolean
描述: 匹配 tailwindcss jit 生成的核心 css chunk 的方法

framework (Taro 特有)

类型: react|vue2|vue3
描述: 由于 Taro 不同框架的编译结果有所不同,需要显式声明框架类型 默认react

customRuleCallback

类型: (node: Postcss.Rule, options: Readonly<RequiredStyleHandlerOptions>) => void
描述: 可根据 Postcss walk 自由定制处理方案的 callback 方法

disabled

类型: boolean
描述: 是否禁用该插件,默认为 false,一般用于多平台构建,有些平台比如 h5 不需要开启此插件,所以可以根据环境变量进行禁用。

cssPreflightRange

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

replaceUniversalSelectorWith

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

customAttributes

类型: Record<string, string | Regexp | (string | Regexp)[]>
描述: 这是一个重要的配置!

它可以自定义wxml标签上的attr转化属性。默认转化所有的classhover-class,这个Mapkey为匹配标签,value为属性字符串或者匹配正则数组。如果你想要增加转化的属性,你可以添加 *: (string | Regexp)[] 这样的键值对,使其中属性的转化,在所有标签上生效,更复杂的情况,可以传一个Map实例。

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

customReplaceDictionary

类型: 'simple' | 'complex' | Record<string, string>
描述: 默认为 'complex' 模式,这个配置项,用来自定义转化class名称字典,你可以使用这个选项来简化生成的class

插件中内置了'simple'模式和'complex'模式:

  • 'simple'模式: 把小程序中不允许的字符串,转义为相等长度的代替字符串,这种情况不追求转化目标字符串的一比一绝对等价,即无法从生成结果,反推原先的class
  • 'complex'模式: 把小程序中不允许的字符串,转义为更长的代替字符串,这种情况转化前后的字符串是等价的,可以从结果进行反推,缺点就是会生成更长的 class 导致 wxmlwxss这类的体积增大

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

cssPreflight

类型: Record<string,string>| false
描述: 在所有 view节点添加的 css 预设,可根据情况自由的禁用原先的规则,或者添加新的规则。 详细用法如下:

// default 默认:
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

supportCustomLengthUnitsPatch

类型: ILengthUnitsPatchOptions | boolean
描述: 自从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

使用 arbitrary values

详见 tailwindcss/using-arbitrary-values 章节 | Sample

关于rem转化rpx

假如你想要把项目里,所有满足条件的 rem 都转化成 rpx,那么 postcss plugin: postcss-rem-to-responsive-pixel 适合你。

假如你想缩小一下范围,只把 tailwindcss 中默认的工具类的单位(非jit生成的class),从 rem 转变为 rpx,那么 tailwindcss preset: tailwindcss-rem2px-preset 适合你。

使用方式见 Demo 和对应 npm 包的文档。

常见问题

目前微信开发者工具会默认开启 代码自动热重载 (compileHotReLoad) 功能,这个功能在原生开发中表现良好,但在 uni-apptaro 等等的框架中,存在一定的问题,详见issues#37,所以如果你遇到了此类问题,建议关闭 代码自动热重载 功能。

常见问题见 FAQ.md

Related projects

CLI 工具

weapp-ide-cli: 一个微信开发者工具命令行,快速方便的直接启动 ide 进行登录,开发,预览,上传代码等等功能。

模板 template

如何选择?

假如你仅仅是开发一个小程序 + h5 的组合,那么使用 vscode 模板就足够了

假如你的项目构建的重点平台是 app 那么还是推荐使用 hbuilderx 模板,因为 hbuilderx 自带了一套 app 构建和调试的工具链,可以更好的支持你的开发。

使用uni-app cli进行构建 vscode开发

uni-app-vite-vue3-tailwind-vscode-template

uni-app-vue3-tailwind-vscode-template

uni-app-vue2-tailwind-vscode-template

weapp-native-mina-tailwindcss-template

使用hbuilderx 进行构建和开发

uni-app-vue2-tailwind-hbuilder-template

uni-app-vue3-tailwind-hbuilder-template

tailwindcss plugin

weapp-tailwindcss-children

tailwindcss preset

tailwindcss-miniprogram-preset

Bugs & Issues

目前这个插件正在快速的开发中,如果遇到 Bug 或者想提出 Issue

欢迎提交到此处

About

take tailwindcss jit engine to weapp ! 把 tailwindcss jit 引擎,带入小程序开发吧 !

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 98.0%
  • JavaScript 2.0%