Element UI Timeline 时间线组件：从文档到源码的完整解析

Element UI Timeline 时间线组件从文档到源码的完整解析【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element在展示业务流程、订单进度、动态日志等带时间属性的信息时Element UI 提供了 Timeline时间线组件以垂直列表的形式按升序或降序可视化多个活动节点。本文以官方文档examples/docs/en-US/timeline.md为主体完整覆盖其基础用法、自定义节点、自定义时间戳以及全部 API 表格并结合packages/timeline下的组件源码、packages/theme-chalk样式变量与test/unit/specs/timeline.spec.js测试用例解释每个属性的底层渲染机制帮助你在实际业务中正确且深入地使用该组件。组件定位Timeline 与 Steps 的区别文档开篇即点明 Timeline 的核心特征它可以按升序或降序拆分为多个活动节点时间戳timestamp是它区别于其他组件的关键特性并特别提醒注意它与 Steps步骤条组件的差异。简单说Steps 强调流程走到第几步的状态推进而 Timeline 强调的是某时刻发生了什么的事件序列展示两者适用场景不同。基础用法升序与降序切换文档Basic usage一节的完整示例如下通过reverse属性在升序ascending与降序descending之间切换节点展示顺序div classblock div classradio Order: el-radio-group v-modelreverse el-radio :labeltruedescending/el-radio el-radio :labelfalseascending/el-radio /el-radio-group /div el-timeline :reversereverse el-timeline-item v-for(activity, index) in activities :keyindex :timestampactivity.timestamp {{activity.content}} /el-timeline-item /el-timeline /div script export default { data() { return { reverse: true, activities: [{ content: Event start, timestamp: 2018-04-15 }, { content: Approved, timestamp: 2018-04-13 }, { content: Success, timestamp: 2018-04-11 }] }; } }; /scriptreverse的底层实现值得注意。查看 packages/timeline/src/main.vueElTimeline的 render 函数在reverse为 true 时直接对整个默认插槽的 vnode 数组执行slots.reverse()即反转的是子节点的渲染顺序而不是 CSS 视觉倒置render() { const reverse this.reverse; const classes { el-timeline: true, is-reverse: reverse }; let slots this.$slots.default || []; if (reverse) { slots slots.reverse(); } return (ul class{ classes } { slots } /ul); }这一实现的直接推论是使用reverse时数据源应按最早的事件在前的升序排列组件负责把最新的节点渲染在视觉上最靠上的位置。test/unit/specs/timeline.spec.js 中的reverse用例验证了这一点——reverse: true时 DOM 中第index个内容等于数据数组的倒数第index项并且reverse切换为 false 后节点顺序会随之恢复说明该属性是响应式的。ElTimeline还会通过provide()将自身实例以timeline为键向子组件注入供ElTimelineItem通过inject: [timeline]获取这是两个组件之间的关联通道见 packages/timeline/src/item.vue 第 46 行。组件的安装入口在 packages/timeline/index.js遵循 Element UI 标准的Vue.component(Timeline.name, Timeline)注册方式。自定义节点大小、颜色与图标文档Custom node一节指出节点node的大小、颜色和图标均可自定义div classblock el-timeline el-timeline-item v-for(activity, index) in activities :keyindex :iconactivity.icon :typeactivity.type :coloractivity.color :sizeactivity.size :timestampactivity.timestamp {{activity.content}} /el-timeline-item /el-timeline /div script export default { data() { return { activities: [{ content: Custom icon, timestamp: 2018-04-12 20:46, size: large, type: primary, icon: el-icon-more }, { content: Custom color, timestamp: 2018-04-03 20:46, color: #0bbd87 }, { content: Custom size, timestamp: 2018-04-03 20:46, size: large }, { content: Default node, timestamp: 2018-04-03 20:46 }] }; } }; /script从 packages/timeline/src/item.vue 的模板可以看到这些属性各自的落点size拼成节点类名el-timeline-item__node--normal或el-timeline-item__node--large。对应的尺寸定义在 packages/theme-chalk/src/timeline-item.scss 中而具体的像素值来自全局样式变量 packages/theme-chalk/src/common/var.scss$--timeline-node-size-normal: 12px、$--timeline-node-size-large: 14px。type同样映射为el-timeline-item__node--primary/success/warning/danger/info类名SCSS 中分别绑定到$--color-primary等主题色变量因此主题换肤时会随主题色变化。color不走类名而是直接以行内样式:style{ backgroundColor: color }写入节点因此会覆盖type产生的背景色。测试用例color断言color#f00时节点style.backgroundColor为rgb(255, 0, 0)印证了这一实现路径。icon节点内渲染一个i元素并附加图标类名例如el-icon-more图标默认白色color: $--color-white字号为$--font-size-small。未设置任何自定义属性时节点背景色为$--timeline-node-color即$--border-color-light也就是文档示例中Default node的默认灰边颜色。测试文件type、size、icon三个用例分别断言了对应 class 的存在可以佐证上述类名映射的准确性。自定义时间戳位置placementtop文档Custom timestamp一节说明当节点内容较高例如内嵌卡片时可以把时间戳放到内容上方div classblock el-timeline el-timeline-item timestamp2018/4/12 placementtop el-card h4Update Github template/h4 pTom committed 2018/4/12 20:46/p /el-card /el-timeline-item el-timeline-item timestamp2018/4/3 placementtop el-card h4Update Github template/h4 pTom committed 2018/4/3 20:46/p /el-card /el-timeline-item el-timeline-item timestamp2018/4/2 placementtop el-card h4Update Github template/h4 pTom committed 2018/4/2 20:46/p /el-card /el-timeline-item /el-timeline /div实现上ElTimelineItem的模板根据placement的值把时间戳渲染在内容el-timeline-item__content之前或之后placementtop时先输出带is-top类的时间戳placementbottom默认值时后输出带is-bottom类的时间戳。两者在样式上的差别是is-top使用margin-bottom: 8px; padding-top: 4pxis-bottom使用margin-top: 8px。test/unit/specs/timeline.spec.js 的placement用例断言了placementtop时时间戳元素带有is-top类名。hide-timestamp则完全隐藏时间戳测试用例hide-timestamp验证了三条节点、其中一条设置hide-timestamp后页面中时间戳元素数量为 2。自定义节点插槽dot slot除内置节点外文档的 Slot 表格还提供了一个dot插槽用于完全自定义节点。从 packages/timeline/src/item.vue 的模板逻辑看两者是互斥的当存在$slots.dot时内置的el-timeline-item__node不再渲染v-if!$slots.dot取而代之的是包裹插槽内容的el-timeline-item__dot容器该容器使用绝对定位与 flex 居中。典型用法如下基于源码模板结构整理el-timeline el-timeline-item p2018-04-12/p template #dot el-button typeprimary sizesmall iconel-icon-plusCustom/el-button /template /el-timeline-item /el-timelineAPI 参考el-timeline Attributes参数说明类型可选值默认值reverse是否节点时间戳显示升序/降序默认为降序boolean—falseel-timeline-item Attributes参数说明类型可选值默认值timestamp时间戳string——hide-timestamp是否隐藏时间戳boolean—falseplacement时间戳位置stringtop / bottombottomtype节点类型stringprimary / success / warning / danger / info—color节点背景色stringhsl / hsv / hex / rgb—size节点大小stringnormal / largenormalicon节点图标类名string——el-timeline-item Slotname说明—时间线自定义内容dot自定义节点上述取值与类型定义与 packages/timeline/src/main.vue 和 packages/timeline/src/item.vue 中的 props 声明一一对应placement默认bottom、size默认normal、hideTimestamp默认false、reverse默认false。TypeScript 类型声明文件 types/timeline.d.ts 与 types/timeline-item.d.ts 将placement、type、size收敛为top | bottom、primary | success | warning | danger | info、normal | large等联合类型在 Vue TypeScript 项目中可获得取值提示。DOM 结构与样式细节理解 DOM 结构有助于排查布局问题。从 packages/timeline/src/item.vue 与样式文件看每个时间线项由四个部分构成.el-timeline-item__tail竖向连接线绝对定位于left: 4px高度 100%以border-left: 2px solid $--timeline-node-color绘制packages/theme-chalk/src/timeline.scss 通过最后一个.el-timeline-item的__tail设为display: none来截断尾节点的连线。.el-timeline-item__node内置圆形节点border-radius: 50%normal定位left: -1px、large定位left: -2px尺寸分别取自 12px / 14px 变量。.el-timeline-item__dot自定义节点插槽容器仅在提供dot插槽时渲染。.el-timeline-item__wrapper内容容器padding-left: 28px; top: -3px内部按时间戳位置、默认插槽内容依次排布。样式入口统一在packages/theme-chalk/src/下文档站演示用的示例样式见 examples/demo-styles/timeline.scss并在 examples/demo-styles/index.scss 中引入。小结Timeline 是 Element UI 中实现较紧凑的展示型组件ElTimeline只负责容器与升/降序对插槽 vnode 数组的reverse()节点、时间戳与插槽的差异全部由ElTimelineItem的 props 与模板条件渲染驱动。掌握reverse的数据排序要求、color行内样式优先于type类名、dot插槽与内置节点互斥这三点基本可以覆盖时间线在业务中常见的定制需求完整的属性边界还可通过 test/unit/specs/timeline.spec.js 中的断言逐项对照验证。【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考