@astrojs/ tailwind

Astro 集成 为你项目中的每一个 .astro 文件和框架组件带来 Tailwind 的实用 CSS 类，同时支持 Tailwind 配置文件。

为什么是 Tailwind？

Tailwind 让你直接使用实用类而不是编写 CSS。这些实用类大多与某个 CSS 属性设置一一对应：例如，在一个元素上添加text-lg，相当于在 CSS 中设置font-size: 1.125rem。你也许会发现使用这些预定义的实用类更容易编写和维护你的样式！

如果你不喜欢这些预定义的设置，你可以根据你项目的设计要求定制 Tailwind 配置文件。例如，如果你设计中的“大文本”实际上是2rem，你可以将lg字体大小设置改为2rem。

Tailwind 也是为 React、Preact 或 Solid 组件添加样式的不错选择，这些组件不支持组件文件中的 <style> 标签。

注意：一般来说，我们不鼓励在同一个文件中同时使用 Tailwind 和另一种样式方法（例如，样式组件）。

安装

快速安装

astro add 命令行工具为你自动进行安装。在一个新的终端窗口中运行下列其中一条命令（如果你不确定你使用的是哪个包管理器，请运行第一个命令）。然后按照提示，在终端中输入“y”（意思是“是”），每一条都是如此。

# Using NPM
npx astro add tailwind
# Using Yarn
yarn astro add tailwind
# Using PNPM
pnpm astro add tailwind

如果你遇到任何问题，请随时在 GitHub 上向我们报告并尝试下面的手动安装步骤。

手动安装

首先，使用你的包管理器安装 @astrojs/tailwind 和 tailwindcss 包。如果你使用的是 npm 或者不确定哪个包管理器，在终端运行这个：

npm install @astrojs/tailwind tailwindcss

然后，使用 integrations 属性将这个集成应用到你的 astro.config.* 文件：

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // ...
  integrations: [tailwind()],
  //             ^^^^^^^^^^
});

然后，在你的项目根目录下创建一个 tailwind.config.cjs 文件。你可以使用以下命令来生成一个基本的配置文件：

npx tailwindcss init

最后，可将如下基本配置添加到你的 tailwind.config.cjs 文件中：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

使用

当你安装集成后，Tailwind 的实用类应该马上就可以使用了。前往 Tailwind 文档学习如何使用 Tailwind，如果你看到一个你想尝试的实用类，就把它添加到你项目的任何 HTML 元素中去吧！

Autoprefixer 也是在开发模式和生产模式下工作时自动设置的，所以 Tailwind 类将在旧的浏览器中工作。

配置

配置 Tailwind

如果你使用了快速安装，并且每个选项都选是，你会在你项目的根目录下看到一个 tailwind.config.mjs 文件。使用这个文件来修改你的 Tailwind 配置。你可以在 Tailwind 文档中学习如何使用这个文件来定制 Tailwind。

如果没有该文件，你可以在根目录下添加你自己的 tailwind.config.(js|cjs|mjs) 文件，集成将使用其配置。如果你已经在另一个项目中配置了 Tailwind，并想把这些设置带到这个项目中来，这也不错。

配置集成

Astro Tailwind 集成处理 Astro 和 Tailwind 之间的通信，它有自己的设置。在 astro.config.mjs 文件（不是 Tailwind 配置文件）中改变这些，这里是你项目的集成设置所在。

configFile

以前在 @astrojs/tailwind v3 中被称为 config.path。请参阅 v4 更改日志以更新你的配置。

如果你想使用不同的 Tailwind 配置文件，而不是默认的 tailwind.config.(js|cjs|mjs)，请使用本集成的 configFile 选项指定该文件的位置。如果 configFile 是相对路径，则会相对于当前工作目录解析。

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [
    tailwind({
      // 示例：为 Tailwind 配置文件提供一个自定义路径
      configFile: './custom-config.cjs',
    }),
  ],
});

applyBaseStyles

以前在 @astrojs/tailwind v3 中被称为 config.applyBaseStyles。请参阅 v4 更改日志以更新你的配置。

默认情况下，该集成在你项目的每个页面上都导入一个基本的 base.css 文件。这个基本的 CSS 文件包括三个主要的 @tailwind 指令：

/* 集成的默认注入的 base.css 文件 */
@tailwind base;
@tailwind components;
@tailwind utilities;

要禁用这个默认行为，请将 applyBaseStyles 设置为 false。如果你需要定义你自己的 base.css 文件（例如包括一个@layer 指令），这可能很有用。如果你不希望 base.css 被导入你的项目的每一个页面，这也很有用。

import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [
    tailwind({
      // 示例：在每个页面上禁用注入基本的`base.css`导入。
      // 如果你需要定义或导入你自己的 "base.css"，这很有用。
      applyBaseStyles: false,
    }),
  ],
});

你现在可以导入你自己的 base.css 作为本地样式表。

例子

Astro Tailwind Starter 为你提供一个基础的、使用 Tailwind 进行样式设计的可运行项目
Astro 的主页使用 Tailwind。查看其 Tailwind 配置文件或示例组件
Astro Ink、Sarissa Blog 和 Creek 主题使用 Tailwind 进行样式设计
浏览 GitHub 上的 Astro Tailwind 项目以获得更多的例子！

故障排除

使用 `@apply` 指令时提示类不存在

当在 Astro、Vue、Svelte 或其他组件集成的 <style> 标签中使用 @apply 指令时，它可能会产生关于你的自定义 Tailwind 类不存在的错误，并导致你的构建失败。

error   The `text-special` class does not exist. If `text-special` is a custom class, make sure it is defined within a `@layer` directive.

通过在你的 Tailwind 配置中添加一个插件来定义你的自定义样式来修复它，而不是在全局样式表中使用@layer指令，添加如下内容：

export default {
  // ...
  plugins: [
    function ({ addComponents, theme }) {
      addComponents({
        '.btn': {
          padding: theme('spacing.4'),
          margin: 'auto',
        },
      });
    },
  ],
};

基于类的修改器不能与 `@apply` 指令一起工作

某些带有修饰符的 Tailwind 类依赖于跨多个元素的组合类。例如，group-hover:text-gray 编译为 .group:hover .text-gray。当这与 Astro <style> 标签中的 @apply 指令一起使用时，编译后的样式会从构建输出中删除，因为它们与 .astro 文件中的任何标记不匹配。同样的问题也可能发生在支持范围样式的框架组件中，如 Vue 和 Svelte。

为了解决这个问题，你可以使用内联类来代替：

<p class="text-black group-hover:text-gray">Astro</p>

其他

如果你的安装似乎不成功，尝试重新启动开发服务器。
如果你编辑并保存了一个文件，但没有看到你的网站有相应的更新，试着刷新页面。
如果刷新页面并没有更新你的预览，或者新的安装似乎没有效果，那么就重新启动开发服务器。

如需帮助，请查看 Discord 上的 #support 频道。我们友好的支持小组成员将在这里提供帮助！

你也可以查看我们的 Astro 集成文档，了解更多关于集成的信息。