跳到主要内容

✅ 重要配置

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/index.ts:13

本页收录 16 个配置项，来源于 UserDefinedOptions。

配置一览​

配置项类型默认值说明
disabledboolean | DisabledOptions—是否禁用此插件。
customAttributesICustomAttributes—自定义 wxml 标签属性的转换规则。
customReplaceDictionaryRecord<string, string>MappingChars2String自定义 class 名称的替换字典。
ignoreTaggedTemplateExpressionIdentifiers(string | RegExp)[]['weappTwIgnore']忽略指定标签模板表达式中的标识符。
ignoreCallExpressionIdentifiers(string | RegExp)[]—忽略指定调用表达式中的标识符。
cssPreflightCssPreflightOptions—控制在视图节点上注入的 CSS 预设。
cssPreflightRange"all"—控制 cssPreflight 注入的 DOM 选择器范围。
cssCalcboolean | (string | RegExp)[] | CssCalcOptions—预计算 CSS 变量或 calc 表达式的结果。
injectAdditionalCssVarScopebooleanfalse是否额外注入 tailwindcss css var scope。
rewriteCssImportsbooleantrue是否在 webpack/vite 阶段自动把 CSS 中的 @import 'tailwindcss' 映射为 weapp-tailwindcss。
cssSelectorReplacement{ root?: string | string[] | false; universal?: string | string[] | false; }详见下方控制 CSS 选择器的替换规则。
rem2rpxboolean | Rem2rpxOptions—rem 到 rpx 的转换配置。
px2rpxboolean | Px2rpxOptions—px 到 rpx 的转换配置。
cssPresetEnvPresetEnvOptions—postcss-preset-env 的配置项。
tailwindcssTailwindUserOptions—为不同版本的 Tailwind 配置行为。
cssEntriesstring[]—指定 tailwindcss@4 的入口 CSS。

详细说明​

disabled​

可选 | 类型: boolean | DisabledOptions

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:36

是否禁用此插件。

备注​

在多平台构建场景下常用：小程序构建保持默认，非小程序环境（H5、App）传入 true 即可跳过转换。

示例​

// uni-app vue3 vite
import process from 'node:process'

const isH5 = process.env.UNI_PLATFORM === 'h5'
const isApp = process.env.UNI_PLATFORM === 'app'
const disabled = isH5 || isApp

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  disabled,
})

customAttributes​

可选 | 类型: ICustomAttributes

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:57

自定义 wxml 标签属性的转换规则。

备注​

默认会转换所有标签上的 class 与 hover-class。此配置允许通过 Map 或对象为特定标签指定需要转换的属性字符串或正则表达式数组。

  • 使用 '*' 作为键可为所有标签追加通用规则。
  • 支持传入 Map<string | RegExp, (string | RegExp)[]> 以满足复杂匹配需求。
  • 常见场景包括通过组件 prop 传递类名，或对三方组件的自定义属性做匹配，更多讨论见 issue#129 与 issue#134。 如果自定义规则已经覆盖默认的 class/hover-class，可开启 disabledDefaultTemplateHandler 以关闭内置模板处理器。

示例​

const customAttributes = {
  '*': [/[A-Za-z]?[A-Za-z-]*[Cc]lass/],
  'van-image': ['custom-class'],
  'ice-button': ['testClass'],
}

customReplaceDictionary​

可选 | 类型: Record<string, string> | 默认值: MappingChars2String

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:66

自定义 class 名称的替换字典。

备注​

默认策略会将小程序不允许的字符映射为等长度的替代字符串，因此无法通过结果反推出原始类名。如需完全自定义，可传入 Record<string, string>，只需确保生成的类名不会与已有样式冲突。示例参考 dic.ts。

默认值​

MappingChars2String

ignoreTaggedTemplateExpressionIdentifiers​

可选 | 类型: (string | RegExp)[] | 默认值: ['weappTwIgnore'] | 版本: ^4.0.0

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:77

忽略指定标签模板表达式中的标识符。

备注​

当模板字符串被这些标识符包裹时，将跳过转义处理。

默认值​

['weappTwIgnore']

ignoreCallExpressionIdentifiers​

可选 | 类型: (string | RegExp)[] | 版本: ^4.0.0

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:86

忽略指定调用表达式中的标识符。

备注​

