ant-design-blazor Timeline 自定义时间轴点(Dot)实战指南:用图标与任意元素打造个性化时间轴

原创2026-10-11 18:58:102,283 阅读
文章标签:UI组件前端

ant-design-blazor Timeline 自定义时间轴点(Dot)实战指南:用图标与任意元素打造个性化时间轴

导读

在 ant-design-blazor 的 Timeline(时间轴)组件中,每个节点默认渲染为一个 10px 的圆形圆点,仅能表达"存在"这一语义。本文聚焦官方示例"自定义时间轴点"(Custom),讲解如何通过 TimelineItem 的 Dot 参数,将节点替换为图标、图片或任意自定义元素,并结合 Color 参数、PendingDot 幽灵节点与 Mode 布局模式,在项目中实现信息密度更高、语义更丰富的业务时间轴。读完本文,你将掌握 Dot 的声明方式、底层渲染原理与样式适配细节,并能在自己的 Blazor 应用中直接复用。

一、核心概念:Dot 参数是什么

TimelineItem(时间轴节点)的 Dot 参数是 ant-design-blazor 为节点预留的"自定义时间轴点"入口,类型为 RenderFragment,即一段可渲染的 Blazor 标记。只要给 Dot 赋值,组件就会放弃默认的圆形圆点,改而渲染你提供的任何内容——可以是图标、头像、图片、徽标,甚至一段包含交互逻辑的复杂模板。

源码定义位于 TimelineItem.cs:

/// <summary>
/// The dot of the timeline item.
/// </summary>
[Parameter]
public RenderFragment Dot { get; set; }

从源码结构看,Dot 的渲染时机非常直接:在 Timeline.razor 中,节点头部容器内先判断 item.Dot != null,非空则直接输出该片段,否则保持为空(由 CSS 背景与边框绘制默认圆点):

<div class="@item._headClassMapper.Class" style="@item.HeadStyle">
    @if (item.Dot != null)
    {
        @item.Dot
    }
</div>

二、官方示例逐行解读:用 ClockCircle 图标替换圆点

官方 Custom 示例(Custom.razor)演示了最基本的自定义方式:把某一节点的圆点替换为时钟图标。完整代码如下:

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

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

2.1 声明 Dot 的推荐写法:RenderFragment + Template 包裹

示例中 dotTemplate 是一个 RenderFragment 字段,内部使用 <Template> 标签包裹图标内容。这是 Blazor 中声明可复用渲染片段的常见模式——@<Template>...</Template> 语法直接构造片段,字段在 @code 块中声明一次,即可被多个 TimelineItem 通过 Dot="dotTemplate" 引用。

若你只需要单个节点的点,也可以直接内联声明,效果等价:

<TimelineItem>
    <Dot>
        <Icon Type="@IconType.Outline.ClockCircle" Style="font-size: 16px;" />
    </Dot>
    Technical testing 2015-09-01
</TimelineItem>

2.2 图标来源:IconType.Outline.ClockCircle

示例中的 <Icon Type="@IconType.Outline.ClockCircle" /> 来自 ant-design-blazor 内置 Icon 组件。其图标类型常量定义在 IconType.cs,IconType.Outline.ClockCircle 对应的图标名称为 "clock-circle":

public static string ClockCircle => "clock-circle";

Outline 表示线性风格主题,与 Fill(实心)、TwoTone(双色)一同构成三类图标主题,分别对应 IconThemeType.Outline / Fill / TwoTone(见 IconThemeType.cs)。实际渲染时,IconStore.cs 会根据 iconName 与 iconTheme 的组合查找对应的 SVG 图标数据。图标自带的 Style="font-size: 16px;" 用于控制显示尺寸,保证与时间轴节点头部协调。

三、底层原理:从参数到 CSS 类的完整链路

自定义圆点不只是"换个内容"这么简单,它涉及三个层面的协同:

  1. 类名切换:在 TimelineItem.cs 的 SetClassMap() 中,当 Dot != null 时,节点头部会额外追加 ant-timeline-item-head-custom 类:
var headPrefix = "ant-timeline-item-head";
_headClassMapper.Add(headPrefix)
    .GetIf(() => $"{headPrefix}-{Color.AsT0.ToString().ToLowerInvariant()}", () => Color.IsT0)
    .If($"{headPrefix}-custom", () => Dot != null);

同时,颜色类(如 ant-timeline-item-head-red)只在 Color 为预设枚举值时生效;若 Color 传入了自定义字符串,则改走 HeadStyle 内联样式路径:

private void TryUpdateCustomColor()
{
    HeadStyle = Color.IsT1 ? $"border-color:{Color.AsT1}" : "";
}
  1. CSS 布局重排:默认圆点的尺寸固定为 10px×10px,而自定义元素尺寸不定。因此 index.less 中 ant-timeline-item-head-custom 专门重置了定位与盒模型:
