Skip to content

Latest commit

 

History

History
296 lines (195 loc) · 14.7 KB

v1.md

File metadata and controls

296 lines (195 loc) · 14.7 KB
Raw

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，它会同时处理类 wxml 和 wxss 文件，从而我们开发者，不需要更改任何代码，就能让 jit 引擎兼容微信小程序。

此方案可兼容 tailwindcss v2/v3，webpack v4/v5，postcss 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转化属性。默认转化所有的class和hover-class，这个Map的 key为匹配标签，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 导致 wxml和wxss这类的体积增大

当然，你也可以自定义，传一个 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 章节

关于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-app 和 taro 等等的框架中，存在一定的问题，详见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

欢迎提交到此处