跳转到内容

@astrojs/ tailwind

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

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

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

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

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

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

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

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

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

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.config.mjs 文件。使用这个文件来修改你的 Tailwind 配置。你可以在 Tailwind 文档中学习如何使用这个文件来定制 Tailwind。

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

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

以前在 @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',
}),
],
});

以前在 @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 被导入你的项目的每一个页面,这也很有用。

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.mjs
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 集成文档,了解更多关于集成的信息。

这个项目由 Astro 的核心团队维护,欢迎你提交 issue 或 PR!

有关该集成的变化历史,请参阅 CHANGELOG.md

其他

UI 框架

SSR 适配器

其他