检测源文件中的类

概述(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.

禁用自动检测(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.