ant-design-blazor Timeline(时间轴)组件实战指南:用法、参数与源码原理

原创2026-10-11 18:58:161,970 阅读
文章标签:前端UI组件设计系统WebAssembly

ant-design-blazor Timeline(时间轴)组件实战指南:用法、参数与源码原理

时间轴(Timeline)是数据展示类组件中最直观的"叙事工具"之一,ant-design-blazor 组件库以 C#/Razor 完整移植了 Ant Design 的时间轴组件,用于垂直展示按时间排列的信息流。本文以仓库内 Timeline 组件的官方中文文档为主体,结合 Timeline 源码、样式实现 与 单元测试 逐项展开,帮助你掌握 Timeline 的全部参数、7 类典型场景写法,并理解其内部渲染与排序机制。

一、组件是什么与何时使用

Timeline 组件在页面上呈现为一条垂直时间轴,节点(时间点)沿轴线依次排布,内容与时间点一一对应。官方文档将其定位为"垂直展示的时间流信息",适用场景非常明确:

  • 当有一系列信息需按时间排列时,可正序和倒序展示;
  • 当需要有一条时间轴对多个节点进行视觉上的串联时。

典型应用包括订单物流轨迹、项目里程碑、版本发布记录、操作审计日志等。在 ant-design-blazor 中,它由 Timeline(时间轴容器)与 TimelineItem(时间轴节点)两个组件协作构成,容器通过 CascadingValue 向所有子节点广播自身实例,子节点则在初始化/销毁时向父组件登记或注销,从而由父组件统一计算每个节点的最终渲染位置。

二、基础用法:最简单的时间轴

先看官方文档配套的最基础示例(完整源码见 demo/Basic.razor):

<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>

不传任何参数时,时间轴点位于内容左侧,节点颜色默认取 TimelineDotColor.Blue。从 Timeline.razor 的模板可以看出,每个节点最终渲染为 <li class="ant-timeline-item">,内部依次是:可选标签区 ant-timeline-item-label、轴线 ant-timeline-item-tail、节点圆点 ant-timeline-item-head、内容区 ant-timeline-item-content;整个容器则是 <ul class="ant-timeline">。

这条渲染链路在 TimelineTests.razor 的 Renders_basic_timeline 测试中被完整断言,例如第二个节点会同时带有 ant-timeline-item-last(末节点)与 ant-timeline-item-head-red(红色圆点)两个类。

三、完整 API 参考

以下参数表来自官方中文文档 doc/index.zh-CN.md,并补充了源码层面的默认值与类型细节。

3.1 Timeline(时间轴容器)

参数 说明 类型 默认值
Pending 指定最后一个幽灵节点是否存在或内容 RenderFragment -
PendingDot 当最后一个幽灵节点存在时,指定其时间图点 RenderFragment -
Reverse 节点排序(正序/倒序) boolean -
Mode 通过设置 mode 可以改变时间轴和内容的相对位置,可选 alternate、left、right string -

结合 Timeline.razor.cs 需要补充的几点实现细节:

  • Mode 与 Reverse 的 setter 中都会置位 _waitingItemUpdate,随后在 OnAfterRender 阶段触发 SetItems() 重新计算节点布局;
  • Pending 在源码中的真实类型是 OneOf<string, RenderFragment>,也就是说既可以直接传入一段字符串文本,也可以传入任意 RenderFragment 内容;官方文档表写为 RenderFragment 是字符串形态的一种简化表达;
  • 当未显式提供 PendingDot 时,幽灵节点默认使用一个 Icon Type="loading" 的加载图标(_loadingDot),这也是官方 demo 中"Recording..."场景自带转圈动画的原因。

Mode 的取值对应枚举 TimelineMode.cs:

public enum TimelineMode
{
    Left,
    Right,
    Alternate
}

3.2 TimelineItem(时间轴节点)

参数 说明 类型 默认值
Color 指定圆圈颜色 blue、red、green、gray,或自定义的色值 string -
Dot 自定义时间轴点 string -
Position 自定义节点位置 left、right string -
Label 设置标签 RenderFragment -

