Ant Design Timeline 时间轴组件入门:从基本用法到源码实现解析
Ant Design Timeline 时间轴组件入门:从基本用法到源码实现解析
时间轴(Timeline)是 Ant Design 中用于垂直展示按时间顺序排列信息流的展示型组件,适用于事件追踪、操作日志、流程进展等需要"从上至下、按时间串联"的典型场景。本文以 components/timeline/demo/basic.md 中的基本用法为起点,结合组件源码与样式实现,带你掌握 Timeline 与 Timeline.Item 的核心 API、颜色语义、幽灵节点(pending)机制,以及其底层 DOM 结构与 Less 样式的对应关系。
基本用法:一行代码搭建时间轴
在 Ant Design 中,时间轴的使用非常直观:外层使用 Timeline 容器,每一个节点使用 Timeline.Item 包裹。以下示例来自 components/timeline/demo/basic.md,展示了最基础的时间轴形态:
import { Timeline } from 'antd';
ReactDOM.render(
<Timeline>
<Timeline.Item>创建服务现场 2015-09-01</Timeline.Item>
<Timeline.Item>初步排除网络异常 2015-09-01</Timeline.Item>
<Timeline.Item>技术测试异常 2015-09-01</Timeline.Item>
<Timeline.Item>网络异常正在修复 2015-09-01</Timeline.Item>
</Timeline>
, mountNode);
运行这段代码后,页面上会呈现一条左侧带有竖线和圆点的纵向列表,每一项从上到下依次排列,将"创建服务现场 → 初步排除网络异常 → 技术测试异常 → 网络异常正在修复"这一系列事件按时间顺序串联起来。这正是官方文档 components/timeline/index.md 所概括的核心能力:垂直展示的时间流信息。
从仓库入口文件 index.js 可以看到,Timeline 作为独立模块导出(Timeline: require('./components/timeline')),因此你可以直接通过 import { Timeline } from 'antd' 引入使用。
组件结构:一个容器、三类节点
理解时间轴的关键在于认识它的组件层次。查看源码 components/timeline/index.jsx,可以看到组件由两部分组成:
Timeline 容器
const Timeline = React.createClass({
getDefaultProps() {
return {
prefixCls: 'ant-timeline',
};
},
render() {
const { prefixCls, children, pending } = this.props;
const pendingNode = typeof pending === 'boolean' ? null : pending;
const className = classNames({
[prefixCls]: true,
[`${prefixCls}-pending`]: !!pending,
});
return (
<ul className={className}>
{
React.Children.map(children, (ele, idx) =>
React.cloneElement(ele, {
last: idx === children.length - 1,
})
)
}
{(!!pending)
? <TimelineItem pending={!!pending}>{pendingNode}</TimelineItem>
: null}
</ul>
);
}
});
Timeline 最终渲染为一个 <ul> 列表元素,并通过 React.Children.map 遍历所有子节点:自动为最后一个子节点注入 last: true 属性,用于在渲染时对末项做特殊处理;当设置了 pending 时,还会在末尾追加一个挂起状态的 TimelineItem。
Timeline.Item 节点
const TimelineItem = React.createClass({
getDefaultProps() {
return {
prefixCls: 'ant-timeline',
color: 'blue',
last: false,
pending: false,
};
},
render() {
const { prefixCls, color, last, children, pending } = this.props;
const itemClassName = classNames({
[`${prefixCls}-item`]: true,
[`${prefixCls}-item-last`]: last,
[`${prefixCls}-item-pending`]: pending,
});
return (
<li className={itemClassName}>
<div className={`${prefixCls}-item-tail`} />
<div className={`${prefixCls}-item-head ${prefixCls}-item-head-${color}`} />
<div className={`${prefixCls}-item-content`}>{children}</div>
</li>
);
}
});
每个 Timeline.Item 渲染为一个 <li>,内部包含三个关键 DOM 节点:
| DOM 节点 | 类名 | 作用 |
|---|---|---|
| 尾部连线 | ant-timeline-item-tail |
时间轴左侧的竖向连接线 |
| 头部圆点 | ant-timeline-item-head-{color} |
每个节点左侧的圆圈标记 |
| 内容区 | ant-timeline-item-content |
承载节点文本或任意 React 内容 |
组件末尾通过 Timeline.Item = TimelineItem 将 TimelineItem 挂载为 Timeline 的静态属性,这就是 <Timeline.Item> 这种嵌套写法的来源。
API 参数详解
官方文档 components/timeline/index.md 给出了完整的参数定义,结合源码实现可以进一步明确每个参数的内部行为:
Timeline 参数
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
pending |
指定最后一个幽灵节点是否存在或内容 | boolean 或 React.Element | 无 | false |
从源码看,pending 的处理逻辑清晰可见:当值为 true 时,pendingNode 为 null,仅追加一个空内容的挂起节点;当值为 React 元素时,该元素会作为挂起节点的内容渲染。同时 pending 还会触发两个联动效果——容器 ul 增加 ant-timeline-pending 类名,追加的末节点获得 ant-timeline-item-pending 类名,二者共同控制挂起节点的样式。
Timeline.Item 参数
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
color |
指定圆圈颜色 | string | blue, red, green |
blue |
源码中 getDefaultProps 明确将 color 默认值设为 'blue',并通过类名拼接 ${prefixCls}-item-head-${color} 将颜色应用到圆点头部节点上。
圆圈颜色的语义化使用
components/timeline/demo/color.md 给出了颜色使用的语义约定:
圆圈颜色,绿色用于已完成、成功状态,红色表示告警或错误状态,蓝色可表示正在进行或其他默认状态。
对应的示例代码为:
import { Timeline } from 'antd';
ReactDOM.render(
<Timeline>
<Timeline.Item color="green">创建服务现场 2015-09-01</Timeline.Item>
<Timeline.Item color="green">创建服务现场 2015-09-01</Timeline.Item>
<Timeline.Item color="red">
<p>初步排除网络异常1</p>
<p>初步排除网络异常2</p>
<p>初步排除网络异常3 2015-09-01</p>
</Timeline.Item>
<Timeline.Item>
<p>技术测试异常1</p>
<p>技术测试异常2</p>
<p>技术测试异常3 2015-09-01</p>
</Timeline.Item>
</Timeline>
, mountNode);
注意最后一个 Timeline.Item 未显式指定 color,会使用默认的蓝色。同时示例还展示了 Timeline.Item 的内容区可以放置多个 <p> 段落,说明节点内容完全支持任意合法的 React 元素组合。
在样式层面,style/components/timeline.less 中定义了三种颜色的具体呈现方式——圆点采用"白色实底 + 彩色描边"的设计:
&-head {
position: absolute;
width: 12px;
height: 12px;
background-color: #fff;
border-radius: 100px;
&-blue {
border: 2px solid @primary-color;
}
&-red {
border: 2px solid @error-color;
}
&-green {
border: 2px solid @success-color;
}
}
可以看到:蓝色对应主题色 @primary-color,红色对应错误色 @error-color,绿色对应成功色 @success-color。圆点为 12px 的白色圆形,配以 2px 彩色描边,通过 Less 变量接入主题体系,因此换肤时颜色会自动跟随主题变化。
幽灵节点(pending):表达"未完成"的时间轴
当时间轴记录仍在进行中时,可以在末尾追加一个"幽灵节点"。文档 components/timeline/demo/pending.md 说明了两种用法:
可以指定
pending={true}或者pending={一个 React 元素}。
最典型的场景是放置一个"查看更多"入口:
import { Timeline } from 'antd';
ReactDOM.render(
<Timeline pending={<a href="#">查看更多</a>}>
<Timeline.Item>创建服务现场 2015-09-01</Timeline.Item>
<Timeline.Item>初步排除网络异常 2015-09-01</Timeline.Item>
<Timeline.Item>技术测试异常 2015-09-01</Timeline.Item>
</Timeline>
, mountNode);
这里 pending 传入的是一个 <a> 链接元素,表示时间轴尚未结束、仍在记录过程中,用户点击"查看更多"可以加载更早的记录。
从源码可以确认其实现细节:挂起节点由 Timeline 内部自动创建(<TimelineItem pending={!!pending}>{pendingNode}</TimelineItem>),无需手动书写 <Timeline.Item>,且该节点自动获得 last 相关的末项样式处理逻辑。
在样式上,挂起节点与普通节点有明显差异:
&-pending &-tail {
display: none;
}
...
&&-pending &-item-last &-item-tail {
display: block;
}
挂起节点自身不绘制尾部连线,但容器处于 pending 状态时,最后一个普通节点(ant-timeline-item-last)的尾部连线会被重新显示(display: block),从而让竖线"延伸"到幽灵节点位置,形成视觉上连续未完成的观感。
样式细节:连线与末项的处理
style/components/timeline.less 还揭示了几个值得注意的布局细节:
- 尾部连线
ant-timeline-item-tail:绝对定位在left: 5px,使用 2px 实线border-left,颜色取自@timeline-color(即@border-color-split),自上而下贯穿每个节点; - 末项特殊处理:默认情况下最后一个节点
ant-timeline-item-last的尾部连线为虚线样式并被隐藏(display: none),其内容区保留min-height: 48px的占位; - 内容区排版:
ant-timeline-item-content设置padding: 0 0 10px 24px、font-size: 12px,并通过top: -3px微调与圆点的垂直对齐。
使用建议与扩展方向
综合以上文档与源码,可以归纳出 Timeline 的几条实战建议:
- 语义化配色:按"绿=成功/完成、红=告警/错误、蓝=进行中/默认"的约定分配节点颜色,让状态一目了然;
- 利用 pending 表达进行时:记录尚未结束的场景(如任务执行中、日志持续追加),使用
pending={<a href="#">查看更多</a>}既能传达"未完成"语义,又能提供交互入口; - 灵活组织节点内容:
Timeline.Item的内容区支持任意 React 元素,多行文本(多个<p>)、图标、链接等均可直接放置; - 关注末项视觉差异:默认最后一个节点不显示完整竖线,若需要竖线贯穿到底,可结合
pending的样式联动实现。
如需查看时间轴的完整组件 API 与使用说明,可继续阅读 components/timeline/index.md;想研究其视觉实现,可研读 style/components/timeline.less;组件核心逻辑则在 components/timeline/index.jsx 中,三个文件配合阅读即可完整掌握该组件的设计与实现。