|
| 1 | +--- |
| 2 | +id: merge |
| 3 | +title: '@weapp-tailwindcss/merge（Tailwind v4）' |
| 4 | +description: '适配 Tailwind v4 的 tailwind-merge 运行时封装，提供小程序 escape/unescape 与多端工厂能力。' |
| 5 | +--- |
| 6 | + |
| 7 | +`@weapp-tailwindcss/merge` 是 `tailwind-merge@3` 的小程序友好封装，适配 `tailwindcss@4`。它在合并前后自动处理 escape/unescape，使运行时输出与编译期一致。 |
| 8 | + |
| 9 | +## 安装 |
| 10 | + |
| 11 | +```bash npm2yarn |
| 12 | +pnpm add @weapp-tailwindcss/merge |
| 13 | +``` |
| 14 | + |
| 15 | +## 核心 API |
| 16 | + |
| 17 | +- `twMerge(...classValues)`：合并 Tailwind 类名并去冲突。 |
| 18 | +- `twJoin(...classValues)`：拼接类名（不做冲突判断）。 |
| 19 | +- `extendTailwindMerge(config)` / `createTailwindMerge(config)`：扩展合并规则。 |
| 20 | +- `create(options?)`：创建隔离实例，控制 escape/unescape。 |
| 21 | +- `weappTwIgnore`：标记「不要转义」的模板字符串。 |
| 22 | + |
| 23 | +### 基础示例 |
| 24 | + |
| 25 | +```ts |
| 26 | +import { twMerge } from '@weapp-tailwindcss/merge' |
| 27 | + |
| 28 | +const className = twMerge( |
| 29 | + 'px-2 py-1 bg-red hover:bg-dark-red', |
| 30 | + 'p-3 bg-[#B91C1C]' |
| 31 | +) |
| 32 | + |
| 33 | +// => 已转义的类名，可直接写入小程序 class |
| 34 | +``` |
| 35 | + |
| 36 | +### 扩展合并规则 |
| 37 | + |
| 38 | +```ts |
| 39 | +import { extendTailwindMerge } from '@weapp-tailwindcss/merge' |
| 40 | + |
| 41 | +const mergeCard = extendTailwindMerge({ |
| 42 | + classGroups: { |
| 43 | + card: ['card-default', 'card-primary'], |
| 44 | + }, |
| 45 | +}) |
| 46 | + |
| 47 | +mergeCard('card-default card-primary') // => 'card-primary' |
| 48 | +``` |
| 49 | + |
| 50 | +## 小程序用法 |
| 51 | + |
| 52 | +小程序端建议直接使用默认导出，运行时会自动输出转义后的类名： |
| 53 | + |
| 54 | +```ts |
| 55 | +import { twMerge } from '@weapp-tailwindcss/merge' |
| 56 | + |
| 57 | +const buttonClass = twMerge( |
| 58 | + 'inline-flex items-center rounded-md px-3 py-2 text-sm', |
| 59 | + isPrimary && 'bg-[#2563EB] text-white' |
| 60 | +) |
| 61 | +``` |
| 62 | + |
| 63 | +## Web 用法（关闭转义） |
| 64 | + |
| 65 | +在 Web/SSR 环境中，使用 `create` 关闭 escape/unescape： |
| 66 | + |
| 67 | +```ts |
| 68 | +import { create } from '@weapp-tailwindcss/merge' |
| 69 | + |
| 70 | +const { twMerge: twMergeWeb } = create({ |
| 71 | + escape: false, |
| 72 | + unescape: false, |
| 73 | +}) |
| 74 | + |
| 75 | +const className = twMergeWeb('text-[#2563EB]', 'text-[#1D4ED8]') |
| 76 | +// => 'text-[#1D4ED8]' |
| 77 | +``` |
| 78 | + |
| 79 | +## Demo：按钮类名合并 |
| 80 | + |
| 81 | +```ts |
| 82 | +import { twMerge } from '@weapp-tailwindcss/merge' |
| 83 | + |
| 84 | +const base = 'inline-flex items-center rounded-md px-4 py-2 text-sm font-medium' |
| 85 | +const state = 'bg-[#2563EB] text-white hover:bg-[#1D4ED8]' |
| 86 | +const override = 'px-6' |
| 87 | + |
| 88 | +const className = twMerge(base, state, override) |
| 89 | +``` |
| 90 | + |
| 91 | +## 常见注意事项 |
| 92 | + |
| 93 | +- **函数名保留**：如果你把 `twMerge` 别名成 `cn`，需要在 `ignoreCallExpressionIdentifiers` 中补充该名称。 |
| 94 | +- **跳过编译期转义**：当类名需要原样传递给第三方时，用 `weappTwIgnore` 标记模板字符串。 |
| 95 | + |
| 96 | +更多细节与调试指南见 [集成与排障指南](/docs/community/merge/integration)。 |
0 commit comments