同样结合 TimelineItem.cs 做源码级澄清:

  • Color 的真实类型是 OneOf<TimelineDotColor, string>,默认值为 TimelineDotColor.Blue(枚举定义见 TimelineDotColor.cs,取值为 Red、Blue、Green、Gray 四项)。传入预设枚举时组件渲染 ant-timeline-item-head-xxx 颜色类;传入自定义字符串色值时,则在 TryUpdateCustomColor() 中直接生成 style="border-color: 色值" 的内联样式覆盖圆点边框颜色;
  • Dot 在源码中类型为 RenderFragment(文档表写为 string 不准确),用于完全替换默认圆点;
  • Position 在源码中实际是内部属性,由父组件 UpdateChildren() 依据 Mode 自动计算并写入,一般不需要使用者手动指定;API 表中将其列出是为了说明节点可落位于左右两侧的语义;
  • Label 在源码中为 string 类型,用于在节点左侧单独展示时间等附加信息。

四、三种 Mode:内容与时间轴的相对位置

Mode 是 Timeline 最核心的布局参数,官方提供了 left、right、alternate 三种取值,分别对应 demo/Right.razor 与 demo/Alternate.razor 的场景。

4.1 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>

4.2 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
        doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore
        veritatis et quasi architecto beatae vitae dicta sunt explicabo.
    </TimelineItem>
    <TimelineItem Color="TimelineDotColor.Red">Network problems being solved 2015-09-01</TimelineItem>
    <TimelineItem>Create a services site 2015-09-01</TimelineItem>
    <TimelineItem Dot="dotTemplate">Technical testing 2015-09-01</TimelineItem>
</Timeline>

源码原理:位置计算集中在 Timeline.razor.cs 的 UpdateChildren() 方法中——Left 模式全部落在左侧,Right 模式全部落在右侧,Alternate 模式下按节点下标奇偶轮流分配:偶数下标(含 0)去左侧、奇数下标去右侧。同时容器类名也会随之变化:Right 模式追加 ant-timeline-right,Alternate 模式追加 ant-timeline-alternate(见 SetClassMap())。

对应测试 Renders_timeline_with_alternate_mode 使用 [InlineData] 逐一验证了三种模式下的容器类名与每个节点的 ant-timeline-item-left/right 类,见 TimelineTests.razor。

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

颜色是时间轴传达状态信息的主要手段。官方 demo/Color.razor 的说明给出了明确的颜色语义约定:

  • 绿色(TimelineDotColor.Green):用于已完成、成功状态;
  • 红色(TimelineDotColor.Red):表示告警或错误状态;
  • 蓝色(TimelineDotColor.Blue):表示正在进行或其他默认状态;
  • 灰色(TimelineDotColor.Gray):表示未完成或失效状态;
  • 另外还支持直接传入自定义色值(如 "#f50"、"green" 等任意 CSS 颜色字符串)。
<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>

源码与样式依据:预设颜色的最终视觉呈现来自 style/index.less 中对 ant-timeline-item-head-blue/red/green/gray 的规则定义,四种颜色分别映射到设计令牌 @primary-color、@error-color、@success-color、@disabled-color,因此会随主题(亮色/暗色/紧凑)自动联动。自定义色值的实现逻辑在 TimelineItem.cs 的 TryUpdateCustomColor(),它只注入 border-color,圆点内部颜色仍保持主题背景;Renders_timeline_with_custom_color 测试用 #fff 与 green 两个用例验证了这一内联样式的输出。

六、自定义时间轴点 Dot

当默认圆点无法满足视觉需求时,可通过 Dot 传入任意 RenderFragment 替换节点圆点,常见做法是嵌入图标(官方 demo demo/Custom.razor 与 demo/Alternate.razor 均使用了时钟图标):

<Timeline>
    <TimelineItem>Create a services site 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>;
}

渲染细节:从 Timeline.razor 的模板可见,只要 item.Dot != null,圆点区就渲染传入的 Dot 内容,并且 TimelineItem.cs 的 SetClassMap() 会在此时追加 ant-timeline-item-head-custom 类。样式层面对该类的处理是去掉默认圆点的固定尺寸与边框,并让自定义内容围绕轴线中心对齐(见 style/index.less 中 &-head-custom 规则),因此图标不会被裁切。

七、Label 标签:单独展示时间

默认情况下时间与内容放在同一个节点里,而 Label 参数可以把时间单独提取到节点左侧展示。官方 demo/Label.razor 用一个 RadioGroup 动态切换三种 Mode,展示标签在不同布局下的落位:

