Tailwind CSS 插件 · v1.4.2

Bootstrap 栅格, 为 Tailwind 而生。

如果你已经习惯用行和列来思考,那就继续这样。tw-bootstrap-grid 把你熟悉的 12 列栅格带到 Tailwind 中,包括 .row、.col-6、.offset-2 和 .g-4,支持 RTL,并且不会对你的组件应该是什么样子指手画脚。

$npm install tw-bootstrap-grid

你能得到什么

  • 12 列栅格

    .row、.col、.col-auto,以及 .col-1 到 .col-12,和 Bootstrap 一样。

  • 来自你主题的 gutter

    .g-*、.gx-* 和 .gy-* 使用你的 Tailwind 间距刻度,因此与设计的其余部分保持一致。

  • Offset 偏移

    .offset-0 到 .offset-12,用来让一列居中或留出空隙。

  • 每行列数

    .row-cols-1 到 .row-cols-6 以及 .row-cols-auto,只需在行上写一个类,就能设定所有子元素的宽度。

  • 容器

    .container 和 .container-fluid,其内边距会考虑 gutter。最大宽度来自 Tailwind 自己的断点。

  • 响应式与 RTL

    每个类都支持 Tailwind 的断点前缀,例如 md:col-6,并且在 dir="rtl" 下会正确翻转。

它只负责布局:没有颜色,没有组件,也没有重置样式。它是在 Tailwind 之上添加内容,而不是替换其中任何东西,所以你可以毫不犹豫地在同一个页面里混用 col-4 和 flex。

快速上手

安装

三个步骤:安装包、注册插件、开始使用这些类。

1安装包

npm install tw-bootstrap-grid

2注册插件

在页眉中选择你的 Tailwind 版本,下面的代码片段会随之变化。Tailwind v4 在 CSS 中注册插件,v3 则在配置文件中注册。

Tailwind v4

main.css
@import "tailwindcss";
@plugin "tw-bootstrap-grid";

在使用 CommonJS 的 v3 配置中,plugins: [require("tw-bootstrap-grid")] 同样可用。

3使用这些类

就是这样。像使用其他 Tailwind 类一样,把它们写进你的标记里。凡是 sm:、md: 或 hover: 能做到的,在这里同样适用。

index.html
<div class="container">
  <div class="row g-4">
    <div class="col-12 md:col-6 lg:col-4">One</div>
    <div class="col-12 md:col-6 lg:col-4">Two</div>
    <div class="col-12 lg:col-4">Three</div>
  </div>
</div>

你需要一个构建步骤

插件运行在 Tailwind 的编译器内部(PostCSS、Vite、Webpack、Tailwind CLI……)。它无法配合 Tailwind Play CDN 脚本使用,因为那个脚本没办法从 npm 加载插件。

快速上手

配置

默认值与 Bootstrap 一致,所以你可以跳过本页。当你想要不同的断点或 gutter 尺寸时再回来。

断点

插件本身没有断点。像 md:col-6 这样的前缀以及 .container 的最大宽度都来自 Tailwind,因此修改你的屏幕断点,栅格也会随之改变。

Tailwind v4

main.css
@import "tailwindcss";
@plugin "tw-bootstrap-grid";

@theme {
  --breakpoint-sm: 40rem;  /* 640px */
  --breakpoint-md: 48rem;  /* 768px */
  --breakpoint-lg: 64rem;  /* 1024px */
  --breakpoint-xl: 80rem;  /* 1280px */
  --breakpoint-2xl: 96rem; /* 1536px */
}

Gutter 尺寸

Gutter 是列与列之间的间距。默认情况下水平方向为 1.5rem,垂直方向为 0。你可以一次性为所有内容设置,也可以分别为容器和行设置。在 v3 中向插件传入选项,在 v4 中设置 CSS 变量。

Tailwind v4

main.css
@import "tailwindcss";
@plugin "tw-bootstrap-grid";

:root {
  /* used by containers and rows */
  --bs-global-gutter-x: 1.5rem;
  --bs-global-gutter-y: 0;

  /* overrides for one of them only */
  --bs-container-gutter-x: 1rem;
  --bs-row-gutter-x: 2rem;
  --bs-row-gutter-y: 1rem;
}
Gutter 的取值顺序
优先级CSS 变量选项说明
1--bs-row-gutter-x / --bs-container-gutter-xrowGutters / containerGutters最具体的值优先。
2--bs-global-gutter-xgutters两者共用的后备值。
31.5rem (x) 和 0 (y)内置默认值与 Bootstrap 使用的默认值相同。

