Ant Design Timeline 时间轴组件入门:从基本用法到源码实现解析

原创2026-09-17 14:06:081,975 阅读
文章标签:前端UI组件设计系统

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 的几条实战建议:

  1. 语义化配色:按"绿=成功/完成、红=告警/错误、蓝=进行中/默认"的约定分配节点颜色,让状态一目了然;
  2. 利用 pending 表达进行时:记录尚未结束的场景(如任务执行中、日志持续追加),使用 pending={<a href="#">查看更多</a>} 既能传达"未完成"语义,又能提供交互入口;
  3. 灵活组织节点内容:Timeline.Item 的内容区支持任意 React 元素,多行文本(多个 <p>)、图标、链接等均可直接放置;
  4. 关注末项视觉差异:默认最后一个节点不显示完整竖线,若需要竖线贯穿到底,可结合 pending 的样式联动实现。

如需查看时间轴的完整组件 API 与使用说明,可继续阅读 components/timeline/index.md;想研究其视觉实现,可研读 style/components/timeline.less;组件核心逻辑则在 components/timeline/index.jsx 中,三个文件配合阅读即可完整掌握该组件的设计与实现。

登录后查看全文
ant-design