企业官网建设流程全解析

DaisyUI Pagination 分页组件实战指南：join + btn 组合的类名体系与源码原理

【免费下载链接】daisyui🌼 🌼 🌼 🌼 🌼 The most popular, free and open-source Tailwind CSS component library项目地址: https://gitcode.com/GitHub_Trending/da/daisyui

Pagination（分页）是 DaisyUI 中一个典型的组合型组件：它本身没有独立 CSS 文件，而是由join（容器）与btn（按钮）两个基础组件协作构成的一组按钮。本文以 skills/daisyui/components/pagination.md 为骨架，结合仓库中 join 工具类源码、button 组件源码 与官方文档页 pagination +page.md/components/pagination/+page.md)，完整讲解类名体系、语法规则、常见形态（尺寸、禁用、radio 选中态）以及底层圆角合并与边框折叠的实现原理，读完后可直接在项目中落地可复用的分页器。

一、组件定位：Pagination 是一个"按钮组"

在 DaisyUI 中，分页组件并非独立实现的 UI 单元，而是一种结构约定：Pagination is a group of buttons（分页是一组按钮）。官方文档明确说明，实现分页时复用 join 组件 将多个链接或按钮并排展示。

这种"组合而非新组件"的设计带来两个直接好处：

• 视觉上天然获得 join 提供的圆角合并能力（首尾项圆角、中间项直角、边框合并）；
• 行为上完全继承btn的交互状态（hover、active、focus、disabled 等）。

二、类名体系

分页组件涉及三类类名，全部来自 DaisyUI 的join与btn体系：

此外，每个分页项还需要btn类来获得按钮外观（见下文第三节）。

从源码看，这三类类名分别承担不同职责（join.css）：

• .join负责建立 flex 容器：inline-flex items-stretch，并初始化 8 个圆角/边距 CSS 变量（--join-ss、--join-se、--join-es、--join-ee、--join-ml、--join-mt、--join-v、--join-h）；
• .join-item负责把--join-*变量映射为实际的border-start-start-radius等圆角属性与负 margin 边框折叠；
• .join-vertical/.join-horizontal通过切换--join-v/--join-h变量值决定圆角与边框的折叠方向。

三、语法与使用规则

分页的基本语法非常简洁：

<div class="join">{CONTENT}</div>

其中{CONTENT}为若干个带join-item的按钮或链接。核心规则有两条：

1. 分页中的每个按钮或链接都必须使用join-item类，否则不会被 join 容器纳入圆角合并与边框折叠体系；
2. 用btn类来为分页项提供按钮样式，这是分页项看起来像"按钮"而非普通文本的原因。

一个最基础的分页示例：

<div class="join"> <button class="join-item btn">1</button> <button class="join-item btn">2</button> <button class="join-item btn">3</button> <button class="join-item btn">4</button> </div>

提示：分页项不限于<button>，也可是<a>链接。若希望多个 join 组并排或嵌套，可参考 join.md 中的{MODIFIER}语法与lg:join-horizontal响应式用法。

四、常见形态实战

官方组件文档（pagination +page.md/components/pagination/+page.md)）给出了六种高频形态，以下全部继承并展开。

4.1 带当前页（active）的分页

使用btn-active标记当前页：

<div class="join"> <button class="join-item btn">1</button> <button class="join-item btn btn-active">2</button> <button class="join-item btn">3</button> <button class="join-item btn">4</button> </div>

btn-active在 button.css 中通过color-mix对背景色压暗 5%、边框压暗 7%，并移除内阴影与投影，形成视觉上的"按下/选中"状态。

4.2 五种尺寸：xs / sm / md / lg / xl

分页随btn尺寸类缩放，DaisyUI 共提供 5 档，源码中的实际尺寸变量如下：

其中--size-field默认 0.25rem，可被主题覆盖以整体调整按钮密度。示例（xs 档）：

<div class="join"> <button class="join-item btn btn-xs">1</button> <button class="join-item btn btn-xs btn-active">2</button> <button class="join-item btn btn-xs">3</button> <button class="join-item btn btn-xs">4</button> </div>

其余尺寸只需把btn-xs依次替换为btn-sm、btn-md、btn-lg、btn-xl即可，结构完全一致。

4.3 带禁用按钮的分页

用btn-disabled表示省略号或不可点击的页码：

<div class="join"> <button class="join-item btn">1</button> <button class="join-item btn">2</button> <button class="join-item btn btn-disabled">...</button> <button class="join-item btn">99</button> <button class="join-item btn">100</button> </div>

