README

TailwindMerge for Laravel 允许您合并多个 Tailwind CSS 类，并通过删除与后续定义的类冲突的类来自动解决类之间的冲突。当您想在 Blade 组件中覆盖 Tailwind CSS 类时，这尤其有用。

由 dcastil 开发的 tailwind-merge 的 Laravel / PHP 版本。

支持 Tailwind v3.0 到 v3.4。

如果您发现这个包很有帮助，请考虑赞助维护者

• Sandro Gehri: github.com/sponsors/gehrisandro

如果您没有使用 Laravel，您可以直接使用 TailwindMerge for PHP。

目录

• 入门
• 用法
  • Laravel Blade 组件
  • Laravel Blade 指令
  • Laravel 的其他地方
• 配置
  • 自定义 Tailwind 配置
• 贡献

入门

需要 Laravel 10

首先，通过 Composer 包管理器安装 TailwindMerge for Laravel

composer require chrillep/tailwind-merge-laravel

可选地，发布配置文件

php artisan vendor:publish --provider="TailwindMerge\Laravel\TailwindMergeServiceProvider"

这将在您的项目中创建一个 config/tailwind-merge.php 配置文件，您可以使用环境变量进行修改以满足您的需求。有关更多信息，请参阅配置部分

TAILWIND_MERGE_PREFIX=tw-

最后，您可以在各种地方使用 TailwindMerge，例如您的 Blade 组件

// circle.blade.php
<div {{ $attributes->twMerge('w-10 h-10 rounded-full bg-red-500') }}></div>

// your-view.blade.php
<x-circle class="bg-blue-500" />

// output
<div class="w-10 h-10 rounded-full bg-blue-500"></div>

TailwindMerge 不仅能够解决基本 Tailwind CSS 类之间的冲突，还可以处理更复杂的场景

use TailwindMerge\Laravel\Facades\TailwindMerge;

// conflicting classes
TailwindMerge::merge('block inline'); // inline
TailwindMerge::merge('pl-4 px-6'); // px-6

// non-conflicting classes
TailwindMerge::merge('text-xl text-black'); // text-xl text-black

// with breakpoints
TailwindMerge::merge('h-10 lg:h-12 lg:h-20'); // h-10 lg:h-20

// dark mode
TailwindMerge::merge('text-black dark:text-white dark:text-gray-700'); // text-black dark:text-gray-700

// with hover, focus and other states
TailwindMerge::merge('hover:block hover:inline'); // hover:inline

// with the important modifier
TailwindMerge::merge('!font-medium !font-bold'); // !font-bold

// arbitrary values
TailwindMerge::merge('z-10 z-[999]'); // z-[999] 

// arbitrary variants
TailwindMerge::merge('[&>*]:underline [&>*]:line-through'); // [&>*]:line-through

// non tailwind classes
TailwindMerge::merge('non-tailwind-class block inline'); // non-tailwind-class inline 

可以传递字符串、数组或两者的组合作为类

TailwindMerge::merge('h-10 h-20'); // h-20
TailwindMerge::merge(['h-10', 'h-20']); // h-20
TailwindMerge::merge(['h-10', 'h-20'], 'h-30'); // h-30
TailwindMerge::merge(['h-10', 'h-20'], 'h-30', ['h-40']); // h-40

用法

有关详细文档和一般 PHP 示例，请参阅 gehrisandro/tailwind-merge-php 存储库。

在 Laravel Blade 组件中使用

像往常一样创建您的 Blade 组件，但不要直接指定 class 属性，而是使用 mergeClasses 方法

// circle.blade.php
<div {{ $attributes->twMerge('w-10 h-10 rounded-full bg-red-500') }}></div>

现在您可以使用您的 Blade 组件并传递要合并的额外类

// your-view.blade.php
<x-circle class="bg-blue-500" />

这将渲染以下 HTML

<div class="w-10 h-10 rounded-full bg-blue-500"></div>

