跳转到内容

@astrojs/ tailwind

v5.1.0 GitHub npm Changelog

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

为什么是 Tailwind？

段落标题 为什么是 Tailwind？

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

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

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

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

安装

段落标题 安装

Astro 包含了一个 astro add 命令，用于自动设置官方集成。如果你愿意，可以改为手动安装集成。

在新的终端窗口中运行以下其中一个命令。

Terminal window
npx astro add tailwind

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

手动安装

段落标题 手动安装

首先，使用你的包管理器安装 @astrojs/tailwind 和 tailwindcss。

Terminal window
npm install @astrojs/tailwind tailwindcss

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

astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
export default defineConfig({
  // ...
  integrations: [tailwind()],
});

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

Terminal window
npx tailwindcss init

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

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

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

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

配置集成

段落标题 配置集成

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

configFile

段落标题 configFile

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

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

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


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

applyBaseStyles

段落标题 applyBaseStyles

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

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

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

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

astro.config.mjs
import { defineConfig } from 'astro/config';


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

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

例子

段落标题 例子

故障排除

段落标题 故障排除

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

段落标题 使用 @apply 指令时提示类不存在

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

Terminal window
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指令，添加如下内容：

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

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

段落标题 基于类的修改器不能与 @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 集成文档，了解更多关于集成的信息。

更多集成

UI 框架

SSR 适配器

其他集成