源码层面，.btn-disabled与.btn:is(:disabled, [disabled], [aria-disabled="true"])等效（button.css），会应用pointer-events-none、文字颜色降为 20% 混合透明、并叠加bg-base-content/10底色。同时 join.css 对禁用项单独处理边框宽度，保证禁用项在 join 中依然保持边框折叠的连贯性。

4.4 极小按钮形态（前后翻页箭头）

使用文本符号«/»配合页码：

<div class="join"> <button class="join-item btn">«</button> <button class="join-item btn">Page 22</button> <button class="join-item btn">»</button> </div>

4.5 等宽的前一页 / 下一页（outline 按钮）

在join上叠加 Tailwind 网格类grid grid-cols-2，配合btn-outline让两个按钮等分宽度：

<div class="join grid grid-cols-2"> <button class="join-item btn btn-outline">Previous page</button> <button class="join-item btn btn-outline">Next</button> </div>

btn-outline在源码中会清除按钮背景与阴影，仅保留边框和文字色（--btn-bg: #0000，边框色取--btn-color或--color-base-content），适合"上一页/下一页"这种次级操作。

4.6 使用 radio 输入实现"单选页码"

将join-item与btn btn-square组合，用原生 radio 实现无需 JS 的单选分页（同一name下天然互斥）：

<div class="join"> <input class="join-item btn btn-square" type="radio" name="options" aria-label="1" checked="checked" /> <input class="join-item btn btn-square" type="radio" name="options" aria-label="2" /> <input class="join-item btn btn-square" type="radio" name="options" aria-label="3" /> <input class="join-item btn btn-square" type="radio" name="options" aria-label="4" /> </div>

两个细节值得注意：

• btn-square通过px-0+width/height: var(--size)把按钮压成正方形（button.css）；
• 勾选态由 button 源码中的&:checked规则接管：--btn-color切换为主题主色--color-primary，文字色切换为--color-primary-content，视觉上即"高亮当前页"。

五、源码原理：join 是如何"无缝连接"按钮的

理解了用法，再看 join.css 的底层机制，能帮你更灵活地定制分页：

1. 圆角变量体系。.join预设 4 个圆角变量（--join-ss起始边起始角、--join-se起始边结束角、--join-es结束边起始角、--join-ee结束边结束角），并通过:first-child/:last-child/:only-child规则分发：首项获得左侧圆角、末项获得右侧圆角、独占项四角全圆角，中间项四角为 0，从而拼出"首尾圆、中间方"的分页条。

2. 边框折叠。相邻项通过负 margin 合并 1px 边框：:not(:first-child)设置--join-ml: calc(var(--border, 1px) * -1 * var(--join-h))。水平方向--join-h: 1产生负左外边距，垂直方向--join-v: 1产生负上外边距，避免相邻按钮边框叠加成 2px 粗线。

3. 方向切换。.join-vertical设置flex-col且--join-v: 1; --join-h: 0；.join-horizontal设置flex-row且--join-v: 0; --join-h: 1。方向变量同时驱动圆角与边框折叠的轴向，因此同一套变量即可适配横竖两种分页布局。

4. 层级处理。容器使用@scope局部作用域：聚焦项（:focus/:has(:focus)）提升到z-2，hover 项提升到z-1，确保圆角重叠处聚焦/悬停状态的边框完整显示，这也是"当前页高亮不被相邻按钮遮挡"的原因。

5. 与 btn 的圆角联动。button.css 中.btn的圆角声明为border-start-start-radius: var(--join-ss, var(--radius-field))等，即优先读取 join 注入的圆角变量，未参与 join 时才回退到全局圆角--radius-field。这就是"按钮一旦放进 join 就自动合并圆角"的底层契约。

六、小结与进一步阅读

DaisyUI 的分页组件遵循"容器类 + 成员类 + 按钮类"的最小化类名约定：join组织结构、join-item声明成员、btn（及其btn-active、btn-disabled、btn-outline、btn-square、尺寸类）定义外观。从 pagination.md 的两条规则出发，配合官方文档页中的六种形态示例，即可覆盖从简单页码条到"上一页/下一页"、radio 单选分页等绝大多数业务场景。

需要深入了解的读者可以继续阅读：

• 组件骨架定义：skills/daisyui/components/pagination.md、skills/daisyui/components/join.md
• 官方组件文档（含全部可交互示例）：pagination +page.md/components/pagination/+page.md)
• 布局与边框折叠实现：join.css
• 按钮尺寸、状态与圆角联动实现：button.css

【免费下载链接】daisyui🌼 🌼 🌼 🌼 🌼 The most popular, free and open-source Tailwind CSS component library项目地址: https://gitcode.com/GitHub_Trending/da/daisyui