Εισαγωγές και εικονικές μονάδες

Το TailwindPHP επιλύει τους κανόνες @import πριν από τη μεταγλώττιση. Οι εισαγωγές μπορούν να αναφέρονται σε ενσωματωμένες εικονικές μονάδες (tailwindcss και άλλες), σε αρχεία στον δίσκο μέσω της επιλογής importPaths ή σε οτιδήποτε επιστρέφει ένας προσαρμοσμένος επιλυτής.

Εικονικές μονάδες

Το @import "tailwindcss" είναι το σημείο εισόδου που χρησιμοποιούν τα περισσότερα έργα. Αναπτύσσεται στις τέσσερις γραμμές παρακάτω — στη δήλωση σειράς επιπέδων και στις τρεις υποεισαγωγές, καθεμία αντιστοιχισμένη στο επίπεδο cascade της:

@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

Κάθε υποεισαγωγή είναι από μόνη της μια εικονική μονάδα, την οποία μπορείτε να εισαγάγετε ξεχωριστά. Οι διαθέσιμες εικονικές μονάδες είναι:

Η ξεχωριστή εισαγωγή των τμημάτων σάς επιτρέπει να παραλείψετε το Preflight ή να αλλάξετε τη σειρά των επιπέδων (δείτε παρακάτω).

Κινούμενα εφέ με tw-animate-css

Το tw-animate-css είναι μια βιβλιοθήκη κινούμενων εφέ TailwindCSS v4 — αντικαθιστά άμεσα το tailwindcss-animate. Περιλαμβάνεται ως ενσωματωμένη εικονική μονάδα, οπότε η εισαγωγή της μαζί με το επίπεδο βοηθητικών εργαλείων επιτρέπει τη μεταγλώττιση των κλάσεων εισόδου/εξόδου της όπως κάθε άλλο βοηθητικό εργαλείο:

@import "tw-animate-css";
@import "tailwindcss/utilities.css";

Τα βοηθητικά εργαλεία κινούμενων εφέ καλύπτουν:

• Είσοδος / έξοδος — animate-in, animate-out
• Εξασθένηση — fade-in, fade-out
• Μεγέθυνση — zoom-in, zoom-out
• Περιστροφή — spin-in, spin-out
• Θόλωση — blur-in, blur-out
• Ολίσθηση — slide-in-from-top / -bottom / -left / -right και τα αντίστοιχα slide-out-to-*, καθώς και -start / -end με υποστήριξη RTL
• Χρονισμός — duration-*, delay-*, repeat-1 / repeat-infinite, direction-normal / -reverse / -alternate και fill-mode-none / -forwards / -backwards / -both
• Κατάσταση αναπαραγωγής — running, paused
• Κινούμενα εφέ στοιχείων — accordion-down / accordion-up, collapsible-down / collapsible-up και caret-blink

Αυτές οι κλάσεις συνδυάζονται με παραλλαγές Tailwind όπως κάθε άλλο βοηθητικό εργαλείο, κάτι που τις καθιστά ιδανικές για μοτίβα διαλόγων και αναπτυσσόμενων μενού shadcn/ui.

Η επιλογή importPaths

Για να επιλύσετε το @import ως προς το σύστημα αρχείων, περάστε το importPaths στη μορφή πίνακα του generate(). Δέχεται μία διαδρομή, έναν κατάλογο ή έναν πίνακα με οποιονδήποτε συνδυασμό τους.

use TailwindPHP\tw;

// Single file
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/styles.css',
]);

// Directory (loads all .css files alphabetically)
$css = tw::generate([
    'content'     => '<div class="flex btn">Hello</div>',
    'importPaths' => '/path/to/css/',
]);

// Multiple paths — files and directories
$css = tw::generate([
    'content'     => '<div class="flex btn card">Hello</div>',
    'importPaths' => [
        '/path/to/base.css',
        '/path/to/components/',
    ],
]);

// Combine with inline css
$css = tw::generate([
    'content'     => '<div class="flex btn custom">Hello</div>',
    'css'         => '.custom { color: red; }',
    'importPaths' => '/path/to/styles.css',
]);

Εμφωλευμένες εισαγωγές

Οι εισαγωγές μέσα σε ένα φορτωμένο αρχείο επιλύονται σε σχέση με αυτό το αρχείο. Αν το /path/to/styles.css περιέχει @import "./components/buttons.css", η διαδρομή επιλύεται ως προς το /path/to/:

/* /path/to/styles.css */
@import "tailwindcss";
@import "./components/buttons.css";
@import "./components/cards.css";

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

Αποδιπλοποίηση

Η εισαγωγή του ίδιου αρχείου ή της ίδιας εικονικής μονάδας περισσότερες από μία φορές δεν έχει αποτέλεσμα μετά την πρώτη — οι επαναλαμβανόμενες γραμμές @import "tailwindcss" ή δύο αρχεία που εισάγουν το ίδιο μερικό αρχείο αποδιπλοποιούνται αυτόματα. Έτσι αποτρέπονται και οι κυκλικές εισαγωγές.

Προσαρμοσμένος επιλυτής

Για εικονικά συστήματα αρχείων, βάσεις δεδομένων ή οποιαδήποτε πηγή εκτός συστήματος αρχείων, περάστε μια συνάρτηση ως importPaths. Λαμβάνει το URI της εισαγωγής και τον βασικό κατάλογο ως προς τον οποίο επιλύεται η εισαγωγή και επιστρέφει CSS ή null:

use TailwindPHP\tw;

$css = tw::generate([
    'content'     => '<div class="flex virtual-class">Hello</div>',
    'importPaths' => function (?string $uri, ?string $fromFile): ?string {
        if ($uri === null) {
            // Entry CSS — returned when no file is supplied
            return '@import "tailwindcss"; @import "custom.css";';
        }
        if ($uri === 'custom.css') {
            return '.virtual-class { color: purple; }';
        }
        return null; // Unknown imports are silently skipped
    },
]);

Όταν το $uri είναι null (στην πρώτη κλήση, με όρισμα null επίσης), επιστρέψτε το αρχείο εισόδου CSS. Για κάθε άλλο URI, επιστρέψτε τα περιεχόμενά του CSS ή το null για να συνεχιστεί η αναζήτηση στο σύστημα αρχείων· αν δεν βρεθεί τίποτα, η εισαγωγή παραλείπεται σιωπηρά.

Προέλεγχος

Το Preflight είναι η βασική επαναφορά του Tailwind, με συγκεκριμένες σχεδιαστικές επιλογές, χτισμένη πάνω στο modern-normalize. Εξομαλύνει τις διαφορές μεταξύ προγραμμάτων περιήγησης, ώστε τα βοηθητικά εργαλεία να συμπεριφέρονται προβλέψιμα. Μεταξύ άλλων, αφαιρεί τα προεπιλεγμένα περιθώρια, καταργεί τα προεπιλεγμένα στυλ επικεφαλίδων και λιστών, κάνει τις εικόνες στοιχεία επιπέδου block, επαναφέρει τα στυλ περιγραμμάτων ώστε μόνο το border-width να σχεδιάζει περίγραμμα και επιτρέπει στα κουμπιά να κληρονομούν τις γραμματοσειρές.

Το Preflight περιλαμβάνεται στο @import "tailwindcss" — αν εισαγάγετε ολόκληρο το πακέτο, είναι ήδη διαθέσιμο:

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '@import "tailwindcss";',
]);

Επέκταση του Preflight

Προσθέστε τα δικά σας βασικά στυλ πάνω από το Preflight με το @layer base:

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<article><h1>Title</h1><p>Content</p></article>',
    'css'     => '
        @import "tailwindcss";
        @layer base {
            h1 { font-size: var(--text-2xl); }
            h2 { font-size: var(--text-xl); }
            a  { color: var(--color-blue-600); text-decoration-line: underline; }
        }
    ',
]);

Απενεργοποίηση του Preflight

Κατά την ενσωμάτωση σε υπάρχον έργο, εισαγάγετε μόνο τα μέρη που χρειάζεστε και παραλείψτε τη γραμμή Preflight:

use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'css'     => '
        @layer theme, base, components, utilities;
        @import "tailwindcss/theme.css" layer(theme);
        @import "tailwindcss/utilities.css" layer(utilities);
    ',
]);

Τροποποιητές εισαγωγής

Όταν εισάγετε ξεχωριστά τα αρχεία του Tailwind, προσθέστε τους τροποποιητές στις εισαγωγές που επηρεάζουν:

/* Assign the import to a cascade layer */
@import "tailwindcss/utilities.css" layer(utilities);

/* prefix affects both theme variables and utilities */
@import "tailwindcss/theme.css" layer(theme) prefix(tw);
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);

/* important affects utilities */
@import "tailwindcss/utilities.css" layer(utilities) important;

/* theme(static) or theme(inline) affects theme variables */
@import "tailwindcss/theme.css" layer(theme) theme(static);

/* theme(reference): utilities use the variables with a fallback, no :root block */
@import "tailwindcss/theme.css" layer(theme) theme(reference);

Εισαγωγές αναφοράς

Το @import "…" reference φορτώνει ένα αρχείο μόνο για τους ορισμούς του: οι τιμές @theme, οι ορισμοί @utility και @custom-variant μέσα σε αυτό μπορούν να χρησιμοποιηθούν, αλλά το αρχείο δεν εκπέμπει δικό του CSS. Είναι σαν να περικλείετε τα περιεχόμενα του αρχείου σε @media reference { … }, κάτι που μπορείτε επίσης να γράψετε απευθείας:

@import "tailwindcss/utilities.css";

@media reference {
    @theme {
        --color-brand: #f00;
    }
}

Το bg-brand μεταγλωττίζεται έπειτα σε background-color: var(--color-brand, #f00); και δεν εκπέμπεται δήλωση --color-brand.

Δύο περιορισμοί στην τρέχουσα έκδοση (#14):

• Τοποθετήστε τις εισαγωγές αναφοράς και τα block @media reference μετά το @import του tailwindcss ή του tailwindcss/utilities.css. Αν τοποθετηθούν πριν από αυτό, όλη η έξοδος είναι κενή.
• Το reference στις ενσωματωμένες εικονικές μονάδες (@import "tailwindcss" reference;) δεν έχει ακόμη αποτέλεσμα: το θέμα, το Preflight και τα βοηθητικά εργαλεία εξακολουθούν να εκπέμπονται.

Συνεχίστε με το Θέμα για τις μεταβλητές θέματος ή με το @source για να ελέγξετε ποια αρχεία σαρώνονται για ονόματα κλάσεων.