注意：由于 Laravel 的限制，目前不支持使用 $attributes->merge(['class' => '...'])

在多个元素上合并类

默认情况下，Laravel 允许您在一个位置合并类。但通过使用 twMergeFor()，您可以使用 TailwindMerge 在多个元素上合并类

// button.blade.php
<button {{ $attributes->withoutTwMergeClasses()->twMerge('p-2 bg-gray-900 text-white') }}>
    <svg {{ $attributes->twMergeFor('icon', 'h-4 text-gray-500') }} viewBox="0 0 448 512"><path d="..."/></svg>
    
    {{ $slot }}
</button>

现在您可以指定按钮和 SVG 图标的额外类

// your-view.blade.php
<x-button class="bg-blue-900" class:icon="text-blue-500">
  Click Me
</x-button>

这将渲染以下 HTML

<button class="p-2 blue text-white">
  <svg class="h-4 text-blue-500" viewBox="0 0 448 512"><path d="..."/></svg>

  Click Me
</button>

注意：在您的主属性包上使用 withoutTwMergeClasses()，否则所有 class:xyz 属性都将渲染到输出中。

使用 Laravel Blade 指令

该包注册了一个Blade指令，可用于合并Blade视图中的类。

@twMerge('w-10 h-10 rounded-full bg-red-500 bg-blue-500') // w-10 h-10 rounded-full bg-blue-500

// or multiple arguments
@twMerge('w-10 h-10 rounded-full bg-red-500', 'bg-blue-500') // w-10 h-10 rounded-full bg-blue-500

如果您想重命名Blade指令，可以在config/tailwind-merge.php配置文件中完成。

// config/tailwind-merge.php
return [
    'blade_directive' => 'customTwMerge',
];

您甚至可以将指令完全禁用，只需将其设置为null。

// config/tailwind-merge.php
return [
    'blade_directive' => null,
];

Laravel 的其他地方

如果您不使用Laravel Blade，您仍然可以通过使用门面（Facade）或直接使用辅助方法来使用TailwindMerge。

门面（Facade）

use TailwindMerge\Laravel\Facades\TailwindMerge;

TailwindMerge::merge('w-10 h-10 rounded-full bg-red-500 bg-blue-500'); // w-10 h-10 rounded-full bg-blue-500

辅助方法

twMerge('w-10 h-10 rounded-full bg-red-500 bg-blue-500'); // w-10 h-10 rounded-full bg-blue-500

更多使用示例

请参阅TailwindMerge for PHP仓库。

配置

如果您没有使用任何额外配置使用Tailwind CSS，可以直接使用TailwindMerge。然后请停止阅读。

如果您使用的是自定义Tailwind配置，可能需要配置TailwindMerge以正确合并类。

默认情况下，TailwindMerge按照以下方式配置，如果您的Tailwind配置符合以下所有条件，您仍然可以使用它：

• 仅使用不与其他Tailwind类名冲突的颜色名称。
• 仅从基于数字的Tailwind类中偏离数字值。
• 仅使用不与默认字体粗细类冲突的字体族类。
• 对于其他所有内容，坚持使用默认Tailwind配置。

如果上述某些点不符合您的情况，您需要自定义配置。

配置前缀

您可以直接在config/tailwind-merge.php配置文件中配置前缀，或者通过设置环境变量来配置。

TAILWIND_MERGE_PREFIX=tw-

修改合并过程

如果TailwindMerge无法正确合并您的更改，您可以修改现有的类组或添加新的类组来修改合并过程。

例如，如果您想添加一个自定义的字体大小“very-large”

// config/tailwind-merge.php

return [
  'classGroups' => [
      'font-size' => [
          ['text' => ['very-large']]
      ],
  ],
];

有关配置选项的更详细说明，请访问原始包文档。

贡献

感谢您考虑为TailwindMerge for Laravel做出贡献！贡献指南可以在CONTRIBUTING.md文件中找到。

TailwindMerge for PHP是一个开源软件，许可协议为MIT许可证。