daisyUI Timeline 组件完全指南：从时间轴基础布局到响应式实战

daisyUI Timeline 组件完全指南：从时间轴基础布局到响应式实战

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

Timeline（时间线）是 daisyUI 中用于按时间顺序展示事件列表的组件，它用一条贯穿的连接线和图标节点，把「事件时间」「事件描述」「过程图标」组织成清晰可读的序列。本文以 daisyUI 官方组件文档 Timeline 页面/components/timeline/+page.md) 为主体，结合组件源码 timeline.css 与文档站点的前缀渲染机制，完整讲解 Timeline 的类名体系、水平/垂直布局、单侧/双侧内容排布、彩色连接线、响应式切换、图标吸顶与紧凑模式，并深入源码揭示其基于 CSS Grid 的实现原理，读完即可在真实项目中直接落地使用。

Timeline 组件定位与类名体系

Timeline 组件以<ul>作为容器，每个<li>表示一个时间点事件。官方文档在其 frontmatter 中定义了完整的类名体系，分为四类：

其中timeline-horizontal是默认方向；添加timeline-vertical类即可切换到垂直布局，两者可响应式组合使用（见下文）。

基础结构：ul > li 三区块与 hr 连接线

Timeline 的最小骨架如下：

<ul class="timeline"> <li> <div class="timeline-start">1984</div> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-end timeline-box">First Macintosh computer</div> <hr /> </li> </ul>

官方文档特别强调了一条关键规则（INFO 提示）：

每个条目开头或结尾的hr标签，用于显示连接相邻条目的线条。

也就是说，<li>内部的<hr>不是普通的水平分割线，而是被 Timeline 组件当作「连接线」使用：它占据网格中的连接列/行，把前后两个事件的节点串起来。从源码看，hr的默认样式是h-1（水平方向 4px 高）加上bg-base-300背景色（timeline.css），并且被取消了默认边框（border: none，timeline.css）。

水平时间线（默认方向）的五种排布

默认情况下（不写方向类，flex默认为行方向），Timeline 呈水平走向。官方文档给出了五种典型排布。

双侧文字 + 图标

这是最经典的形态：上方放时间、中间放图标、下方放事件描述，每个<li>之间用hr连接：

<ul class="timeline"> <li> <div class="timeline-start">1984</div> <div class="timeline-middle"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="h-5 w-5"> <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.857-9.809a.75.75 0 00-1.214-.882l-3.483 4.79-1.88-1.88a.75.75 0 10-1.06 1.061l2.5 2.5a.75.75 0 001.137-.089l4-5.5z" clip-rule="evenodd" /> </svg> </div> <div class="timeline-end timeline-box">First Macintosh computer</div> <hr /> </li> <li> <hr /> <div class="timeline-start">1998</div> <div class="timeline-middle"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="h-5 w-5"> <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.857-9.809a.75.75 0 00-1.214-.882l-3.483 4.79-1.88-1.88a.75.75 0 10-1.06 1.061l2.5 2.5a.75.75 0 001.137-.089l4-5.5z" clip-rule="evenodd" /> </svg> </div> <div class="timeline-end timeline-box">iMac</div> <hr /> </li> <li> <hr /> <div class="timeline-start">2001</div> <div class="timeline-middle"> <!-- 图标 SVG 同上 --> </div> <div class="timeline-end timeline-box">iPod</div> <hr /> </li> <li> <hr /> <div class="timeline-start">2007</div> <div class="timeline-middle"> <!-- 图标 SVG 同上 --> </div> <div class="timeline-end timeline-box">iPhone</div> <hr /> </li> <li> <hr /> <div class="timeline-start">2015</div> <div class="timeline-middle"> <!-- 图标 SVG 同上 --> </div> <div class="timeline-end timeline-box">Apple Watch</div> </li> </ul>

注意观察hr的放置规律：除了第一个<li>的开头，以及最后一个<li>的结尾，其余每个<li>的前后都各有一个hr——前一个hr承接上一节点，后一个hr引出下一节点。最后一个<li>可以省略尾部hr，第一条目也可以省略头部hr。这里timeline-end还叠加了timeline-box，让描述文字带上卡片盒样式。

仅下方（bottom side only）

若只写timeline-middle+timeline-end（不写timeline-start），事件内容会全部排在轴线的下方，适合「时间不重要、只需事件流」的展示：

<ul class="timeline"> <li> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-end timeline-box">First Macintosh computer</div> <hr /> </li> <li> <hr /> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-end timeline-box">iMac</div> <hr /> </li> <!-- 后续 <li> 结构相同 --> </ul>

仅上方（top side only）

反过来，只写timeline-start+timeline-middle，内容全部排在上方：

<ul class="timeline"> <li> <div class="timeline-start timeline-box">First Macintosh computer</div> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <hr /> </li> <li> <hr /> <div class="timeline-start timeline-box">iMac</div> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <hr /> </li> <!-- 后续 <li> 结构相同 --> </ul>

