ant-design-blazor Timeline 自定义时间轴点(Dot)实战指南:用图标与任意元素打造个性化时间轴
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 类的完整链路
自定义圆点不只是"换个内容"这么简单,它涉及三个层面的协同:
- 类名切换:在 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}" : "";
}
- 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 更大的元素(如图标、头像),组件会自动完成居中对齐。
- 内容输出:如第一节所述,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 重排、父组件编排三层的完整支撑——理解了这条链路,你就能在项目里按需扩展出属于自己的时间轴视觉语言。