ant-design-blazor Timeline 时间轴组件完全指南:API 参数、模式布局与源码实现剖析

原创2026-10-11 19:03:001,636 阅读
文章标签:UI组件前端

ant-design-blazor Timeline 时间轴组件完全指南:API 参数、模式布局与源码实现剖析

Timeline(时间轴)是 ant-design-blazor 提供的数据展示组件,用于以垂直时间线形式串联一系列按时间排列的信息节点。本文将围绕官方文档 Timeline 组件文档 展开,完整讲解其 Pending、Reverse、Mode 等核心参数与 TimelineItem 节点的配色、自定义轴点、标签能力,并结合组件源码、官方演示样例与单元测试,帮助你掌握从基本用法到定制化布局的完整实战方案。

组件定位与适用场景

根据文档定义,Timeline 用于「垂直展示的时间流信息」,核心价值在于用一条纵向时间轴把零散的时间事件在视觉上串联起来。文档明确给出两条适用判断标准:

  • 当有一系列信息需要按时间排列(可正序、可倒序)时;
  • 当需要有一条时间轴对多个事件进行视觉串联时。

典型的落地场景包括:项目里程碑记录、订单物流轨迹、操作审计日志、版本发布历史等。组件在仓库中归属于数据展示(Data Display)分类,其核心实现位于 components/timeline 目录,由 Timeline(时间轴容器)与 TimelineItem(时间轴节点)两个组件配合使用。

快速上手:最小可运行示例

Timeline 的使用方式非常直观:外层声明 <Timeline>,内部用 <TimelineItem> 声明每一个节点,节点内容就是普通的 Markup。参考官方 Basic 演示样例:

<div>
    <Timeline>
        <TimelineItem>Create a services site 2015-09-01</TimelineItem>
        <TimelineItem Color="TimelineDotColor.Red" >Solve initial network problems 2015-09-01</TimelineItem>
        <TimelineItem>Technical testing 2015-09-01</TimelineItem>
        <TimelineItem>Network problems being solved 2015-09-01</TimelineItem>
    </Timeline>
</div>

渲染结果为:纵向轴线左侧依次排列圆点与内容,最后一个节点自动追加 ant-timeline-item-last 类,尾线不再向下延伸。单元测试 TimelineTests.razor 验证了上述输出结构:每个 <li> 由 ant-timeline-item-tail(尾线)、ant-timeline-item-head(轴点)与 ant-timeline-item-content(内容)三个 div 构成,且未指定颜色时轴点默认携带 ant-timeline-item-head-blue 类。

API 参数详解

官方文档的 API 部分将参数分为 Timeline 容器与 TimelineItem 节点两组,下面结合源码 Timeline.razor.cs 与 TimelineItem.razor.cs 逐项展开。

Timeline 容器参数

参数 说明 类型 默认值
Pending 指定最后一个幽灵节点是否存在或其内容 OneOf<string, RenderFragment> -
PendingDot 当幽灵节点存在时,指定其时间轴点 RenderFragment -
Reverse 节点排序(正序/倒序) bool false
Mode 时间轴与内容的相对位置,可选 alternate、left、right TimelineMode? -

几个值得注意的实现细节:

  • Pending 的类型是 OneOf<string, RenderFragment>:即既可以直接传字符串文本,也可以传一段渲染片段。源码在赋值时会创建一个带有 ant-timeline-item-pending 类的 TimelineItem,并把传入的字符串或片段写入其内容;若未指定 PendingDot,则自动使用一个 Icon Type="loading" 的加载图标作为默认轴点(见 Timeline.razor.cs)。
  • Mode 的枚举定义:TimelineMode 在 TimelineMode.cs 中定义为 Left、Right、Alternate 三个成员。注意 Mode 参数本身可空(TimelineMode?),不设置时内容统一在右侧;容器 ClassMapper 会根据模式追加 ant-timeline-right 或 ant-timeline-alternate 样式类(Timeline.razor.cs)。
  • Reverse 与 Pending 的交互:SetItems() 方法中,当 Reverse 为 true 时,幽灵节点被排在最前面,其余节点倒序;为 false 时幽灵节点排在末尾(Timeline.razor.cs)。

