README

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

由 dcastil 编写的 tailwind-merge 的 Laravel / PHP 版本。

支持 Tailwind v3.0 到 v3.3。

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

• Devanox Private Limited: github.com/sponsors/devanoxltd

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

目录

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

入门

需要 Laravel 10

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

composer require devanoxltd/tailwind-class-merge-laravel

可选，发布配置文件

php artisan vendor:publish --provider="TailwindClassMerge\Laravel\TailwindClassMergeServiceProvider"

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

TAILWIND_MERGE_PREFIX=tw-

最后，您可以在 Blade 组件的各种位置使用 TailwindClassMerge

// circle.blade.php
<div {{ $attributes->tailwindClass('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>

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

use TailwindClassMerge\Laravel\Facades\TailwindClassMerge;

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

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

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

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

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

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

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

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

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

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

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

用法

有关深度文档和一般 PHP 示例，请参阅 devanoxltd/tailwind-class-merge-php 存储库。

在 Laravel Blade 组件中使用

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

// circle.blade.php
<div {{ $attributes->tailwindClass('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 允许您在一个地方合并类。但是，使用 TailwindClassMerge，您可以通过使用 forAttributes() 在多个元素上合并类

// button.blade.php
<button {{ $attributes->withoutForAttributes()->tailwindClass('p-2 bg-gray-900 text-white') }}>
    <svg {{ $attributes->forAttributes('icon')->tailwindClass('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" component:icon:class="text-blue-500">
  Click Me
</x-button>

这将渲染以下 HTML

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

  Click Me
</button>

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

如果您想重命名 blade 组件前缀，可以在 config/tailwind-class-merge.php 配置文件中这样做

// config/tailwind-class-merge.php
return [
    'attribute_prefix' => 'component:',
];

使用Laravel Blade指令

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

@tailwindClass('w-10 h-10 rounded-full bg-red-500 bg-blue-500') // class="w-10 h-10 rounded-full bg-blue-500"

// or multiple arguments
@tailwindClass('w-10 h-10 rounded-full bg-red-500', 'bg-blue-500') // class="w-10 h-10 rounded-full bg-blue-500"

如果您想重命名Blade指令，可以在config/tailwind-class-merge.php配置文件中这样做

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

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

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

Laravel 其他地方

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

门面

use TailwindClassMerge\Laravel\Facades\TailwindClassMerge;

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

辅助方法

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

更多使用示例

请查看TailwindClassMerge for PHP存储库。

配置

如果您在没有任何额外配置的情况下使用Tailwind CSS，可以直接使用TailwindClassMerge。然后停止阅读这里。

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

默认情况下，TailwindClassMerge的配置方式允许您在使用以下所有内容时仍然使用它

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

如果这些点中的某些不适用于您，则需要自定义配置。

配置前缀

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

TAILWIND_MERGE_PREFIX=tw-

修改合并过程

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

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

// config/tailwind-class-merge.php

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

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

贡献

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

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