Timeline 时间线

按时间顺序展示一组事件。内容为自由插槽。

与 Steps 的分工

库里已经有 SrSteps，两者容易混淆，先说清边界：

	SrSteps	SrTimeline
表达	流程进度（走到第几步）	时间顺序（何时发生）
状态	由索引自动派生	每项独立，无「当前」概念
内容	标题 + 描述	任意插槽
典型场景	下单流程、注册向导	发布记录、操作日志、里程碑

一句话：Steps 有「当前进行到哪」，Timeline 没有。

基础用法

• 2026-09-14

  提交了首个版本
• 2026-09-12

  补全单元测试，覆盖率 82%
• 2026-09-08

  依赖升级时发现一处不兼容，已回滚
• 2026-09-01

  创建仓库

<SrTimeline>
  <SrTimelineItem time="2026-09-14" type="success">提交了首个版本</SrTimelineItem>
  <SrTimelineItem time="2026-09-12">补全单元测试</SrTimelineItem>
  <SrTimelineItem time="2026-09-08" type="warning">发现一处不兼容</SrTimelineItem>
  <SrTimelineItem time="2026-09-01">创建仓库</SrTimelineItem>
</SrTimeline>

time 只是便捷属性，需要更复杂的排版时用同名插槽覆盖；内容区则是默认插槽， 随便放什么都行。

连接线只连在圆点之间

线从当前圆点下方延伸到下一项的圆点——首项上方与末项下方都不会伸出线头。

末项由 CSS 的 :last-child 判定，不靠子组件注册。

为什么不用注册式

SrSteps 用的是「子组件注册、父组件维护索引」的方案，但这里刻意不这么做：

一旦宿主用 v-if 条件渲染中间某项，注册顺序就和视觉顺序错位了。 v-for 加 v-if、或者按权限过滤掉某几条，都会触发这个问题。

CSS 永远跟着真实 DOM 走，而且省掉了一整套 provide / inject。

排布方式

• 左侧（默认）

  圆点与内容都在左侧
• 第二项

  适合日志、动态流

• 2026 Q1

  项目立项
• 2026 Q2

  组件达到 20 个
• 2026 Q3

  补齐数据录入
• 2026 Q4

  文档站上线

<SrTimeline mode="left">…</SrTimeline>
<SrTimeline mode="right">…</SrTimeline>
<SrTimeline mode="alternate">…</SrTimeline>

模式	说明
left	默认。圆点与内容都在左侧，最通用
right	镜像到右侧，给左边留空间（如配一张竖版图）
alternate	左右交替，圆点在正中轴。适合「里程碑」这类希望有仪式感的场景

alternate 超过 8 条左右会开始显得散，而且每侧只有一半宽度， 内容较长时会挤成很高的块、左右高度也不等。内容偏长时建议用 left。

倒序

• 最新

  第三条
• 居中

  第二条
• 最早

  第一条

<SrTimeline reverse>…</SrTimeline>

reverse 只影响视觉顺序，不改动宿主传入的数据——数组是宿主的东西， 组件不该为了展示去动它，否则 v-for 的 key 与索引会对不上， @click 里拿到的下标也就不再指向正确的数据。

圆点样式

• 语义色

  成功
• 语义色

  警告
• 语义色

  失败
• 自定义色

  走 color 属性
• 空心

  未激活的节点
• 进行中

  正在处理，尚未结束

<SrTimelineItem type="success">成功</SrTimelineItem>
<SrTimelineItem color="#8b5cf6">走 color 属性</SrTimelineItem>
<SrTimelineItem hollow>未激活的节点</SrTimelineItem>
<SrTimelineItem pending type="primary">正在处理</SrTimelineItem>

type 优先于 color：语义色应当走设计令牌，写死的十六进制在切换主题时 不会跟着变。color 留给品牌色、分类色这类令牌覆盖不到的场合。

pending 只该放在最后一项——它表达「还在继续」， 放在中间项上语义变成了「中间断了」。

尺寸

• 紧凑

  更小的圆点与间距
• 紧凑

  适合密集的日志流

<SrTimeline size="sm">…</SrTimeline>

自定义圆点

• 2026 Q1

  项目立项
• 2026 Q2

  组件达到 20 个

<SrTimelineItem time="2026 Q1">
  <template #dot>
    <span class="custom-dot"><SrIcon size="xs"><svg … /></SrIcon></span>
  </template>
  项目立项
</SrTimelineItem>

dot 插槽会替换掉默认圆点，但连接线的位置不变——它对齐的是圆点列的 中轴，而不是某个具体的圆点元素，因此自定义成图标、徽标还是头像都不会把线带偏。

自定义圆点的宽度上限

圆点列宽度由 --sr-timeline-head-width 控制（默认 24px， alternate 下 32px，size="sm" 时 18px）。自定义内容超出这个宽度会溢出， 需要更大的图标时覆盖该变量即可。

SrTimeline Props

名称	类型	默认值	说明
mode	'left' | 'right' | 'alternate'	'left'	排布方式
size	'sm' | 'md'	'md'	尺寸
reverse	boolean	false	是否倒序（只影响视觉顺序）

SrTimelineItem Props

名称	类型	默认值	说明
time	string	—	时间文本，也可用 time 插槽
type	'primary' | 'success' | 'warning' | 'danger'	—	圆点语义色
color	string	—	自定义圆点颜色，type 优先
hollow	boolean	false	圆点是否空心
pending	boolean	false	是否处于「进行中」（呼吸光环）

SrTimelineItem 插槽

名称	说明
default	内容区
time	自定义时间区，覆盖 time 属性
dot	自定义圆点，覆盖默认圆点

无障碍

• 容器是 <ul>、每项是 <li>，读屏软件能播报「列表，共 N 项」
• pending 的呼吸光环在 prefers-reduced-motion 下只停掉脉冲动画、 保留光环本身——静态的半透明圆环同样是「进行中」的有效信号， 直接移除会让这层语义彻底丢失（这属于降级过度）