# 插件

TailwindPHP 提供官方 TailwindCSS 插件的 PHP 移植版，并提供原生 PHP 插件 API。插件可注册工具、组件和变体；在输入 CSS 中使用 `@plugin` 指令加载插件。内置插件是其 JavaScript 对应插件的 1:1 移植版——选择器和输出均相同——使用 PHP 实现，而非通过 Node 执行。目前有一个例外：排版插件的元素修饰符（`prose-headings:`、`prose-a:`、…）依赖尚未应用的插件变体（[#10](https://github.com/inline0/tailwindphp/issues/10)）。

## 使用 `@plugin`

使用 `@plugin` 按名称引用插件。内置插件使用其 npm 包名。将该指令与 `@import "tailwindcss/utilities.css";` 配合使用，这样插件类就会输出到工具层：

```php
use TailwindPHP\tw;

$css = tw::generate([
    'content' => '<article class="prose prose-lg"><h1>Hello</h1><p>Content here</p></article>',
    'css' => '
        @plugin "@tailwindcss/typography";
        @import "tailwindcss/utilities.css";
    ',
]);
```

可以同时加载多个插件，顺序不影响结果：

```css
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@import "tailwindcss/utilities.css";
```

`@plugin` 不能嵌套在其他 at 规则（例如 `@media`）中，未注册的插件名称则会引发错误。

## 插件选项

在名称后使用 CSS 块语法向插件传递选项。键会映射到插件的选项数组：

```css
@plugin "@tailwindcss/forms" {
    strategy: "class";
}

@plugin "@tailwindcss/typography" {
    className: "markdown";
}
```

`@tailwindcss/forms` 插件接受 `strategy`（`base` 或 `class`）；`@tailwindcss/typography` 接受 `className`，用于重命名生成的 `prose` 类。完整选项列表请参阅各插件页面。

## 内置插件

| 插件 | 说明 |
|--------|-------------|
| `@tailwindcss/typography` | `prose` 类——为富文本设置排版默认样式。请参阅[排版](https://tailwindphp.inline0.dev/zh/docs/plugins/typography)。 |
| `@tailwindcss/forms` | 可重置、可设置样式的表单控件。请参阅[表单](https://tailwindphp.inline0.dev/zh/docs/plugins/forms)。 |

## 自定义插件

实现 `PluginInterface`，并使用 `PluginAPI` 上的方法（`addUtilities`、`matchUtilities`、`addComponents`、`addVariant`、`theme` 等）即可编写自己的插件。使用 `registerPlugin(new MyPlugin())` 注册插件后，`getName()` 返回的名称就可以在 `@plugin "my-plugin"` 指令中解析：

```php
use function TailwindPHP\registerPlugin;

registerPlugin(new MyCustomPlugin());
```

有关接口、完整示例以及完整的 `PluginAPI` 方法参考，请参阅[自定义插件](https://tailwindphp.inline0.dev/zh/docs/plugins/custom)。