左右交错（different sides）

每个<li>独立决定内容放在上方还是下方，即可实现上下交错的效果（例如奇偶项交替），适合需要视觉节奏感的场景：

<ul class="timeline"> <li> <div class="timeline-start timeline-box">First Macintosh computer</div> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <hr /> </li> <li> <hr /> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-end timeline-box">iMac</div> <hr /> </li> <li> <hr /> <div class="timeline-start timeline-box">iPod</div> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <hr /> </li> <!-- 后续 <li> 按需交错 --> </ul>

彩色连接线（colorful lines）

连接线本质是带bg-base-300的hr，因此可以直接用 Tailwind 的颜色类覆盖它。给hr加bg-primary，同时给图标加text-primary，即可得到一条主色贯穿的强调式时间线：

<ul class="timeline"> <li> <div class="timeline-start timeline-box">First Macintosh computer</div> <div class="timeline-middle"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="text-primary h-5 w-5"> <!-- 对勾 path --> </svg> </div> <hr class="bg-primary" /> </li> <li> <hr class="bg-primary" /> <div class="timeline-middle"> <!-- 图标 SVG（text-primary） --> </div> <div class="timeline-end timeline-box">iMac</div> <hr class="bg-primary" /> </li> <!-- 只对需要的线段加 bg-primary，未强调的线段保持默认 --> </ul>

无图标（without icons）

完全省略timeline-middle，让时间线与卡片直接相连，得到极简的纯文字时间线：

<ul class="timeline"> <li> <div class="timeline-start timeline-box">First Macintosh computer</div> <hr /> </li> <li> <hr /> <div class="timeline-end timeline-box">iMac</div> <hr /> </li> <li> <hr /> <div class="timeline-start timeline-box">iPod</div> <hr /> </li> <li> <hr /> <div class="timeline-end timeline-box">iPhone</div> <hr /> </li> <li> <hr /> <div class="timeline-start timeline-box">Apple Watch</div> </li> </ul>

垂直时间线（timeline-vertical）

在<ul>上追加timeline-vertical，轴线即转为从上到下，timeline-start/timeline-end相应变为左/右两侧。官方文档为垂直方向同样提供了全部五种排布，结构上与水平版一一对应，仅容器多了方向类：

<ul class="timeline timeline-vertical"> <li> <div class="timeline-start">1984</div> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-end timeline-box">First Macintosh computer</div> <hr /> </li> <li> <hr /> <div class="timeline-start">1998</div> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-end timeline-box">iMac</div> <hr /> </li> <!-- 后续 <li> 结构相同 --> </ul>

• 仅右侧：只写timeline-middle+timeline-end，事件内容全部在轴线右侧；
• 仅左侧：只写timeline-start+timeline-middle，事件内容全部在轴线左侧；
• 交错：各<li>自由选择timeline-start或timeline-end，实现左右交替；
• 彩色连接线：同样通过hr class="bg-primary"+ 图标text-primary实现；
• 无图标：省略timeline-middle即可。

垂直时间线尤其适合移动端纵向滚动阅读，也是官方推荐的默认响应式方案（见下节）。

响应式：默认垂直、大屏水平

把方向类与 Tailwind 断点前缀组合，即可实现「小屏垂直、大屏水平」的经典响应式时间线。官方示例在lg断点切换：

<ul class="timeline timeline-vertical lg:timeline-horizontal"> <li> <div class="timeline-start">1984</div> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-end timeline-box">First Macintosh computer</div> <hr /> </li> <li> <hr /> <div class="timeline-start">1998</div> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-end timeline-box">iMac</div> <hr /> </li> <!-- 后续 <li> 结构相同 --> </ul>

其原理是timeline-vertical与timeline-horizontal分别应用flex-col/flex-row（见 timeline.css），而 Tailwind 的lg:前缀会在 ≥1024px 的视口下覆盖为水平布局。由于内部li的网格定位逻辑在源码中分别针对两种方向做了完整实现，切换布局时内容会自动重新排布，无需改动任何li内部结构。

高级：图标吸顶（timeline-snap-icon）与紧凑模式（timeline-compact）

官方文档最后给出一个组合了多个 modifier 的长文本示例：

<ul class="timeline timeline-snap-icon max-md:timeline-compact timeline-vertical"> <li> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-start mb-10 md:text-end"> <time class="font-mono italic">1984</time> <div class="text-lg font-black">First Macintosh computer</div> <!-- 长段落文字 --> </div> <hr /> </li> <li> <hr /> <div class="timeline-middle"> <!-- 图标 SVG --> </div> <div class="timeline-end md:mb-10"> <time class="font-mono italic">1998</time> <div class="text-lg font-black">iMac</div> <!-- 长段落文字 --> </div> <hr /> </li> <!-- 后续 <li> 结构相同 --> </ul>

这里同时用到了三个关键技巧：