<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;
}

源码原理:Timeline 内部维护 _hasLabel 标志,只要任意子节点设置了 Label,SetClassMap() 就会给容器追加 ant-timeline-label 类;渲染模板中每个节点会优先输出 <div class="ant-timeline-item-label"> 标签区块(见 Timeline.razor)。样式层面,style/index.less 的 .ant-timeline-label 规则让标签固定在轴的一侧(默认右对齐,右侧模式时左对齐),使时间列与内容列视觉分离。注意 Label 仅当至少一个节点声明时才启用整条时间轴的标签布局。

八、Pending 幽灵节点与 Reverse 倒序

当任务仍在进行、记录尚未结束时,可以在时间轴末尾追加一个"幽灵节点"(pending 节点)表示当前进行中的时间点;Reverse 则控制整体排序。官方 demo/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;
    }
}

源码原理:Pending 的 setter 中会创建一个带 ant-timeline-item-pending 类的内部 TimelineItem(_pendingItem),把传入内容写入 ChildContent、把 PendingDot(缺省为 loading 图标)写入 Dot。真正的排序逻辑在 SetItems()(Timeline.razor.cs):

  • Reverse == false:正常节点序列 + 幽灵节点,幽灵节点排最后;
  • Reverse == true:幽灵节点 + 倒序后的正常节点,幽灵节点排最前(此时最后一条实线变为 pending 虚线)。

对应的样式在 style/index.less:pending 节点所在位置的轴线由实线变为 2px dotted 虚线,且容器会追加 ant-timeline-pending 或 ant-timeline-reverse 类来配合呈现;pending 节点的头部同时使用 @font-size-sm 与透明背景,营造"进行中"的轻盈感。

九、样式体系与主题联动

Timeline 的视觉完全由 Less 样式驱动,样式入口是 components/timeline/style/entry.less,核心规则集中在 style/index.less,并单独引入 rtl.less 支持 RTL 布局(容器类名含 ant-timeline-rtl)。几个值得注意的设计点:

  • 轴线 ant-timeline-item-tail 默认 border-left 实线,宽度与颜色由变量 @timeline-width、@timeline-color 控制;
  • 末节点 ant-timeline-item-last 会隐藏尾部轴线并给内容区留出最小高度(min-height: 48px);
  • alternate、right、label 三种模式统一将 tail/head 定位到 50% 中轴线,再由 left/right 节点类分别向两侧展开内容,所有宽度都基于 calc(50% - …) 计算;
  • 由于圆点颜色直接引用主题令牌(@primary-color 等),暗色主题、紧凑主题下无需改动组件代码即可自动适配。

十、单元测试:行为即契约

仓库在 tests/AntDesign.Tests/Timeline/TimelineTests.razor 为 Timeline 建立了完整的渲染契约测试,覆盖了本文涉及的全部核心行为:

  • Renders_basic_timeline:基础结构、默认蓝色圆点、末节点类;
  • Renders_timeline_with_right_mode:ant-timeline-right 容器类与节点 ant-timeline-item-right 类;
  • Renders_timeline_with_alternate_mode:通过 [InlineData] 矩阵验证三种 Mode 下首末节点的左右位置;
  • Renders_timeline_with_label:ant-timeline-label 容器类与 ant-timeline-item-label 区块输出;
  • Renders_timeline_with_color / Renders_timeline_with_custom_color:预设枚举映射到 ant-timeline-item-head-green/red 类、自定义色值映射到 border-color 内联样式。

这些测试同时可以作为你自行扩展 Timeline 场景(如 pending 节点 + label 组合)时的断言模板,也是理解组件内部 CascadingValue 父子协作模式的绝佳入口。

结语

Timeline 在 ant-design-blazor 中是一个"小而精"的组件:API 仅有 4 个容器参数与 4 个节点参数,却通过 Mode、Reverse、Pending 的组合覆盖了正序/倒序、左右/交替布局、进行中状态等绝大多数时间流场景,并且与主题令牌、RTL 方向深度联动。理解 UpdateChildren 的位置计算逻辑 与 index.less 的布局规则,即可在业务中游刃有余地定制属于自己的时间轴叙事。

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