使用这些方法包裹的模板字符串或字符串字面量会跳过转义，常与 @weapp-tailwindcss/merge 配合（如 ['twMerge', 'twJoin', 'cva']）。

cssPreflight​

可选 | 类型: CssPreflightOptions

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:115

控制在视图节点上注入的 CSS 预设。

参阅​

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

备注​

默认会向所有 view/text 元素注入 Tailwind 风格的基础样式，可通过此配置禁用、调整或补充规则，受 cssPreflightRange 影响。

示例​

cssPreflight: {
  'box-sizing': 'border-box',
  'border-width': '0',
  'border-style': 'solid',
  'border-color': 'currentColor',
}

cssPreflight: false

cssPreflight: {
  'box-sizing': false,
  background: 'black',
}

cssPreflightRange​

可选 | 类型: "all"

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:124

控制 cssPreflight 注入的 DOM 选择器范围。

参阅​

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

备注​

仅 view、text 及其伪元素会受影响。设置为 'all' 可以覆盖所有元素，此时需自行处理与宿主默认样式的冲突。

cssCalc​

可选 | 类型: boolean | (string | RegExp)[] | CssCalcOptions | 版本: ^4.3.0

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:157

预计算 CSS 变量或 calc 表达式的结果。

备注​

解决部分机型对 calc 计算不一致的问题，可传入布尔值、选项对象或自定义匹配列表（支持正则）。在启用计算后，可通过 includeCustomProperties 指定需要保留的变量。

示例​

// 原始输出
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: calc(var(--spacing) * 2);
}
// 启用 cssCalc 后
.h-2 {
  height: 16rpx;
  height: calc(var(--spacing) * 2);
}
cssCalc: ['--spacing']
cssCalc: { includeCustomProperties: ['--spacing'] }

injectAdditionalCssVarScope​

可选 | 类型: boolean | 默认值: false | 版本: ^2.6.0

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:168

是否额外注入 tailwindcss css var scope。

备注​

当构建链路（例如 @tarojs/plugin-html）移除了包含 * 的选择器时，可启用该选项重新写入变量作用域，以避免渐变等功能失效。

默认值​

false

rewriteCssImports​

可选 | 类型: boolean | 默认值: true

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:177

是否在 webpack/vite 阶段自动把 CSS 中的 @import 'tailwindcss' 映射为 weapp-tailwindcss。

备注​

开启后打包链路只会在处理样式时拦截 tailwindcss 的导入路径（JS/TS import 'tailwindcss' 不会被修改），让源码可以继续写 @import 'tailwindcss';，同时输出 weapp-tailwindcss 的样式。传入 false 可完全关闭该行为。

默认值​

true

cssSelectorReplacement​

可选 | 类型: { root?: string | string[] | false; universal?: string | string[] | false; } | 默认值: 详见下方

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:183

控制 CSS 选择器的替换规则。

默认值​

ts 'page' | | universal? | string | false | Default ts 'view' |

rem2rpx​

可选 | 类型: boolean | Rem2rpxOptions | 版本: ^3.0.0

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:219

rem 到 rpx 的转换配置。

备注​

传入 true 使用默认配置，或提供 postcss-rem-to-responsive-pixel 支持的完整选项。

{
  rootValue: 32,
  propList: ['*'],
  transformUnit: 'rpx',
}

px2rpx​

可选 | 类型: boolean | Px2rpxOptions | 版本: ^4.3.0

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:228

px 到 rpx 的转换配置。

备注​

传入 true 启用默认映射（1px = 1rpx），或通过对象自定义更多行为。

cssPresetEnv​

可选 | 类型: PresetEnvOptions | 版本: ^4.0.0

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:238

postcss-preset-env 的配置项。

参阅​

  • ://preset-env.cssdb.org/
  • ://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env#readme

tailwindcss​

可选 | 类型: TailwindUserOptions | 版本: ^4.0.0

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:246

为不同版本的 Tailwind 配置行为。

cssEntries​

可选 | 类型: string[] | 版本: ^4.2.6

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/important.ts:256

指定 tailwindcss@4 的入口 CSS。

备注​

未配置时无法加载自定义插件，等价于设置 tailwindcss.v4.cssEntries。

aizex
Aizex 合租面板
更好用的「GPT-5 x Claude」使用方式
亲测推荐