• timeline-snap-icon：把原本位于行/列中间的图标「吸附」到起点位置。官方定义其作用为 "snaps the icon to the start instead of middle"。从源码看，它通过覆盖网格变量实现：水平方向设置--timeline-col-start: 0.5rem，垂直方向设置--timeline-row-start: 0.5rem（timeline.css），把图标偏移到时间轴起点，让长文本从顶部对齐，配合time、加粗标题、段落文字可以做出「时间 + 标题 + 正文」的富文本时间线。
• timeline-compact：官方定义其作用为 "forces all items on one side"（强制所有条目位于同一侧）。源码中它在水平方向把--timeline-row-start设为0，垂直方向把--timeline-col-start设为0，使内容收拢到单侧（timeline.css）。
• max-md:timeline-compact：这是响应式组合的另一种用法——在max-md（小于 md 断点）以下才启用紧凑模式，小屏单侧堆叠、大屏双侧展开。

辅助排版上，示例还使用了time元素加font-mono italic表现年份、text-lg font-black表现标题、mb-10/md:mb-10/md:text-end控制间距与对齐，说明 Timeline 的内容区完全兼容 Tailwind 的任意工具类。

源码原理：CSS Grid 如何驱动 Timeline

Timeline 的精髓在于 timeline.css 中基于 CSS Grid 的实现。每个li被定义为3×3 网格：

> li { @apply relative grid shrink-0 items-center; grid-template-rows: var(--timeline-row-start, minmax(0, 1fr)) auto var(--timeline-row-end, minmax(0, 1fr)); grid-template-columns: var(--timeline-col-start, minmax(0, 1fr)) auto var(--timeline-col-end, minmax(0, 1fr)); }

三个区块分别落入网格的对应位置：

• timeline-start：水平方向占据第 1 行（上方）、跨满 3 列；垂直方向占据第 1 列（左侧）、跨满 3 行（timeline.css）；
• timeline-middle：固定在中间单元格col-start-2 row-start-2（timeline.css），图标因此天然居中线；
• timeline-end：水平方向占据第 3 行（下方）、跨满 3 列（timeline.css）。

而hr连接线被放进中间列的上下单元格（水平布局）或中间行的左右单元格（垂直布局），并针对「首尾条目」做了精细化圆角处理：源码通过:has(.timeline-middle)判断是否存在中间图标，进而决定连接线端头的rounded-e-selector/rounded-s-selector圆角方向，避免首尾出现多余的圆头（timeline.css）。

timeline-box则是一个独立的卡片盒样式：rounded-box圆角、bg-base-100背景、border-base-300边框、px-4 py-2内边距，外加极浅的阴影与 0.75rem 字号（timeline.css），所以它可以放心地叠加在timeline-start或timeline-end上。

这套网格方案的核心变量是--timeline-row-start/--timeline-col-start等 CSS 自定义属性，timeline-compact、timeline-snap-icon正是通过改写这些变量（而非复制整套布局代码）来切换行为，这也是组件实现高度精简的原因。

前缀机制：文档中的$$占位符从何而来

细心的读者会发现，官方文档所有代码示例中类名写作$$timeline、$$timeline-vertical等。这是文档站点为了支持「类名前缀」配置而引入的占位符机制：文档站点组件 actions.svelte.js 中的prefixClassNames动作会监听前缀 store，并执行node.innerHTML = originalContent.replaceAll("$$", prefixValue)，把$$实时替换成用户配置的前缀（默认为空字符串，替换后即普通的timeline）。

与之对应的是组件库构建期的前缀能力：addPrefix.js 会在编译时按配置为所有组件类名批量添加前缀（例如配置前缀d-后生成d-timeline），其测试用例 addPrefix.test.js 中即包含timeline与.timeline:has(.timeline-middle hr):first-child这类选择器的前缀改写验证。因此在实际项目中使用时，写timeline系列类名即可，若配置了自定义前缀则统一使用配置后的名称。

使用要点小结

• 容器用<ul class="timeline">，事件用<li>，不要嵌套多余元素破坏网格结构；
• hr是连接线不是分割线：保留首尾条目的hr用于串接，除首/末条目外每个<li>前后各放一个；
• 三区块可按需省略：只要timeline-start/timeline-end存在，内容就会自动落到对应侧；都省略则得到纯节点时间线；
• 方向类决定走向：timeline-horizontal（默认）与timeline-vertical，可结合lg:、max-md:等断点做响应式切换；
• timeline-box可叠加在任意一侧内容上，快速获得卡片样式；timeline-snap-icon与timeline-compact用于长文本场景的图标吸顶与单侧紧凑排布；
• 连接线颜色可自由覆盖：给hr加bg-*、给图标加text-*即可，无需额外配置。

以上内容可直接参考官方示例源文件 timeline 组件文档/components/timeline/+page.md)、组件样式实现 timeline.css，以及提供给 AI 工具链的简明用法说明 timeline.md，在项目中按需组合使用。

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