DevUI Time Axis 时间轴组件：从基础到进阶的完整指南
DevUI Time Axis 时间轴组件：从基础到进阶的完整指南
DevUI 时间轴 (Time Axis) 是一个用于可视化时间序列事件的强大 Angular 组件。它源自华为内部业务的多年沉淀，严格遵循 DevUI “高效、开放、可信、乐趣”的设计价值观，为项目中展示发展历程、操作流程、版本发布等时间线信息提供了高度灵活且开箱即用的解决方案。本文将基于官方文档，详细阐述其使用方法、配置项及代码示例。
一、组件概述与核心概念
DevUI 时间轴组件 (<d-time-axis>) 通过时间节点 (<d-time-axis-item>) 来串联一系列事件。其核心设计围绕方向 (direction)、模式 (mode)和内容自定义展开，允许你轻松创建水平和垂直时间轴，并控制时间点和内容的显示位置。
核心特性包括：
- 双向布局：支持水平 (
horizontal) 和垂直 (vertical) 布局。 - 灵活模式：支持常规（两侧内容）和单边（
top,bottom,left,right）模式。 - 深度自定义：可自定义时间点样式、内容模板（支持
ng-template）和纯 HTML。 - 细粒度控制：可单独设置每个时间节点的位置，或单独使用时间节点项。
二、基础用法与数据接口
1. 数据接口 ([data])
时间轴接收一个TimeAxisItem对象数组作为数据源。这是最基础的驱动方式。
// 在组件TypeScript文件中定义数据import{Component}from'@angular/core';import{TimeAxisItem}from'devui';@Component({selector:'app-your-component',templateUrl:'./your-component.component.html'})exportclassYourComponent{// 基础数据示例basicData:TimeAxisItem[]=[{time:'2021/07/28',text:'Download',status:'primary'},{time:'2021/07/29',text:'Check',status:'success'},{time:'2021/07/30',text:'Build',status:'warning'},{time:'2021/07/31',text:'Deploy',status:'danger'},{time:'2021/08/01',text:'End',status:'default'}];}2. 最简单的使用
在模板中，只需将数据绑定到[data]属性。
<!-- 在组件HTML模板中使用 --><d-time-axis[data]="basicData"></d-time-axis>三、核心功能详解与代码示例
1. 设置方向 ([direction])
通过direction属性控制时间轴的排列方向。
<h4>水平时间轴</h4><d-time-axis[direction]="'horizontal'"[data]="basicData"></d-time-axis><h4>垂直时间轴</h4><divstyle="width:200px"><!-- 为垂直布局设置宽度 --><d-time-axis[direction]="'vertical'"[data]="basicData"></d-time-axis></div>2. 单边模式 ([mode])
通过mode属性可以将内容固定在一侧显示，形成更简洁的视图。
| 模式值 | 适用方向 | 内容显示侧 |
|---|---|---|
top | horizontal | 时间线上方 |
bottom | horizontal | 时间线下方 |
left | vertical | 时间线左侧 |
right | vertical | 时间线右侧 |
<h4>底部模式 (Bottom)</h4><d-time-axis[data]="basicData"[mode]="'bottom'"></d-time-axis><h4>右侧模式 (Right)</h4><d-time-axis[direction]="'vertical'"[data]="basicData"[mode]="'right'"></d-time-axis>3. 自定义内容（模板与HTML）
这是时间轴最强大的功能之一，允许你完全控制每个节点的展示内容。
a) 使用HTML字符串自定义
直接在数据对象的content属性中传入HTML字符串。
// 在TypeScript数据中定义timeAxisHtmlData:TimeAxisItem[]=[{time:'2017/07/25',text:'Start',content:`<div style="color:#526ecc; padding:8px; border-left: 2px solid #526ecc;"> <b>some events in 2017/07/25</b><br/> Here are the details... </div>`},// ... 其他数据项];b) 使用 Angular 模板自定义 ([contentTemplate])
通过传递ng-template引用实现类型安全的复杂内容渲染，这是推荐的方式。
<!-- 在组件HTML模板中 --><d-time-axis[data]="templateData"[contentTemplate]="customTemplate"[mode]="'alternative'"></d-time-axis><!-- 定义自定义内容模板 --><ng-template#customTemplatelet-item="data"><divstyle="border-left:4px solid;padding:12px 8px;margin:4px 0;background:#fff;box-shadow:0 2px 4pxrgba(0,0,0,0.1);"[style.border-color]="item.color"><divstyle="font-weight:bold;font-size:14px;">{{ item.title }}</div><divstyle="color:#666;margin-top:4px;">发布日期：{{ item.date }}</div><div>版本状态：<d-tag[tag]="item.status"[customColor]="item.color"></d-tag></div></div></ng-template>// 对应的TypeScript数据templateData=[{title:'第四季度交付版本1.0',date:'2019/11/01',status:'已发布',color:'#50d4ab',position:'bottom'// 可用于模板内逻辑判断},// ... 其他数据项];4. 时间节点位置与方向自定义
- 时间位置 (
timePosition)：当direction为vertical时，可指定时间为left或bottom。 - 替代模式 (
alternative)：在mode设置为alternative时，会交替显示内容的位置（如左/右，上/下），使布局更紧凑美观。
<h4>垂直时间轴，时间在左侧</h4><d-time-axis[direction]="'vertical'"[data]="basicData"[mode]="'alternative'"timePosition="left"></d-time-axis>5. 时间节点单独使用
你可以不使用[data]输入属性，而是以嵌套组件的方式声明每个节点，从而实现最大程度的个性化控制。
<d-time-axisdirection="horizontal"[mode]="'alternative'"><d-time-axis-itemdirection="horizontal"dotColor="var(--devui-success)"text="Start"time="2021/3/13"></d-time-axis-item><d-time-axis-itemdirection="horizontal"dotColor="var(--devui-danger)"text="Check"time="2021/4/14"></d-time-axis-item><!-- 可以在此处为单个item插入自定义内容 --><d-time-axis-item...><div>自定义嵌入的内容</div></d-time-axis-item></d-time-axis>四、配置属性与事件总结
为了方便查阅，以下表格列出了d-time-axis和d-time-axis-item的主要输入属性：
<d-time-axis>组件属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
[data] | TimeAxisItem[] | - | 时间轴数据源，与<d-time-axis-item>二选一 |
[direction] | 'horizontal'｜'vertical' | 'horizontal' | 时间轴方向 |
[mode] | 'normal'｜'top'｜'bottom'｜'left'｜'right'｜'alternative' | 'normal' | 时间轴展示模式 |
[contentTemplate] | TemplateRef | - | 自定义内容区域的模板 |
timePosition | 'left'｜'bottom' | 'left' | 垂直方向专用，时间文本位置 |
<d-time-axis-item>组件属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
[time] | string | - | 节点时间文本 |
[text] | string | - | 节点主要描述文本 |
[dotColor] | string | 'var(--devui-line)' | 时间节点圆点的颜色 |
[position] | 'top'｜'bottom'｜'left'｜'right' | - | 单独设置该节点的内容位置 |
五、实用技巧与最佳实践
- 数据转换：在实际项目中，你的数据可能来自后端API。确保在传递给组件前，将其转换为
TimeAxisItem[]格式。 - 响应式设计：在移动端，考虑使用
direction="vertical"以获得更好的显示效果。可以通过媒体查询或监听屏幕宽度来动态改变direction属性。 - 性能优化：当时间节点数量非常多（如超过50个）时，考虑进行分页或虚拟滚动。虽然文档未直接提及，但可以结合
*ngFor和分页逻辑来分割data数组。 - 与DevUI其他组件协作：如示例所示，时间轴内容可以无缝集成
d-tag等其它DevUI组件，保持设计语言统一。
总结
DevUI 时间轴组件通过其分层级的自定义能力，完美平衡了“开箱即用”的便利性与“灵活扩展”的开放性。无论是简单的操作步骤提示，还是复杂的项目里程碑展示，你都可以通过组合direction、mode和自定义模板来构建出最适合当前场景的时间线视图。
参考文档
MateChat：https://gitcode.com/DevCloudFE/MateChat
MateChat官网：https://matechat.gitcode.com
DevUI官网：https://devui.design/home