ant-design-vue Timeline 时间轴组件完全指南API、源码实现与实战示例【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-vue导读Timeline时间轴是 ant-design-vue 中用于垂直展示时间流信息的数据展示组件适合呈现按时间排列的事件序列如服务排查记录、订单流转、项目里程碑。本文以 components/timeline/index.zh-CN.md 为骨架结合 Timeline.tsx、TimelineItem.tsx 等源码与 demo 目录下的真实示例系统讲解 Timeline 的全部 API、四种布局模式left / alternate / right / 标签模式、幽灵节点、倒序排列、自定义时间轴点等核心能力让你在 Vue 3 项目中能直接上手并理解其底层渲染逻辑。一、组件定位与何时使用Timeline 的核心价值在于用一根垂直轴线把按时间顺序排列的信息视觉串联起来。官方文档给出两条使用准则当有一系列信息需按时间排列时可正序和倒序展示需要有一条时间轴进行视觉上的串联时使用。典型业务场景包括服务上线/故障处理时间线、订单状态流转记录、项目迭代日志、操作审计记录等。它支持从left、alternate交替、right三种整体布局中切换并允许在每个节点上自定义颜色、图标、标签与位置。最简单的用法如下与 demo/basic.vue 一致a-timeline a-timeline-item创建服务现场 2015-09-01/a-timeline-item a-timeline-item初步排除网络异常 2015-09-01/a-timeline-item a-timeline-item技术测试异常 2015-09-01/a-timeline-item a-timeline-item网络异常正在修复 2015-09-01/a-timeline-item /a-timeline渲染结果每个节点由左侧圆点head、连接线tail与右侧内容区content组成最后一个节点不再绘制连接线。二、Timeline 组件 API 详解Timeline 主组件参数参数说明类型默认值mode通过设置mode改变时间轴和内容的相对位置left|alternate|rightleftpending指定最后一个幽灵节点是否存在或内容boolean | string | slotfalsependingDot当最后一个幽灵节点存在时指定其时间图点string | slotLoadingOutlined /reverse节点排序booleanfalse源码印证在 Timeline.tsx 中这些 props 被定义为export const timelineProps () ({ prefixCls: String, pending: PropTypes.any, // 幽灵节点内容布尔值只控制显隐 pendingDot: PropTypes.any, // 幽灵节点的时间轴点 reverse: booleanType(), // 是否倒序 mode: PropTypes.oneOf(tuple(left, alternate, right, )), });并通过initDefaultProps设置默认值reverse: false、mode: 空字符串等价于默认的left布局。组件名为ATimeline注册时同时注册Timeline.Item子组件见 index.tsx。Timeline.Item 节点参数参数说明类型默认值版本color指定圆圈颜色blue, red, green或自定义的色值stringblue-dot自定义时间轴点string | slot--label设置标签string | slot-3.0position自定义节点位置left|right--源码印证TimelineItem.tsx 中export const timelineItemProps () ({ prefixCls: String, color: String, dot: PropTypes.any, pending: booleanType(), position: PropTypes.oneOf(tuple(left, right, )).def(), label: PropTypes.any, });默认color: blue。节点内部 DOM 结构依次为item-label仅 label 存在时渲染、item-tail连接线、item-head圆点/自定义点、item-content内容区对应 TimelineItem.tsx 的渲染函数。三、四种布局模式mode 与 position 的配合1. 左侧布局默认modeleft所有节点的时间轴点都在内容左侧这是默认行为。Timeline的getPositionCls函数Timeline.tsx实现了位置类名的完整决策逻辑const getPositionCls (ele, idx: number) { const eleProps ele.props || {}; if (props.mode alternate) { if (eleProps.position right) return ${prefixCls.value}-item-right; if (eleProps.position left) return ${prefixCls.value}-item-left; return idx % 2 0 ? ${prefixCls.value}-item-left : ${prefixCls.value}-item-right; } if (props.mode left) return ${prefixCls.value}-item-left; if (props.mode right) return ${prefixCls.value}-item-right; if (eleProps.position right) return ${prefixCls.value}-item-right; return ; };2. 交替布局modealternate内容在时间轴两侧轮流出现对应 demo/alternate.vuea-timeline modealternate a-timeline-itemCreate a services site 2015-09-01/a-timeline-item a-timeline-item colorgreenSolve initial network problems 2015-09-01/a-timeline-item a-timeline-item template #dotClockCircleOutlined stylefont-size: 16px //template Sed ut perspiciatis unde omnis iste natus error sit voluptatem... /a-timeline-item a-timeline-item colorredNetwork problems being solved 2015-09-01/a-timeline-item /a-timeline从源码可见交替模式的放置规则偶数下标idx % 2 0放左侧奇数下标放右侧若节点显式设置了positionleft或positionright则优先遵循节点自身的位置声明。3. 右侧布局moderight时间轴点移到内容右侧对应 demo/right.vuea-timeline moderight a-timeline-itemCreate a services site 2015-09-01/a-timeline-item a-timeline-item template #dotclock-circle-outlined stylefont-size: 16px //template Technical testing 2015-09-01 /a-timeline-item /a-timelinemoderight会让所有节点都应用-item-right类布局样式在 style/index.tsx 中通过insetInlineStart: calc(100% - ...)将 tail、head、head-custom 定位到右端。4. 标签模式label 属性触发自 3.0 版本起Timeline.Item支持label属性用于在时间轴另一侧单独展示时间对应 demo/label.vuea-radio-group v-model:valuemode stylemargin-bottom: 20px a-radio valueleftLeft/a-radio a-radio valuerightRight/a-radio a-radio valuealternateAlternate/a-radio /a-radio-group a-timeline :modemode a-timeline-item label2015-09-01Create a services/a-timeline-item a-timeline-item label2015-09-01 09:12:11Solve initial network problems/a-timeline-item a-timeline-itemTechnical testing/a-timeline-item a-timeline-item template #labelstrong stylecolor: red2015-09-01 09:12:11/strong/template Network problems being solved /a-timeline-item /a-timeline关键点label既支持普通字符串也支持#label具名插槽可插入自定义渲染如红色加粗的时间文案。从 Timeline.tsx 的源码可以看到只要任意节点带有label根节点就会追加-label样式类进入标签布局模式const hasLabelItem timeLineItems.some( item !!(item.props?.label || item.children?.label), );标签模式下mode决定标签与内容的相对方位left/alternate时标签在左、内容在右右侧节点-item-right则反转——标签移到右半区、内容移到左半区样式细节见 style/index.tsx。四、幽灵节点pending与倒序reverse幽灵节点展示进行中状态当任务仍在记录过程中可以用幽灵节点标记当前进度对应 demo/pending.vuea-timeline pendingRecording... :reversereverse a-timeline-itemCreate a services site 2015-09-01/a-timeline-item a-timeline-itemSolve initial network problems 2015-09-01/a-timeline-item a-timeline-itemTechnical testing 2015-09-01/a-timeline-item /a-timeline a-button typeprimary stylemargin-top: 16px clickhandleClickToggle Reverse/a-button结合 Timeline.tsx 的实现pending 的三种取值含义如下pending为真值true渲染幽灵节点但内容为空pending为字符串字符串作为幽灵节点的内容展示如Recording...pending为VNode / slot可用于完全定制节点内容。当pending为真时内部会构造一个带pending{true}标记的TimelineItemconst pendingItem pending ? ( TimelineItem pending{!!pending} dot{pendingDot || LoadingOutlined /} {pendingNode} /TimelineItem ) : null;pendingDot用于定制幽灵节点的时间轴点默认值是LoadingOutlined /加载图标这也解释了为何幽灵节点默认带加载中的视觉暗示。幽灵节点的连接线渲染为虚线dotted样式见 style/index.tsx。reverse 倒序排列reverse为true时节点倒序显示最新事件置顶适合最近发生在前的诉求。源码通过children.reverse()实现Timeline.tsxconst timeLineItems reverse ? children.reverse() : children;倒序时样式上会做对应调整-reverse类下最后一个节点的 tail 隐藏而幽灵节点pending的 tail 以虚线重新出现见 style/index.tsx保证倒序后视觉上仍然连贯。最后一个节点last的自动识别Timeline会自动为最后一个节点追加-item-last类Timeline.tsxconst itemsCount timeLineItems.length; const lastCls ${prefixCls.value}-item-last; const items timeLineItems.map((ele, idx) { const pendingClass idx itemsCount - 2 ? lastCls : ; const readyClass idx itemsCount - 1 ? lastCls : ; return cloneVNode(ele, { class: classNames([ !reverse !!pending ? pendingClass : readyClass, getPositionCls(ele, idx), ]), }); });未倒序且有 pending倒数第二个节点获得-item-last因为最后一个位置被幽灵节点占据其他情况最后一个节点获得-item-last。-item-last的样式会隐藏该节点的 tail 连接线避免尾部出现悬空的线头style/index.tsx。五、节点样式定制color 与 dotcolor圆点颜色color支持语义色名与任意自定义色值内置色名blue默认表示进行中/默认状态、green已完成/成功、red告警/错误、gray禁用/不可用任意合法 CSS 色值如#00CCFF。源码实现TimelineItem.tsx只有匹配blue|red|green|gray时才使用语义类名否则按自定义色值走内联样式const customColor computed(() /blue|red|green|gray/.test(props.color || ) ? undefined : props.color || blue, ); const dotClassName computed(() ({ [${prefixCls.value}-item-head]: true, [${prefixCls.value}-item-head-${props.color || blue}]: !customColor.value, })); // 渲染时style{{ borderColor: customColor.value, color: customColor.value }}对应演示见 demo/color.vue其中还演示了自定义色值#00CCFF与#dot插槽SmileOutlined的组合用法。内置色名映射到主题 tokenblue → colorPrimary、red → colorError、green → colorSuccess、gray → colorTextDisabledstyle/index.tsx。dot自定义时间轴点dot可以是字符串或插槽通常传入图标实现更丰富的视觉表达对应 demo/custom.vuea-timeline-item colorred template #dotclock-circle-outlined stylefont-size: 16px //template Technical testing 2015-09-01 /a-timeline-item当存在自定义 dot 时head 会追加-item-head-custom类样式将圆形默认点替换为自适应宽高的内容容器并居中定位style/index.tsx因此图标可以自由缩放而不会撑破布局。六、样式体系与主题定制Timeline 采用 ant-design-vue 的 CSS-in-JS 样式方案通过genComponentStyleHook(Timeline, ...)注册style/index.tsx并定义了如下设计 tokenToken默认值含义timeLineItemPaddingBottomtoken.padding * 1.25节点底部间距timeLineItemHeadSize10时间轴点尺寸timeLineItemCustomHeadPaddingVerticaltoken.paddingXXS自定义轴点垂直内边距timeLineItemTailWidthtoken.lineWidthBold连接线宽度timeLineHeadBorderWidthwireframe 模式为lineWidthBold否则lineWidth * 3圆点边框宽度组件的 class 前缀通过useConfigInject(timeline, props)注入因此可通过ConfigProvider的prefixCls或主题 token 统一定制同时支持-rtl类实现 RTL 方向适配style/index.tsx。所有根节点样式类均带hashId保证样式隔离。七、类型定义与测试保障Timeline 导出完整的 TypeScript 类型TimelineProps、TimelineItemPropsindex.tsx其中TimelineProps[mode]可直接用于约束变量类型见 demo/label.vue 中的refTimelineProps[mode](left)。测试方面tests/index.test.js 通过mountTest对Timeline及其Item子组件执行挂载与卸载冒烟测试tests/demo.test.js 则对全部 demo 进行渲染快照校验确保各布局、pending、reverse 场景的输出稳定。八、实战小结综合以上内容使用 Timeline 时的核心决策路径可归纳为选整体布局默认left事件较多且想均衡两侧空间用alternate轴点靠右用right需要单独突出时间信息用label3.0标记状态用colorgreen/red/gray/自定义色值区分完成、告警、禁用状态展示进行中设置pendingtrue / 字符串 / VNode并配合pendingDot定制幽灵轴点调整阅读顺序reverse为true时倒序展示常用于最新动态置顶场景个性表达用dot插槽图标与position按节点微调位置。所有能力均有对应的 demo 示例、源码实现Timeline.tsx、TimelineItem.tsx与样式定义style/index.tsx可供深入研读与直接复用。【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考