&-head-custom {
  position: absolute;
  top: 5.5px;
  left: 5px;
  width: auto;
  height: auto;
  margin-top: 0;
  padding: 3px 1px;
  line-height: 1;
  text-align: center;
  border: 0;
  border-radius: 0;
  transform: translate(-50%, -50%);
}

关键点:width/height: auto 让容器随自定义内容自适应,translate(-50%, -50%) 以内容中心对齐时间轴线。这意味着你可以放心放入比 10px 更大的元素(如图标、头像),组件会自动完成居中对齐。

  1. 内容输出:如第一节所述,Timeline.razor 在头部容器内直接输出 Dot 片段。整条渲染链路由 Timeline 父组件统一编排:子组件注册进 _items 列表、OnAfterRender 阶段调用 SetItems() 计算显示顺序与位置(见 Timeline.razor.cs)。

四、结合 Color 参数:自定义点 + 颜色语义

官方示例中自定义节点还同时设置了 Color="TimelineDotColor.Red"。预设颜色枚举定义在 TimelineDotColor.cs:

public enum TimelineDotColor
{
    Red,
    Blue,
    Green,
    Gray
}

颜色语义约定(源自官方 Color 示例说明):

  • 绿色 Green:已完成、成功状态;
  • 红色 Red:告警或错误状态;
  • 蓝色 Blue:进行中或其他默认状态(也是 Color 参数的默认值,见 TimelineItem.cs);
  • 灰色 Gray:未完成或失效状态。

Color 还接受任意 CSS 色值字符串,例如 Color="@("#f50")",此时会通过 border-color 内联样式生效,并配合 ant-timeline-item-head-custom 将自定义圆点边框染成目标颜色。因此,你可以自由组合"自定义图标 + 状态颜色",例如用红色时钟图标表达"超时未处理"的节点。

五、进阶组合:幽灵节点、交替布局与自定义点

Dot 的灵活性与 Timeline 的其他参数组合后,能覆盖更丰富的业务场景:

5.1 PendingDot:自定义幽灵节点圆点

Timeline 的 Pending 参数用于在末尾追加一个"幽灵节点"(如"待办"占位),其默认圆点是加载图标;PendingDot 参数(类型同样为 RenderFragment)可替换该幽灵节点的圆点。源码中 Pending 的默认点由 Timeline.razor.cs 提供:

private static readonly RenderFragment _loadingDot = builder =>
{
    builder.OpenComponent<Icon>(0);
    builder.AddAttribute(1, nameof(Icon.Type), "loading");
    builder.CloseComponent();
};

设置 PendingDot 后,幽灵节点将按你的自定义内容渲染,例如:

<Timeline Pending="Recording..." PendingDot="pendingDot">
    <!-- 若干 TimelineItem -->
</Timeline>

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

5.2 Mode 交替布局下的自定义点

在 Mode="TimelineMode.Alternate" 下(见 Alternate.razor),节点在左右两侧交替排列,Dot 模板同样适用——官方示例甚至为多个节点复用了同一个 dotTemplate:

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

TimelineMode 枚举定义在 TimelineMode.cs,可取 Left(默认)、Right、Alternate。需要留意的是,Alternate 模式下 index.less 会让 head-custom 的 left: 50% 并微调 margin-left,自定义点依然按内容中心对齐时间轴线,无需额外适配。

六、API 速查

TimelineItem 核心参数(官方 API 文档见 index.zh-CN.md):

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

Timeline 相关参数:

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

七、测试佐证:自定义圆点的渲染契约

仓库的组件测试 TimelineTests.razor 对圆点渲染给出了精确的契约验证:

  • 默认节点渲染为 <div class="ant-timeline-item-head ant-timeline-item-head-blue"></div>(无内容、无 custom 类);
  • 传入预设颜色时渲染 ant-timeline-item-head-red / ant-timeline-item-head-green 类;
  • 传入自定义色值(如 "#fff"、"green")时,头部不再携带颜色类,而是输出内联样式 style="border-color:#fff"。

这些断言印证了本文第二节所述的类名切换与内联样式两条路径:自定义 Dot 与自定义 Color 互不冲突,可安全组合使用。

结语

TimelineItem.Dot 是 ant-design-blazor 时间轴组件中成本最低、收益最高的自定义入口:只需一段 RenderFragment,就能把呆板的圆形节点升级为图标、头像或任意业务元素,且组件的定位对齐、颜色语义与布局模式(左、右、交替)全部自动适配。官方示例本身虽只有十余行代码,但背后是类名切换、CSS 重排、父组件编排三层的完整支撑——理解了这条链路,你就能在项目里按需扩展出属于自己的时间轴视觉语言。

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