README

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

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

支持 Tailwind v3.0 至 v3.3。

如果您觉得这个包很有用，请考虑赞助维护者

• Sandro Gehri: github.com/sponsors/gehrisandro

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

目录

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

入门

需要 Laravel 10

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

composer require gehrisandro/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 允许您在一个地方合并类。但使用 TailwindMerge，您可以使用 twMergeFor() 在多个元素上合并类

// 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无法正确合并您的更改，您可以通过修改现有类组或添加新的类组来修改合并过程。

例如，如果您想添加自定义字体大小“非常大”

// config/tailwind-merge.php

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

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

贡献

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

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