Direktif

Direktif adalah at-rule berprefiks @ yang Anda tulis dalam CSS input untuk menyusun, memperluas, dan mengatur urutan output Tailwind. Halaman ini membahas @apply, @utility, @variant, @custom-variant, dan @layer. @theme dibahas di Tema; @plugin di Plugin; dan @source di @source.

@apply

@apply menyematkan deklarasi utilitas yang sudah ada ke dalam selector Anda sendiri. Gunakan untuk menerapkan gaya utilitas pada kelas semantik, termasuk di dalam selector bersarang dan kueri media.

use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

    @theme { --color-brand: #3b82f6; }

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');

Varian berfungsi dalam daftar @apply — @apply bg-blue-500 hover:bg-blue-600; memperluas status :hover, dan prefiks responsif seperti @apply px-4 md:px-6 lg:px-8; menghasilkan aturan @media yang sesuai. Modifier penting juga diterapkan (@apply !flex;). Selector bersarang didukung, sehingga aturan seperti .card { h2 { @apply text-xl font-bold; } } menerapkan utilitas pada h2 yang bersarang.

@apply adalah pernyataan: @apply px-4 { … } dengan isi akan memunculkan error. @apply yang hanya mencantumkan ident dashed (@apply --my-mixin;) adalah mixin CSS dari draf mixin CSS, bukan daftar utilitas, sehingga TailwindPHP tidak dapat menyelesaikannya; mencampur mixin dan utilitas dalam @apply yang sama akan memunculkan error (You cannot use @apply with both mixins and utilities…). Saat ini aturan mixin dihilangkan dari output, bukan diteruskan (#12).

@utility

@utility mendaftarkan utilitas kustom yang menjadi bagian dari mesin Tailwind — utilitas ini diurutkan ke dalam lapisan utilities dan menerima varian seperti utilitas bawaan. Utilitas statis memiliki isi tetap:

@utility content-auto {
    content-visibility: auto;
}

Karena ini utilitas sungguhan, varian dapat digabungkan secara otomatis (hover:content-auto, md:content-auto). Isinya dapat menggunakan @apply dan selector bersarang:

@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}

Utilitas fungsional menggunakan sufiks -* pada namanya dan membaca nilai yang cocok dengan --value():

@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}

--value() menyelesaikan nilai kandidat terhadap setiap sumber secara berurutan: namespace tema (--gutter-*), nilai arbitrer dengan tipe data ([length]), atau tipe nilai polos (integer, number, percentage, ratio). Deklarasi yang nilai --value()-nya tidak terselesaikan akan dihilangkan, sehingga menyusun deklarasi akan membentuk rangkaian fallback:

--modifier() menyelesaikan bagian setelah / dengan cara yang sama: dengan line-height: --modifier(integer); di dalam body, gutter-4/7 juga menghasilkan line-height: 7. Nama utilitas mengikuti aturan TailwindCSS v4.3.3: paling banyak satu /, % hanya di akhir setelah digit, dan titik hanya di antara digit.

@variant

@variant menerapkan varian pada deklarasi di dalam CSS Anda sendiri, tanpa mendefinisikan utilitas:

.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}

.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}

Varian dapat ditumpuk (@variant hover:focus), dipisahkan dengan koma, disarangkan satu di dalam yang lain, dan dapat menyebut @custom-variant buatan Anda sendiri. @variant tingkat atas tanpa body, atau dengan @slot, diperlakukan sebagai @custom-variant demi kompatibilitas ke belakang.

@custom-variant

@custom-variant mendefinisikan varian baru yang dapat Anda tambahkan sebagai awalan pada utilitas apa pun. Bentuk ringkasnya mencantumkan nama varian dan selector atau at-rule di dalam tanda kurung.

Varian daftar selector menggunakan & untuk elemen tersebut:

@custom-variant hocus (&:hover, &:focus);

hocus:bg-blue-500 lalu menghasilkan aturan :hover dan :focus. Bentuk atribut bekerja dengan cara yang sama:

@custom-variant loading (&[data-loading="true"]);

Varian at-rule membungkus utilitas yang cocok di dalam at-rule tersebut:

@custom-variant tablet (@media (min-width: 600px));

Varian kustom dapat ditumpuk dengan varian bawaan — sm:hocus:bg-blue-500 menyarangkan selector hocus di dalam kueri media sm. Untuk kasus yang lebih kompleks, gunakan bentuk blok dengan @slot sebagai penanda tempat deklarasi utilitas disisipkan:

@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}

@layer

@layer mengatur urutan cascade menggunakan cascade layer CSS bawaan. Pernyataan @layer tanpa isi mendeklarasikan urutan layer; layer yang muncul belakangan akan menang, terlepas dari spesifisitas selector. Urutan kanonis Tailwind adalah:

@layer theme, base, components, utilities;

Inilah yang disiapkan @import "tailwindcss" secara internal. Anda dapat mendeklarasikan urutan sendiri, atau membaginya ke beberapa pernyataan (@layer reset, base; lalu @layer components, utilities;), dan menetapkan aturan ke layer bernama dengan sebuah blok:

use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');

Menambahkan gaya dasar melalui @layer base menempatkannya di bawah components dan utilities, sehingga kelas utilitas selalu mengesampingkan nilai default elemen Anda. Hal yang sama berlaku untuk @layer components { … } bagi kelas komponen yang seharusnya berada di bawah utilitas. Layer anonim dan modifier layer() pada @import dibahas di Impor.

Langkah berikutnya

• Tema — @theme token dan fungsi tema.
• Impor — @import, modul virtual, dan modifier layer().
• Plugin — direktif @plugin dan API plugin.
• @source — atur file dan kelas yang dipindai.