检测源文件中的类

概述(Overview)

¥Overview

Tailwind 的工作原理是扫描项目中的工具类，然后根据你实际使用的类生成所有必要的 CSS。

¥Tailwind works by scanning your project for utility classes, then generating all of the necessary CSS based on the classes you've actually used.

这确保你的 CSS 尽可能小，也是使 任意值 等功能成为可能的原因。

¥This makes sure your CSS is as small as possible, and is also what makes features like arbitrary values possible.

如何检测类别(How classes are detected)

¥How classes are detected

Tailwind 将你的所有源文件视为纯文本，并且不会尝试以任何方式将你的文件解析为代码。

¥Tailwind treats all of your source files as plain text, and doesn't attempt to actually parse your files as code in any way.

相反，它只会根据 Tailwind 在类名中期望的字符，在文件中查找可能为类的任何标记：

¥Instead it just looks for any tokens in your file that could be classes based on which characters Tailwind is expecting in class names:

export function Button({ color, children }) {
  const colors = {
    black: "bg-black text-white",
    blue: "bg-blue-500 text-white",
    white: "bg-white text-black",
  };
  return (
    <button className={`${colors[color]} rounded-full px-2 py-1.5 font-sans text-sm/6 font-medium shadow`}>
      {children}
    </button>
  );
}

然后，它会尝试为所有这些标记生成 CSS，丢弃任何未映射到框架所知的工具类的标记。

¥Then it tries to generate the CSS for all of these tokens, throwing away any tokens that don't map to a utility class the framework knows about.

动态类名(Dynamic class names)

¥Dynamic class names

由于 Tailwind 将你的源文件扫描为纯文本，因此它无法理解你使用的编程语言中的字符串连接或插值。

¥Since Tailwind scans your source files as plain text, it has no way of understanding string concatenation or interpolation in the programming language you're using.

<div class="text-{{ error ? 'red' : 'green' }}-600"></div>

在上面的示例中，字符串 text-red-600 和 text-green-600 不存在，因此 Tailwind 不会生成这些类。

¥In the example above, the strings text-red-600 and text-green-600 do not exist, so Tailwind will not generate those classes.

相反，请确保你使用的任何类名都完整存在：

¥Instead, make sure any class names you’re using exist in full:

<div class="{{ error ? 'text-red-600' : 'text-green-600' }}"></div>

如果你正在使用像 React 或 Vue 这样的组件库，这意味着你不应该使用 props 来动态构造类：

¥If you're using a component library like React or Vue, this means you shouldn't use props to dynamically construct classes:

function Button({ color, children }) {
  return <button className={`bg-${color}-600 hover:bg-${color}-500 ...`}>{children}</button>;
}

相反，将 props 映射到在构建时可静态检测的完整类名：

¥Instead, map props to complete class names that are statically detectable at build-time:

function Button({ color, children }) {
  const colorVariants = {
    blue: "bg-blue-600 hover:bg-blue-500",
    red: "bg-red-600 hover:bg-red-500",
  };
  return <button className={`${colorVariants[color]} ...`}>{children}</button>;
}

这有一个额外的好处，可以让你将不同的属性值映射到不同的颜色阴影，例如：

¥This has the added benefit of letting you map different prop values to different color shades for example:

function Button({ color, children }) {
  const colorVariants = {
    blue: "bg-blue-600 hover:bg-blue-500 text-white",
    red: "bg-red-500 hover:bg-red-400 text-white",
    yellow: "bg-yellow-300 hover:bg-yellow-400 text-black",
  };
  return <button className={`${colorVariants[color]} ...`}>{children}</button>;
}

只要你始终在代码中使用完整的类名，Tailwind 每次都会完美地生成所有 CSS。

¥As long as you always use complete class names in your code, Tailwind will generate all of your CSS perfectly every time.

扫描哪些文件(Which files are scanned)

¥Which files are scanned

Tailwind 将扫描项目中的每个文件以查找类名，但以下情况除外：

¥Tailwind will scan every file in your project for class names, except in the following cases:

• .gitignore 文件中的文件

  ¥Files that are in your .gitignore file

• 二进制文件，如图片、视频或 zip 文件

  ¥Binary files like images, videos, or zip files

• CSS 文件

  ¥CSS files

• 通用包管理器锁定文件

  ¥Common package manager lock files

如果你需要扫描 Tailwind 默认忽略的任何文件，则可以 明确注册 这些源。

¥If you need to scan any files that Tailwind is ignoring by default, you can explicitly register those sources.

显式注册源(Explicitly registering sources)

¥Explicitly registering sources

使用 @source 明确注册相对于样式表的源路径：

¥Use @source to explicitly register source paths relative to the stylesheet:

@import "tailwindcss";
@source "../node_modules/@acmecorp/ui-lib";

当你需要扫描使用 Tailwind 构建的外部库时，这特别有用，因为依赖通常列在你的 .gitignore 文件中，并且默认情况下被 Tailwind 忽略。