CSS 变量在运行时读取,因此无论哪个版本,你都可以在任意元素上覆盖它们,只改变那一部分的 gutter。对于单独一行,请使用 .g-*、.gx-* 和 .gy-*。

关闭容器

只想用 Tailwind 自带的 container?把 generateContainers 设为 false,插件就不再生成 .container-fluid 及其考虑 gutter 的内边距。行和列不受影响。

Tailwind v4

main.css
@import "tailwindcss";
@plugin "tw-bootstrap-grid" {
  generateContainers: false;
}

为什么 v4 用变量?

Tailwind v4 可以向插件传递 generateContainers: false; 这样的简单值,但不能传递 gutters 这样的嵌套对象。CSS 变量能解决这个问题,还有一个好处,就是可以针对单个元素覆盖。

参考

类名

插件添加的所有内容,集中在这里。

布局

布局类名
类名作用说明
.containerwidth: 100%;居中;内边距取自 gutter最大宽度来自 Tailwind 的断点。
.container-fluid与 .container 相同在每个断点下都是全宽。
.rowdisplay: flex; flex-wrap: wrap; 负外边距抵消外侧的 gutter,并排布它的子元素。

列

列类名
类名作用说明
.colflex: 1 0 0%平均分配剩余空间。
.col-autoflex: 0 0 auto; width: auto宽度由内容决定。
.col-1 … .col-12flex: 0 0 auto; width: n / 12占 12 份中的 n 份。

Offset 与每行列数

Offset 与每行列数类名
类名作用说明
.offset-0 … .offset-12margin-inline-start: n / 12在 RTL 中自动翻转。
.row-cols-1 … .row-cols-6子元素获得 width: 1 / n设置在 .row 上,作用于每个子元素。
.row-cols-auto子元素获得 width: auto子元素的宽度由内容决定。

Gutter

Gutter类名
类名作用说明
.g-*--bs-gutter-x 和 --bs-gutter-y两个方向。
.gx-*--bs-gutter-x仅水平方向。
.gy-*--bs-gutter-y仅垂直方向。

一切都是响应式的

给上面任何一个类加上断点前缀即可:md:col-6、lg:offset-3、sm:row-cols-2、xl:g-8。

有哪些 gutter 档位?

.g-*、.gx-* 和 .gy-* 由你的间距主题生成。在 v3 中,是 theme.spacing 里所有不带小数点的键(所以有 g-4,没有 g-0.5)。在 v4 中,是默认刻度,即 g-0 到 g-96 以及 g-px。

对齐与排序来自 Tailwind

插件不提供自己的 justify-*、items-* 或 order-*。.row 就是一个普通的 flex 容器,所以 Tailwind 的工具类可以直接作用于它。

从 Bootstrap 迁移

从 Bootstrap 迁移

栅格的工作方式和你记忆中的一样。有三处看起来不同:响应式类的写法、间距数值,以及断点宽度。

  • 保持不变的部分

    结构:.container、.row、.col-*、.offset-*、.row-cols-*。就连 CSS 变量的名字也保持不变,即 --bs-gutter-x 和 --bs-gutter-y,所以读取它们的自定义 CSS 仍然可用。

  • 前缀,而不是中缀

    Bootstrap 写作 col-md-6,Tailwind 写作 md:col-6。这是你改动最多的地方,而一个脚本就可以替你完成。

  • 不同的数值

    Gutter 和间距的数值遵循 Tailwind 的刻度,所以 Bootstrap 的 g-3 在这里是 g-4。断点的宽度也略有不同。

完整指南包含类名对照表、gutter 尺寸的变化、如何对齐 Bootstrap 的断点,以及一条可以转换你的标记的命令。

阅读迁移指南

用法

示例

每个示例都是实时的。编辑左侧的 HTML,预览会随着你的输入更新。如果你了解 Bootstrap 栅格 (在新标签页中打开),这会让你感到熟悉。

基本布局

.container 让内容居中,.row 把各列并排排列,每个 .col-* 占据 12 份中相应的份数。两个 col-6 列把一行平分。

预览
可编辑的 HTML

列总是会换行。一行中超过 12 份的部分会掉到下一行,这对卡片列表很方便。

等宽列与自动宽度列

单独的 .col 会平分剩余空间,所以三个这样的列就是三个等宽列。.col-auto 根据内容决定自己的宽度,旁边的 .col 占据剩下的部分。

