mini program tailwind

Mini Program Tailwind Webpack Plugin

讓你的小程式用上原汁原味的Tailwind/Windi CSS

來自Digital Creative, 一家位於上海的數位產品研究、設計與開發公司。

了解我們

• What we do
• About us
• Contact us

推薦閱讀獨立文件以獲得更好的閱讀體驗♥️

---

介紹

由於小程式本身不支援由Tailwind/Windi CSS 產生的選擇器名稱中包含的一些特殊轉義字元（如[ ! .等），這使得你在開發小程式時無法使用一些本該在開發Web 應用時所使用的得心應手的靈活語法與Arbitrary values/Value auto-infer 功能，如w-[30px] translate-x-1/2 !bg-[#ff0000]等。這無疑對我們的開發效率與心智負擔帶來了不小的影響。

為了突破這個限制，我們開發了這款外掛程式來幫助你在使用Tailwind/Windi CSS 開發小程式時仍然保持著與開發Web 應用程式高度一致的開發體驗，你不再需要關注因為哪些字串不被支援而不得不換一種寫法的問題，而是繼續按照Tailwind/Windi CSS 的官方語法繼續編寫你的小程式樣式，背後的兼容工作則由這款插件靜默處理。

此外，本插件還整合了rpx值自動轉換的功能。此功能可以將Tailwind/Windi CSS 設定檔中以及原始碼中我們所寫的rem與px單位的值在最終產生的樣式檔中自動轉換為rpx單位的值。這不僅可以讓開發者重複使用在Web 專案中使用的相同主題配置又可以讓小程式繼續使用responsive pixel 帶來的特性。

進一步了解本插件的工作原理

讓你的小程式用上原汁原味的Tailwind/Windi CSS

---

快速開始

選擇其中一個適合你的小程式類型進行插件安裝

常規Webpack 類別小程式（以MPX 為例）

常規Webpack 類別小程式（以MPX 為例）

MPX, 一款具有優秀開發體驗和深度效能最佳化的增強型跨端小程式框架。

由於MPX 框架為典型的以Webpack 為建構工具的增強型小程式開發框架，所以本次安裝示範將MPX 專案作為典型案例來示範如何為大部分Webpack 類別小型程式專案進行插件安裝。以下安裝步驟在Webpack 專案中具有廣泛的通用性，對於大部分Webpack 類別小程式專案只需參考相同步驟進行安裝即可。

安裝windicss-webpack-plugin

npm i windicss-webpack-plugin -D

參考Windi CSS 官方文件了解更多細節

Windi CSS Webpack 集成

安裝@dcasia/mini-program-tailwind-webpack-plugin

npm i @dcasia/mini-program-tailwind-webpack-plugin -D

更新webpack 設定檔

使用Webpack 插件

 //webpack.base.conf.js
const WindiCSSWebpackPlugin = require ( "windicss-webpack-plugin" ) ;
const MiniProgramTailwindWebpackPlugin = require ( "@dcasia/mini-program-tailwind-webpack-plugin" )

module . exports = {
  plugins : [
    new WindiCSSWebpackPlugin ( ) ,
    new MiniProgramTailwindWebpackPlugin ( {
      // options
    } )
  ]
} 

新建Windi CSS 設定文件

在專案根目錄新建windi.config.js設定檔

 //windi.config.js
export default {
  preflight : false ,
  prefixer : false ,
  extract : {
    // 将 .mpx 文件纳入范围（其余 Webpack 类小程序根据项目本身的文件后缀酌情设置）
    include : [ 'src/**/*.{css,html,mpx}' ] ,
    // 忽略部分文件夹
    exclude : [ 'node_modules' , '.git' , 'dist' ]
  } ,
  corePlugins : {
    // 禁用掉在小程序环境中不可能用到的 plugins
    container : false
  }
}

此處Tailwind CSS 設定檔同樣適用

參考Windi CSS 官方文件了解更多細節

Windi CSS 設定檔相容規則

在入口文件中引入Windi CSS 的產物

// app.mpx
< style src =" windi.css " > </ style >

對於其餘非MPX 專案的Webpack 類別小程序，可參考類似的方式在入口檔案中引入windi.css即可，如：

 // main.js
import 'windi.css'

參考Windi CSS 官方文件了解更多細節

引入Windi CSS 樣式文件

完成

開始享受在小程式專案中由Windi CSS 帶來的高效開發體驗?

可配置參數

名稱	類型	預設	描述
enableRpx	Boolean	true	是否開啟自動轉換至rpx 單位值的功能
designWidth	Number	350	設計稿的像素寬度值，尺寸會影響rpx 轉換過程中的計算比率
utilitiesSettings.spaceBetweenItems	Array<string>	[]	使用了Space Between utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項目。如需新增則可以在陣列中新增新的元件名稱。
utilitiesSettings.divideItems	Array<string>	[]	使用了Divide width utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項。如需新增則可以在陣列中新增新的元件名稱。

案例

整合案例：MPX 項目

? Taro 小程式

Taro 小程式

Taro, 多端統一開發解決方案

此插件包含Taro 插件，透過「一鍵安裝」的方式來方便的適配Taro 小程式。

Taro 外掛程式已相容於以下前端框架

• React
• Vue 2
• Vue 3
• Preact

同時也相容於在混合原生元件開發中使用Tailwind/Windi CSS

安裝@dcasia/mini-program-tailwind-webpack-plugin

 npm i @dcasia/mini-program-tailwind-webpack-plugin -D

使用Taro 插件

 // config/index.js
const config = {
  plugins : [
    [ '@dcasia/mini-program-tailwind-webpack-plugin/dist/taro' , {
      // ...options
    } ]
  ]
} 

新建Windi CSS 設定文件

在專案根目錄新建windi.config.js設定檔

 // windi.config.js
export default {
  prefixer : false ,
  extract : {
    // 忽略部分文件夹
    exclude : [ 'node_modules' , '.git' , 'dist' ]
  } ,
  corePlugins : {
    // 禁用掉在小程序环境中不可能用到的 plugins
    container : false
  }
}

此處Tailwind CSS 設定檔同樣適用

參考Windi CSS 官方文件了解更多細節

Windi CSS 設定檔相容規則

在入口文件中引入Windi CSS 的產物

 // app.js
import 'windi.css' ; 

完成

開始享受在Taro 中由Windi CSS 帶來的高效開發體驗?

可配置參數

名稱	類型	預設	描述
enableWindiCSS	Boolean	true	是否開啟插件自帶的Windi CSS
windiCSSConfigFile	String	讀取專案根目錄的設定檔	必要時手動設定Windi CSS 設定檔的路徑
enableRpx	Boolean	false	是否開啟自動轉換至rpx 單位值的功能（由於Taro 自帶此功能，預設為關閉）
designWidth	Number	375	設計稿的像素寬度值，尺寸會影響rpx 轉換過程中的計算比率
utilitiesSettings.spaceBetweenItems	Array<string>	[]	使用了Space Between utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項。如需新增則可以在陣列中新增新的元件名稱。
utilitiesSettings.divideItems	Array<string>	[]	使用了Divide width utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項。如需新增則可以在陣列中新增新的元件名稱。
utilitiesSettings.customComponents	Array<string>	[]	對於使用Uno CSS 作為Atomic CSS 引擎的開發者需要根據專案狀況進行配置。預設已包含所有小程式自帶的元件名稱，所以大部分情況下開發者不需要配置該項目。如需新增則可以在陣列中新增新的元件名稱。
enableDebugLog	Boolean	false	是否開啟列印本插件的內部運行日誌

案例

• 整合案例：Taro - React 項目
• 整合案例：Taro - Vue 2 項目
• 整合案例：Taro - Vue 3 項目

? uni-app 小程式

uni-app 小程式

uni-app, 開發一次，多端覆蓋。

本篇內容包含uni-app 的Vue 3 與Vue 2 兩種安裝示範。

Vue 3 安裝示範

請參考下一個小程式類型：常規Vite 類別小程式（以uni-app 為例）

Vue 2 安裝示範

安裝windicss-webpack-plugin

npm i windicss-webpack-plugin -D

參考Windi CSS 官方文件了解更多細節

Windi CSS Webpack 集成

安裝@dcasia/mini-program-tailwind-webpack-plugin

npm i @dcasia/mini-program-tailwind-webpack-plugin -D

新建Vue 設定檔

在專案根目錄新建vue.config.js設定檔並使用Webpack 插件

 // vue.config.js
const WindiCSSWebpackPlugin = require ( "windicss-webpack-plugin" ) ;
const MiniProgramTailwindWebpackPlugin = require ( "@dcasia/mini-program-tailwind-webpack-plugin" )

module . exports = {  
  configureWebpack : {  
    plugins : [  
      new WindiCSSWebpackPlugin ( ) ,
      new MiniProgramTailwindWebpackPlugin ( {
        // options
      } )
    ]  
  }  
} 

新建Windi CSS 設定文件

在專案根目錄新建windi.config.js設定檔

 //windi.config.js
export default {
  preflight : false ,
  prefixer : false ,
  extract : {
    // 忽略部分文件夹
    exclude : [ 'node_modules' , '.git' , 'dist' ]
  } ,
  corePlugins : {
    // 禁用掉在小程序环境中不可能用到的 plugins
    container : false
  }
}

此處Tailwind CSS 設定檔同樣適用

參考Windi CSS 官方文件了解更多細節

Windi CSS 設定檔相容規則

在入口文件中引入Windi CSS 的產物

 // main.js
import 'windi.css' 

完成

開始享受在小程式專案中由Windi CSS 帶來的高效開發體驗?

可配置參數

名稱	類型	預設	描述
enableRpx	Boolean	true	是否開啟自動轉換至rpx 單位值的功能
designWidth	Number	350	設計稿的像素寬度值，尺寸會影響rpx 轉換過程中的計算比率
utilitiesSettings.spaceBetweenItems	Array<string>	[]	使用了Space Between utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項。如需新增則可以在陣列中新增新的元件名稱。
utilitiesSettings.divideItems	Array<string>	[]	使用了Divide width utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項。如需新增則可以在陣列中新增新的元件名稱。
utilitiesSettings.customComponents	Array<string>	[]	對於使用Uno CSS 作為Atomic CSS 引擎的開發者需要根據專案狀況進行配置。預設已包含所有小程式自帶的元件名稱，所以大部分情況下開發者不需要配置該項目。如需新增則可以在陣列中新增新的元件名稱。

案例

整合案例：uni-app Vue 2 項目

?常規Vite 類小程式（以uni-app 為例）

常規Vite 類小程式（以uni-app 為例）

uni-app, 開發一次，多端覆蓋。

由於在uni-app 中使用Vue 3 進行小程式開發時專案是基於Vite 進行建構的，所以本次安裝示範將uni-app Vue 3 專案作為典型案例來示範如何為大部分Vite 類別小型程式專案進行插件安裝。以下安裝步驟在Vite 專案中具有廣泛的通用性，對於大部分Vite 類小程式專案只需參考相同步驟進行安裝即可。

安裝vite-plugin-windicss 與windicss

npm i vite-plugin-windicss windicss -D

參考Windi CSS 官方文件了解更多細節

Windi CSS Vite 集成

安裝@dcasia/mini-program-tailwind-webpack-plugin

npm i @dcasia/mini-program-tailwind-webpack-plugin -D

更新Vite 設定檔

在vite.config.js設定檔中使用插件

 // vite.config.js
import WindiCSS from 'vite-plugin-windicss' ;
import MiniProgramTailwind from '@dcasia/mini-program-tailwind-webpack-plugin/rollup' ;

export default {
  plugins : [
    WindiCSS ( ) ,
    MiniProgramTailwind ( )
  ]
} 

新建Windi CSS 設定文件

在專案根目錄新建windi.config.js設定檔

 //windi.config.js
export default {
  preflight : false ,
  prefixer : false ,
  extract : {
    // 忽略部分文件夹
    exclude : [ 'node_modules' , '.git' , 'dist' ]
  } ,
  corePlugins : {
    // 禁用掉在小程序环境中不可能用到的 plugins
    container : false
  }
}

此處Tailwind CSS 設定檔同樣適用

參考Windi CSS 官方文件了解更多細節

Windi CSS 設定檔相容規則

在入口文件中引入Windi CSS 的產物

 // main.js
import 'virtual:windi.css' 

完成

開始享受在小程式專案中由Windi CSS 帶來的高效開發體驗?

可配置參數

名稱	類型	預設	描述
enableRpx	Boolean	true	是否開啟自動轉換至rpx 單位值的功能
designWidth	Number	350	設計稿的像素寬度值，尺寸會影響rpx 轉換過程中的計算比率
utilitiesSettings.spaceBetweenItems	Array<string>	[]	使用了Space Between utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項。如需新增則可以在陣列中新增新的元件名稱。
utilitiesSettings.divideItems	Array<string>	[]	使用了Divide width utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項。如需新增則可以在陣列中新增新的元件名稱。
utilitiesSettings.customComponents	Array<string>	[]	對於使用Uno CSS 作為Atomic CSS 引擎的開發者需要根據專案狀況進行配置。預設已包含所有小程式自帶的元件名稱，所以大部分情況下開發者不需要配置該項目。如需新增則可以在陣列中新增新的元件名稱。

案例

整合案例：uni-app Vue 3 項目

? 原生開發或自訂建置的小程式

原生開發或自訂建置工具的小程序

無論你的專案是基於什麼bundler 或workflow 工具進行開發，只要有一個可程式化的檔案監聽與處理服務便可以進行自訂實作。但這裡需要明確的一點是，若想在以原生開發模式的基礎之上去集成本插件的功能，則一定需要我們去啟動一套可編程的文件監聽處理服務作為插件的運行基礎，這個服務通常由配置好的Webpack, Gulp 等第三方工具完成。

使用Tailwind/Windi CSS CLI 的開發者請看

如果你是透過Tailwind/Windi CSS 官方的CLI 進行小程式UI 開發，遺憾的是由於該CLI 不支援插件機製而且不可能支援對於模板檔案的修改，所以我們無法在此基礎之上以自訂的方式集成本插件。

我們將本插件的核心功能解耦並打包進了universal-handler.js檔案中，若您想在自訂的建置工具中集成本插件的核心功能，可以在工作流程邏輯中引入universal-handler ：

 const { handleTemplate , handleStyle } = require ( '@dcasia/mini-program-tailwind-webpack-plugin/universal-handler' )

處理template:

 const rawContent = '<view class="w-10 h-[0.5px] text-[#ffffff]"></view>'
const handledTemplate = handleTemplate ( rawContent )

處理style:

 const rawContent = '.h-\[0\.5px\] {height: 0.5px;}'
const handledStyle = handleStyle ( rawContent , options )

此後你便可以將處理過的字串傳回至工作流程原本的流程中來產生最終的檔案。

進一步了解自訂實作過程中的實務細節

小程式整合Windi CSS 的自訂實現

可配置參數

名稱	類型	預設	描述
enableRpx	Boolean	false	是否開啟自動轉換至rpx 單位值的功能
designWidth	Number	350	設計稿的像素寬度值，尺寸會影響rpx 轉換過程中的計算比率
utilitiesSettings.spaceBetweenItems	Array<string>	[]	使用了Space Between utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項。如需新增則可以在陣列中新增新的元件名稱。
utilitiesSettings.divideItems	Array<string>	[]	使用了Divide width utilities 的容器中的子元件的名稱。預設已包含view, button, text, image 四個常用元件，所以大部分情況下開發者不需要配置該項。如需新增則可以在陣列中新增新的元件名稱。
utilitiesSettings.customComponents	Array<string>	[]	對於使用Uno CSS 作為Atomic CSS 引擎的開發者需要根據專案狀況進行配置。預設已包含所有小程式自帶的元件名稱，所以大部分情況下開發者不需要配置該項目。如需新增則可以在陣列中新增新的元件名稱。

案例

整合案例：基於Gulp 進行自訂實現

示範操作步驟皆以整合Windi CSS 為例（Windi CSS 的體驗更佳且相容於Tailwind CSS）

進一步了解Windi CSS

Windi CSS

---

陷阱

• 在小程式中為了讓元件樣式可以被Tailwind/Windi 的CSS 產物作用到，我們需要在每一個元件的JSON 設定檔中設定其樣式的作用域styleIsolation ，否則即使Tailwind/Windi CSS 運作正常也無法用來開發組件UI。

  Taro 小程式不受此限制影響

  {
    "component" : true ,
    "styleIsolation" : " apply-shared "
  }

  相關issue

  Issue #1

• 由於目前微信開發者工具的熱重載功能無法監聽到樣式檔內由@import導入的wxss 文件內容的變動，所以當啟用熱重載功能開發時，模擬器不會隨著你對Tailwind/Windi CSS的更改而更新UI。目前微信官方已知曉該bug 的存在，在該bug 修復之前，我們建議你在開發時關閉熱重載，用傳統的頁面自動刷新來預覽每一次的UI 更新。 目前，該問題已在微信開發者工具1.06.2205231 RC 中修復。

  相關issue

  Issue #3

• 對於原生小程式中外部樣式類別externalClasses的聲明，外掛程式僅支援將該externalClasses名稱聲明為'class'的做法，不支援其他名稱。

   Component ( {
    externalClasses : [ 'class' ]
  } )

  相關issue

  Issue #44

---

功能對比

文法	不使用本插件	使用本插件
Regular : h-10 text-white	✅	✅
Arbitrary values/Value infer : t-[25px] bg-[#ffffff]		✅
Fraction : translate-x-1/2 w-8.5		✅
Important : !p-1		✅
RGB value infer : text-[rgb(25,25,25)]		✅
Space between : space-y-2 space-y-reverse		✅
Divide width : divide-x-2 divide-y-reverse		✅
Variants : dark:bg-gray-800		✅
Variants groups : hover:(bg-gray-400 font-medium)		✅
Responsive : md:p-2		✅
Universal selector : *		✅
rpx value transformed from rem and px value		✅

---

相容範圍

• Webpack >= 4.0.0
• Taro >= 3.4.0
• MPX >= 2.7.5
• uni-app