TimelineItem 节点参数

参数 说明 类型 默认值
Color 指定圆圈颜色:blue、red、green、gray,或自定义色值 OneOf<TimelineDotColor, string> TimelineDotColor.Blue
Dot 自定义时间轴点(可为图标等任意元素) RenderFragment -
Position 自定义节点位置,可选 left、right TimelineMode?(内部属性) -
Label 设置标签(通常用于单独展示时间) string -

源码层面的补充说明:

  • Color 的枚举语义:TimelineDotColor 定义于 TimelineDotColor.cs,包含 Red、Blue、Green、Gray 四项。当传入枚举值时,轴点类名映射为 ant-timeline-item-head-{color};当传入自定义字符串(如 "#f50")时,组件通过 TryUpdateCustomColor() 直接生成内联样式 border-color:{value}(见 TimelineItem.razor.cs)。
  • Label 的联动:只要任一节点设置了 Label,容器就会追加 ant-timeline-label 类,从而触发「时间轴居中、内容左右分列」的标签布局(见 Timeline.razor.cs)。
  • Position 的赋值规则:Position 是内部属性,由容器统一计算:Left 模式下所有节点靠左,Right 模式下全部靠右,Alternate 模式下偶数位靠左、奇数位靠右(Timeline.razor.cs),并以 ant-timeline-item-left / ant-timeline-item-right 类落到每个 <li> 上。

圆圈颜色:预设语义与自定义色值

官方 Color 演示 给出了四种预设颜色的使用语义:

  • 绿色(Green):用于已完成、成功状态;
  • 红色(Red):表示告警或错误状态;
  • 蓝色(Blue):表示正在进行或其他默认状态;
  • 灰色(Gray):表示未完成或失效状态。

预设颜色在样式表 index.less 中分别映射到主题变量:蓝色对应 @primary-color、红色对应 @error-color、绿色对应 @success-color、灰色对应 @disabled-color,因此会随主题切换自动适配。

除预设值外还支持任意自定义色值。参考 Color.razor:

<Timeline>
    <TimelineItem Color="TimelineDotColor.Green">Create a services site 2015-09-01</TimelineItem>
    <TimelineItem Color="TimelineDotColor.Red">
        <p>Solve initial network problems 1</p>
        <p>Solve initial network problems 2</p>
        <p>Solve initial network problems 3 2015-09-01</p>
    </TimelineItem>
    <TimelineItem Color="TimelineDotColor.Gray">
        <p>Technical testing 1</p>
        <p>Technical testing 2</p>
        <p>Technical testing 3 2015-09-01</p>
    </TimelineItem>
    <TimelineItem Color="@("#f50")">
        <p>Technical testing 1</p>
        <p>Technical testing 2</p>
        <p>Technical testing 3 2015-09-01</p>
    </TimelineItem>
</Timeline>

测试 Renders_timeline_with_custom_color 验证了自定义色值的真实输出:节点 <div> 上不再有 ant-timeline-item-head-* 颜色类,而是出现 style="border-color:#fff" 之类的内联样式。同时也可以看到,节点内容支持多个 <p> 段落,TimelineItem 的 ChildContent 本质上是任意 RenderFragment。

布局模式:Left / Right / Alternate

右侧时间轴点(Right)

官方 Right 演示 展示时间轴点位于内容右侧的形态:

<Timeline Mode="TimelineMode.Right">
    <TimelineItem>Create a services site 2015-09-01</TimelineItem>
    <TimelineItem>Solve initial network problems 2015-09-01</TimelineItem>
    <TimelineItem Dot="dotTemplate" Color="TimelineDotColor.Red">
        Technical testing 2015-09-01
    </TimelineItem>
    <TimelineItem Color="TimelineDotColor.Red">Network problems being solved 2015-09-01</TimelineItem>
</Timeline>