预览
可编辑的 HTML

响应式列

每个类都支持 Tailwind 的断点前缀。先从移动端的 col-12 开始,再用 sm:、md:、lg: 等在更大的屏幕上改变宽度。使用预览上方的宽度按钮,可以看到每个断点如何生效。

预览
768px · md · 0%
可编辑的 HTML

预览是一个真实的视口。它在角落显示宽度和断点,手机、平板和桌面按钮可以切换它,所以 md: 和 lg: 的生效方式与在那种屏幕上完全一样。

Gutter

Gutter 是列与列之间的间隙。.g-* 同时设置两个方向,.gx-* 只设置水平方向,.gy-* 只设置垂直方向。数值来自 Tailwind 的间距刻度,所以 g-4 和 p-4 是同一档。

预览
可编辑的 HTML

把 gutter 类放在 .row 上。使用 g-0 可以完全去掉间隙。

Offset 偏移

.offset-* 把一列向旁边推开相应的份数。这是让一列居中或留出空隙的快捷方式。Offset 也支持断点前缀,例如 lg:offset-3。

预览
可编辑的 HTML

Offset 使用 margin-inline-start,所以页面从右向左排布时,它会从正确的一侧推开。试试预览上方的 RTL 按钮。

每行列数

当所有列大小相同时,只需在行上设置一次,而不必给每个子元素都设置。.row-cols-1 到 .row-cols-6 让每个子元素获得相同的份额,.row-cols-auto 则按内容决定宽度。

预览
可编辑的 HTML

把它与断点结合,可以随屏幕变大而改变列数,例如 row-cols-2 lg:row-cols-3。

嵌套

一列可以包含它自己的 .row。嵌套的行会在这一列内部开始一个新的 12 份栅格,所以你可以把一块空间按需要分割任意多次。

预览
可编辑的 HTML

对齐与排序

.row 是一个普通的 flex 容器,所以 Tailwind 自己的 flexbox 工具类可以作用于它:items-*、justify-*、self-* 和 order-*。插件不会重新定义它们。

预览
可编辑的 HTML

order-2 md:order-1 这样的调换是一种常见模式:在手机上按一种顺序堆叠,在更大的屏幕上反过来。

从右到左

在容器上设置 dir="rtl",或者在 <html> 上设置以作用于整个页面,栅格就会从右侧开始排布。阿拉伯语、波斯语、希伯来语等 RTL 语言就用它。

预览
可编辑的 HTML

无需配置。行的 gutter 是对称的,offset 使用逻辑属性,所以它们会自行翻转。

值得了解

从右到左

加上 dir="rtl",栅格就会自己镜像翻转。无需任何配置。

用于整个页面

index.html
<html dir="rtl">
  ...
</html>

用于某一部分

index.html
<div class="container" dir="rtl">
  <div class="row">
    <div class="col-6 offset-3">Starts from the right</div>
  </div>
</div>

为什么它自然就能工作

Offset 使用 margin-inline-start,而行的负外边距和列的内边距是对称的,所以它们会自行翻转。在上面任何一个示例中使用 RTL 按钮就能看到效果。

值得了解

常见问题

最常被问到的问题的解答。

不会。Tailwind 的 container 仍然负责提供各断点的最大宽度。插件在它之上添加居中和考虑 gutter 的内边距。如果你不想要这些,把 generateContainers 设为 false 即可。

可以,这正是设计的初衷。.row 是一个 flex 容器,所以 items-center、justify-between、order-2、mt-4 等都会像往常一样作用于它和它的列。

Tailwind 只会为它在你的源文件里找到的类生成 CSS。在你自己的项目中这是自动完成的。而在这个页面上,可编辑的示例可以包含任何内容,所以演示会预先生成插件的每个类和每个断点。

不可以。CDN 脚本无法从 npm 加载插件。请使用 Vite、PostCSS、Webpack 或 Tailwind CLI 这样的构建环境。

Tailwind v3.4 和 v4,Node 18 或更高版本。该包同时提供 ESM 和 CommonJS 构建,并附带 TypeScript 类型。

类名很接近:col-md-6 变成 md:col-6,gutter 数值遵循 Tailwind 的刻度。迁移指南里有完整的对照表,以及一条可以转换你的标记的命令。

发现了 bug 或有想法?

欢迎在 GitHub 上提交 issue (在新标签页中打开)或发送 pull request (在新标签页中打开)。小的修复和文档改进都非常欢迎。