¥This is especially useful when you need to scan an external library that is built with Tailwind, since dependencies are usually listed in your .gitignore file and ignored by Tailwind by default.

设置基本路径(Setting your base path)

¥Setting your base path

默认情况下，Tailwind 使用当前工作目录作为扫描类名的起点。

¥Tailwind uses the current working directory as its starting point when scanning for class names by default.

要明确设置源检测的基本路径，请在 CSS 中导入 Tailwind 时使用 source() 函数：

¥To set the base path for source detection explicitly, use the source() function when importing Tailwind in your CSS:

@import "tailwindcss" source("../src");

这在使用 monorepos 时很有用，其中你的构建命令从 monorepo 的根目录而不是每个项目的根目录运行。

¥This can be useful when working with monorepos where your build commands run from the root of the monorepo instead of the root of each project.

忽略特定路径(Ignoring specific paths)

¥Ignoring specific paths

使用 @source not 在扫描类名时忽略相对于样式表的特定路径：

¥Use @source not to ignore specific paths, relative to the stylesheet, when scanning for class names:

@import "tailwindcss";
@source not "../src/components/legacy";

当你的项目中存在大型目录并且你知道它们不使用 Tailwind 类（例如旧版组件或第三方库）时，这将非常有用。

¥This is useful when you have large directories in your project that you know don't use Tailwind classes, like legacy components or third-party libraries.

禁用自动检测(Disabling automatic detection)

¥Disabling automatic detection

如果你想明确注册所有源，请使用 source(none) 完全禁用自动源检测：

¥Use source(none) to completely disable automatic source detection if you want to register all of your sources explicitly:

@import "tailwindcss" source(none);
@source "../admin";
@source "../shared";

这在具有多个 Tailwind 样式表的项目中很有用，你希望确保每个样式表仅包含每个样式表所需的类。

¥This can be useful in projects that have multiple Tailwind stylesheets where you want to make sure each one only includes the classes each stylesheet needs.

将特定工具添加到安全列表(Safelisting specific utilities)

¥Safelisting specific utilities

如果你需要确保 Tailwind 生成内容文件中不存在的某些类名，请使用 @source inline() 强制生成它们：

¥If you need to make sure Tailwind generates certain class names that don’t exist in your content files, use @source inline() to force them to be generated:

@import "tailwindcss";
@source inline("underline");

.underline {
  text-decoration: underline;
}

将变体添加到安全列表(Safelisting variants)

¥Safelisting variants

你还可以使用 @source inline() 生成带有变体的类。例如，要生成带有悬停和聚焦变体的 underline 类，请将 {hover:,focus:,} 添加到源输入：

¥You can also use @source inline() to generate classes with variants. For example, to generate the underline class with hover and focus variants, add {hover:,focus:,} to the source input:

@import "tailwindcss";
@source inline("{hover:,focus:,}underline");

.underline {
  text-decoration: underline;
}
@media (hover: hover) {
  .hover\:underline:hover {
    text-decoration: underline;
  }
}
@media (focus: focus) {
  .focus\:underline:focus {
    text-decoration: underline;
  }
}

将范围添加到安全列表(Safelisting with ranges)

¥Safelisting with ranges

源输入为 括号已展开，因此你可以一次生成多个类。例如，要生成所有带有悬停变体的红色背景颜色，请使用范围：

¥The source input is brace expanded, so you can generate multiple classes at once. For example, to generate all the red background colors with hover variants, use a range:

@import "tailwindcss";
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");

.bg-red-50 {
  background-color: var(--color-red-50);
}
.bg-red-100 {
  background-color: var(--color-red-100);
}
.bg-red-200 {
  background-color: var(--color-red-200);
}
/* ... */
.bg-red-800 {
  background-color: var(--color-red-800);
}
.bg-red-900 {
  background-color: var(--color-red-900);
}
.bg-red-950 {
  background-color: var(--color-red-950);
}
@media (hover: hover) {
  .hover\:bg-red-50:hover {
    background-color: var(--color-red-50);
  }
  /* ... */
  .hover\:bg-red-950:hover {
    background-color: var(--color-red-950);
  }
}

这将生成从 100 到 900 的红色背景色，增量为 100，并且第一个和最后一个渐变色分别为 50 和 950。它还会为每个类添加 hover: 变体。

¥This generates red background colors from 100 to 900 in increments of 100, along with the first and last shades of 50 and 950. It also adds the hover: variant for each of those classes.

明确排除类别(Explicitly excluding classes)

¥Explicitly excluding classes

使用 @source not inline() 阻止生成特定类，即使在源文件中检测到它们：

¥Use @source not inline() to prevent specific classes from being generated, even if they are detected in your source files:

@import "tailwindcss";
@source not inline("{hover:,focus:,}bg-red-{50,{100..900..100},950}");

这将明确排除红色背景工具及其悬停和聚焦变体的生成。

¥This will explicitly exclude the red background utilities, along with their hover and focus variants, from being generated.