容器渲染为 <ul class="ant-timeline ant-timeline-right">,所有 <li> 均携带 ant-timeline-item-right 类,内容列在轴线左侧、右对齐。这一结构在测试 Renders_timeline_with_right_mode 中得到了逐标签验证。

交替展现(Alternate)

官方 Alternate 演示 描述为「内容在时间轴两侧轮流出现」,即奇偶节点分别落在轴线左右两侧:

<Timeline Mode="TimelineMode.Alternate">
    <TimelineItem>Create a services site 2015-09-01</TimelineItem>
    <TimelineItem Color="TimelineDotColor.Green">Solve initial network problems 2015-09-01</TimelineItem>
    <TimelineItem Dot="dotTemplate">
        Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium ...
    </TimelineItem>
    <TimelineItem Color="TimelineDotColor.Red">Network problems being solved 2015-09-01</TimelineItem>
</Timeline>

其轮流规则由 UpdateChildren() 中的 i % 2 == 0 ? Left : Right 逻辑决定,测试 Renders_timeline_with_alternate_mode 用 InlineData 覆盖了三种模式:Left 模式下两个节点均为 left,Right 模式下均为 right,Alternate 模式下分别为 left、right,与实现完全一致。

幽灵节点(Pending)与节点排序(Reverse)

官方 Reverse 演示 说明:当任务仍在进行、事件记录尚未结束时,可用「幽灵节点」表示当前时间节点;Pending 为真值时展示该节点,且可用自定义元素定制节点内容;PendingDot 用于定制其轴点。Reverse 用于控制节点排序,false 时正序排列,true 时倒序排列。

参考演示代码 Reverse.razor:

<Timeline Pending="pending" Reverse=@bReverse>
    <TimelineItem>Create a services site 2015-09-01</TimelineItem>
    <TimelineItem>Solve initial network problems 2015-09-01</TimelineItem>
    <TimelineItem>Technical testing 2015-09-01</TimelineItem>
</Timeline>
<Button Type="ButtonType.Primary" Style="margin-top: 16px " OnClick="HandleClick">
    Toggle Reverse
</Button>

@code{
    private bool bReverse { get; set; } = false;
    RenderFragment pending = @<Template>
        Recording...
    </Template>;
    void HandleClick()
    {
        bReverse = !bReverse;
    }
}

需要理解的关键行为:

  • 幽灵节点的轴点默认是 loading 图标,视觉上表达「正在发生」,符合「任务状态正在发生、还在记录过程中」的语义;
  • 幽灵节点在倒序模式下会出现在列表顶部而非底部,这是 SetItems() 中 Reverse ? pitems.Concat(...) : ...Concat(pitems) 的结果(Timeline.razor.cs);
  • 样式层面,ant-timeline-pending 类会令末尾节点的尾线变成 2px dotted 虚线(index.less),与普通实线区分;
  • 容器 ClassMapper 在 Reverse 为真时追加 ant-timeline-reverse 类,此时幽灵节点的尾线改为向下延长(index.less)。

该示例同时展示了 Pending 的 RenderFragment 用法,以及 Reverse 通过按钮动态切换的实际场景——这正是文档所说「正序和倒序」需求的典型交互形态。

自定义时间轴点(Dot)

官方 Custom 演示 指出轴点「可以设置为图标或其他自定义元素」。通过 Dot 参数传入任意 RenderFragment 即可,配合 @<Template> 语法定义复用片段:

<Timeline>
    <TimelineItem>Create a services site 2015-09-01</TimelineItem>
    <TimelineItem>Solve initial network problems 2015-09-01</TimelineItem>
    <TimelineItem Dot="dotTemplate" Color="TimelineDotColor.Red">
        Technical testing 2015-09-01
    </TimelineItem>
    <TimelineItem>Network problems being solved 2015-09-01</TimelineItem>
</Timeline>

@code {
    RenderFragment dotTemplate =
        @<Template>
            <Icon Type="@IconType.Outline.ClockCircle" Style="font-size: 16px;" />
        </Template>;
}

