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'
})
export class YourComponent {
  // 基础数据示例
  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>
<div style="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 #customTemplate let-item="data">
  <div style="border-left: 4px solid; padding: 12px 8px; margin: 4px 0; background: #fff; box-shadow: 0 2px 4px rgba(0,0,0,0.1);"
       [style.border-color]="item.color">
    <div style="font-weight: bold; font-size: 14px;">{{ item.title }}</div>
    <div style="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-axis direction="horizontal" [mode]="'alternative'">
  <d-time-axis-item direction="horizontal"
                    dotColor="var(--devui-success)"
                    text="Start"
                    time="2021/3/13">
  </d-time-axis-item>
  <d-time-axis-item direction="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'	-	单独设置该节点的内容位置

五、实用技巧与最佳实践

1. 数据转换：在实际项目中，你的数据可能来自后端API。确保在传递给组件前，将其转换为 TimeAxisItem[] 格式。
2. 响应式设计：在移动端，考虑使用 direction="vertical" 以获得更好的显示效果。可以通过媒体查询或监听屏幕宽度来动态改变 direction 属性。
3. 性能优化：当时间节点数量非常多（如超过50个）时，考虑进行分页或虚拟滚动。虽然文档未直接提及，但可以结合 *ngFor 和分页逻辑来分割 data 数组。
4. 与DevUI其他组件协作：如示例所示，时间轴内容可以无缝集成 d-tag 等其它DevUI组件，保持设计语言统一。

总结

DevUI 时间轴组件通过其分层级的自定义能力，完美平衡了“开箱即用”的便利性与“灵活扩展”的开放性。无论是简单的操作步骤提示，还是复杂的项目里程碑展示，你都可以通过组合 direction、mode 和自定义模板来构建出最适合当前场景的时间线视图。

参考文档

MateChat：https://gitcode.com/DevCloudFE/MateChat

MateChat官网：https://matechat.gitcode.com

DevUI官网：https://devui.design/home