# 导入与虚拟模块
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](https://github.com/Wombosvideo/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' => 'Hello
',
'importPaths' => '/path/to/styles.css',
]);
// Directory (loads all .css files alphabetically)
$css = tw::generate([
'content' => 'Hello
',
'importPaths' => '/path/to/css/',
]);
// Multiple paths — files and directories
$css = tw::generate([
'content' => 'Hello
',
'importPaths' => [
'/path/to/base.css',
'/path/to/components/',
],
]);
// Combine with inline css
$css = tw::generate([
'content' => 'Hello
',
'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' => 'Hello
',
'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](https://github.com/sindresorhus/modern-normalize) 构建的、具有明确设计取向的基础重置。它会消除跨浏览器差异，使工具类表现一致。例如，它会移除默认外边距、重置标题和列表样式、将图像设为块级元素、重置边框样式（只有 `border-width` 会绘制边框），并让按钮继承字体。
Preflight 已包含在 `@import "tailwindcss"` 中——如果你导入完整包，就已经包含它：
```php
use TailwindPHP\tw;
$css = tw::generate([
'content' => 'Hello
',
'css' => '@import "tailwindcss";',
]);
```
### 扩展 Preflight
使用 `@layer base` 在 Preflight 的基础上添加自己的基础样式：
```php
use TailwindPHP\tw;
$css = tw::generate([
'content' => 'Title
Content
',
'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' => 'Hello
',
'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](https://github.com/inline0/tailwindphp/issues/14)）：
- 将引用导入和 `@media reference` 块放在 `tailwindcss` 或 `tailwindcss/utilities.css` 的 `@import` 之后。若放在前面，整个输出将为空。
- 内置虚拟模块（`@import "tailwindcss" reference;`）上的 `reference` 目前不起作用：主题、Preflight 和工具类仍会生成。
接下来可阅读 [主题](https://tailwindphp.inline0.dev/zh/docs/usage/theme) 了解主题变量，或阅读 [@source](https://tailwindphp.inline0.dev/zh/docs/usage/source) 了解如何控制要扫描哪些文件以查找类名。