实现上,只要 Dot != null,轴点头部类就追加 ant-timeline-item-head-custom(见 TimelineItem.razor.cs),样式表会去掉默认圆点的边框与尺寸限制,改为自适应内容(index.less),从而实现时钟图标、头像、自定义图形等任意元素作为轴点。

标签(Label):单独展示时间

官方 Label 演示 说明「使用 label 标签单独展示时间」,适用于把时间信息从正文中抽离、以独立列呈现的场景:

<RadioGroup @bind-Value="@mode" Style="margin-bottom:20px">
    <Radio Value="TimelineMode.Left">Left</Radio>
    <Radio Value="TimelineMode.Right">Right</Radio>
    <Radio Value="TimelineMode.Alternate">Alternate</Radio>
</RadioGroup>
<Timeline Mode="@mode">
    <TimelineItem Label="2015-09-01">Create a services</TimelineItem>
    <TimelineItem Label="2015-09-01 09:12:11">Solve initial network problems</TimelineItem>
    <TimelineItem>Technical testing</TimelineItem>
    <TimelineItem Label="2015-09-01 09:12:11">Network problems being solved</TimelineItem>
</Timeline>

@code{
    private TimelineMode mode = TimelineMode.Left;
}

该示例还演示了 Mode 与 RadioGroup 双向绑定联动:切换 Left/Right/Alternate 时,时间轴布局实时变化。标签的渲染细节:

  • 每个携带 Label 的节点,其 <li> 内部会多出一个 ant-timeline-item-label 的 div(见 Timeline.razor);
  • 容器自动追加 ant-timeline-label 类,将轴线与轴点居中,标签列与内容列分布在轴线两侧——即使 Mode 为 Left 或 Right,标签布局仍然生效(测试 Renders_timeline_with_label 证明三种模式下容器类均为 ant-timeline-label,而各节点分别携带 left/right 定位类);
  • 需要注意 Label 的当前类型为 string,文档表格中标注为 RenderFragment,实际以字符串文本传入即可。

渲染原理与实现机制

父子组件通过级联参数协作

Timeline 通过 <CascadingValue Value="this" IsFixed> 将自身暴露给所有子节点(Timeline.razor),TimelineItem 通过 [CascadingParameter] private Timeline ParentTimeline 接收,并在 OnInitialized 时调用 AddItem(this) 注册自己、在 Dispose 时调用 RemoveItem(this) 注销自己(TimelineItem.razor.cs)。这种设计让容器在首帧渲染后即可拿到全部节点列表,统一计算位置与排序。

两阶段渲染与位置计算

容器渲染分两步:ChildContent 先渲染出 <li> 骨架,随后在 OnAfterRender 中通过 SetItems() 基于注册的 _items 列表生成最终展示顺序,再触发 StateHasChanged 完成二次渲染(Timeline.razor.cs)。Mode、Reverse、Pending 等参数的 setter 均会置位 _waitingItemUpdate 标志,保证属性变化后重新计算布局。

样式类的统一管理

组件使用 ClassMapper 统一维护 CSS 类:容器类的追加规则见 SetClassMap,节点类的追加规则见 SetClassMap。同时组件继承 AntDomComponentBase,因此天然支持 Class、Style、Id、RTL(追加 ant-timeline-rtl 类)等通用属性;RTL 方向的尾线、轴点、内容偏移在 rtl.less 中做了完整的镜像处理。

小结

Timeline 组件用少量参数覆盖了时间流展示的绝大多数诉求:Color 表达状态语义、Dot 支持任意自定义轴点、Mode 控制轴线与内容的相对位置、Label 独立呈现时间信息、Pending + Reverse 应对「进行中 + 倒序」场景。其实现上「容器统一计算 + 子节点级联注册」的协作模式,与 ClassMapper 的样式管理方式,也为阅读 components/timeline 目录下的其他组件提供了可借鉴的范本。若需进一步验证组件行为,可参考单元测试 TimelineTests.razor 中的 Markup 断言,并结合样式源文件 index.less 理解布局细节。

登录后查看全文
ant-design-blazor