导入与虚拟模块

以 Markdown 格式查看在 GitHub 上编辑文档位置 3843abd

TailwindPHP 会在编译前解析 @import 规则。导入可以指向内置虚拟模块（tailwindcss 等）、通过 importPaths 选项指向磁盘上的文件，也可以指向自定义解析器返回的任何内容。

虚拟模块

@import "tailwindcss" 是大多数项目使用的入口。它会展开为下面四行：层顺序声明，以及分别分配到各层的三个子导入：

CSS

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

每个子导入本身也是一个虚拟模块，可以单独导入。可用的虚拟模块如下：

模块	内容
`tailwindcss`	完整包：theme + Preflight + 工具类。
`tailwindcss/theme.css`	仅主题变量（颜色、基础间距、断点等）。
`tailwindcss/preflight.css`	Preflight 基础重置。
`tailwindcss/utilities.css`	工具类层。
`tw-animate-css`	`tw-animate-css` 动画工具类。

分别导入各个部分，可以跳过 Preflight 或重新排列层顺序（见下文）。

使用 tw-animate-css 实现动画

tw-animate-css 是一个 TailwindCSS v4 动画库，可直接替代 tailwindcss-animate。它作为内置虚拟模块提供，因此将它与工具类层一同导入后，其中的进入/退出动画类就会像其他工具类一样编译：

CSS

@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-*，还有支持 RTL 的 -start / -end
时序 — 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，请在 generate() 的数组形式中传入 importPaths。它接受单个路径、目录或由两者组成的数组。

PHP

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/ 解析路径：

CSS

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

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

去重

同一个文件或虚拟模块导入多次时，首次导入后后续导入均为空操作——重复的 @import "tailwindcss" 行，或两个文件同时导入同一个局部文件，都会自动去重。此机制也能防止循环导入。

自定义解析器

对于虚拟文件系统、数据库或任何非文件系统来源，请将可调用对象作为 importPaths 传入。它会接收导入 URI 和用于解析该导入的基目录，并返回 CSS 或 null：

PHP

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 构建的、具有明确设计取向的基础重置。它会消除跨浏览器差异，使工具类表现一致。例如，它会移除默认外边距、重置标题和列表样式、将图像设为块级元素、重置边框样式（只有 border-width 会绘制边框），并让按钮继承字体。

Preflight 已包含在 @import "tailwindcss" 中——如果你导入完整包，就已经包含它：

PHP

use TailwindPHP\tw;

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

扩展 Preflight

使用 @layer base 在 Preflight 的基础上添加自己的基础样式：

PHP

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 那一行：

PHP

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 的文件时，应将修饰符添加到它们所影响的导入项上：

CSS

/* 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 { … } 中，也可以直接这样写：

CSS

@import "tailwindcss/utilities.css";

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

bg-brand 随后会编译为 background-color: var(--color-brand, #f00);，且不会生成 --color-brand 声明。

当前版本有两项限制（#14）：

将引用导入和 @media reference 块放在 tailwindcss 或 tailwindcss/utilities.css 的 @import 之后。若放在前面，整个输出将为空。
内置虚拟模块（@import "tailwindcss" reference;）上的 reference 目前不起作用：主题、Preflight 和工具类仍会生成。

接下来可阅读主题了解主题变量，或阅读 @source 了解如何控制要扫描哪些文件以查找类名。