时间轴视图

插件简介

plugin-timeline 是一个时间轴区块插件，用于按时间维度展示多条数据记录。它适合展示项目节点、事件轨迹、建设过程、历史变更等需要按时间顺序呈现的业务数据。

当前版本支持以下能力：

支持竖向和横向两种展示方向
支持左侧、右侧、交替、上方、下方等展示模式
支持标题、简介、时间、节点、标题图片等字段映射
支持使用字典颜色作为节点颜色
支持使用附件图片作为节点图片
支持开始时间、结束时间双时间字段展示
支持点击节点后打开记录详情弹窗
支持配置轴线颜色、轴线宽度、节点大小、节点间距、标题间距、时间间距
支持结合数据范围和默认排序控制最终展示结果

使用前准备

在配置时间轴区块前，建议先准备好对应的数据表和字段。字段不一定要全部具备，但字段越完整，展示效果越好。

推荐准备以下字段：

标题字段：用于显示时间轴节点标题，例如“大事记名称”“里程碑名称”“节点标题”
简介字段：用于显示节点摘要说明，例如“事件说明”“建设内容”“阶段描述”
开始时间字段：用于显示开始时间
结束时间字段：用于显示结束时间
节点字段：用于控制节点本身的展示样式
标题图片字段：用于显示标题旁边的图片

字段准备建议：

如果只需要显示一个时间点，可以只准备一个时间字段并将它映射为时间展示字段
如果需要展示一个时间区间，建议分别准备开始时间和结束时间
如果希望节点显示不同颜色，建议将 节点字段 配置为字典字段
如果希望节点显示为图片，建议将 节点字段 配置为附件字段
如果希望标题右侧带一张展示图，建议将 标题图片字段 配置为附件字段

版本依赖要求：

@nocobase/client: 2.x
@nocobase/server: 2.x
@nocobase/test: 2.x

快速上手

下面用最短路径说明如何快速配置一个可用的时间轴区块。

时间轴区块效果示例：

竖向展示示例：

1. 添加时间轴区块

在目标页面中添加区块后，选择：

区块名称：Time line
中文名称：时间轴

该区块面向多条记录数据进行展示，会按当前数据源查询结果渲染时间轴内容。

点击 创建区块 后，可以在数据区块列表中看到时间轴入口：

2. 选择数据表

将时间轴区块绑定到你要展示的数据表，例如：

项目大事记
工程节点
里程碑记录
历史变更记录

建议优先确认数据表中至少有标题和时间相关字段，这样可以先得到一个基础可读的时间轴。

3. 配置字段映射

选择完 数据表 后，会弹出 字段映射。

建议的最小配置为：

标题字段
简介字段
开始时间字段 或 结束时间字段

如果还需要更丰富的展示效果，可以继续配置：

标题图片字段
节点字段
时间格式

字段映射示例：

4. 设置方向与模式

完成字段映射后，继续设置：

方向
模式

常见组合建议：

需要传统项目过程展示时，使用 竖向 + 左侧 或 竖向 + 交替
需要更强阶段推进感时，使用 横向 + 上方 或 横向 + 交替

5. 调整外观

如果默认样式已经满足需求，可以不调整。

如果需要更贴近当前页面风格，可以按需调整：

轴线颜色
轴线宽度
节点大小
节点间距
标题间距
时间间距

6. 验证展示效果

配置完成后，建议重点检查以下内容：

是否已经按预期显示标题和简介
时间格式是否正确
节点是按颜色显示还是按图片显示
横向或纵向布局是否符合预期
点击节点后是否会打开记录详情
数据范围和默认排序是否符合预期

横向时间轴效果示例：

竖向时间轴效果示例：

配置详解

时间轴配置区域示例：

字段映射

字段映射用于告诉时间轴区块，页面上的每一部分内容应该读取哪个字段。

标题字段

用途：

显示每个节点的主标题

推荐选择：

文本类标题字段
能代表这条记录主题的字段

展示效果：

节点内容区会优先显示这个字段作为标题

标题图片字段

用途：

在标题内容区域旁边显示一张图片

推荐选择：

附件字段

展示效果：

如果字段里有图片，区块会读取图片并展示在内容区域中

注意：

当前实现基于附件字段读取图片
会读取该字段中的首张图片作为展示图

简介字段

用途：

显示节点的摘要说明

推荐选择：

多行文本字段
用于描述事件内容的字段

展示效果：

时间轴中会显示节点简介
简介内容较长时，会以摘要形式展示

节点字段

用途：

控制节点本身显示为什么样式

推荐选择：

字典字段
附件字段

展示效果：

如果选择的是字典字段，节点会按字典项颜色显示
如果选择的是附件字段，节点会显示为图片节点

注意：

字典字段时，节点颜色来自匹配字典项的 color
附件字段时，节点展示为图片，不再只是纯色圆点

开始时间字段

用途：

显示开始时间

推荐选择：

日期字段
日期时间字段
创建时间、更新时间等时间类型字段

展示效果：

如果设置了开始时间字段，会显示开始时间

结束时间字段

用途：

显示结束时间

推荐选择：

日期字段
日期时间字段

展示效果：

如果设置了结束时间字段，会显示结束时间

时间格式

用途：

控制时间的显示格式

默认值：

YYYY-MM-DD

展示效果：

所有时间都会按该格式输出

使用建议：

如果业务只关心日期，保留默认格式即可
如果业务需要显示具体时分秒，可以改成更详细的时间格式

双时间字段显示规则

当同时配置了开始时间字段和结束时间字段时：

时间轴会优先按双时间展示
会分别展示开始时间和结束时间

如果只配置了其中一个时间字段：

则只显示已有的那个时间值

方向

方向用于控制时间轴整体是纵向展示还是横向展示。

可选值：

竖向
横向

竖向

适用场景：

项目过程记录
历史事件追踪
传统的时间轴阅读方式

展示效果：

节点沿纵向从上到下排列

横向

适用场景：

阶段推进展示
适合强调时间推进过程的页面

展示效果：

节点沿横向排列
内容会围绕横向轴线分布

注意：

横向时间轴是插件自定义布局
它不是直接复用 Ant Design 的横向时间轴能力

模式

模式用于控制节点内容相对于轴线的位置，且会随着方向不同而变化。

竖向模式

可选值：

左侧
右侧
交替

展示效果：

左侧：内容集中在轴线左侧
右侧：内容集中在轴线右侧
交替：内容左右交替分布

横向模式

可选值：

上方
下方
交替

展示效果：

上方：内容集中在横向轴线上方
下方：内容集中在横向轴线下方
交替：内容上下交替分布

注意：

横向 交替 模式下，节点内容会按上下交替排列
当前实现会自动统一横向上下区域的共享高度，避免不同节点内容长短不一致时造成轴线错位

外观

外观配置用于调整时间轴的视觉样式。

轴线颜色

用途：

控制时间轴线条颜色

展示效果：

影响整条时间轴主线颜色
当节点未使用字典颜色时，也会作为默认节点颜色来源

轴线宽度

用途：

控制轴线粗细

展示效果：

数值越大，轴线越粗

节点大小

用途：

控制节点圆点或节点图片尺寸

展示效果：

数值越大，节点越明显

节点间距

用途：

调整节点相对轴线的位置偏移

展示效果：

可以微调节点与内容区的视觉关系

注意：

仅设置节点偏移时，不适用于节点图片

标题间距

用途：

调整标题区域与轴线的上下距离

展示效果：

可以微调标题离轴线的远近，让布局更紧凑或更舒展

时间间距

用途：

调整时间区域与轴线的上下距离

展示效果：

可以微调时间文字与轴线的视觉距离

恢复默认

用途：

一键恢复默认外观参数

默认外观参数如下：

{
  color: '#1890ff',
  lineWidth: 2,
  nodeSize: 12,
  nodePadding: -4,
  titlePadding: -7,
  timePadding: -6,
}

数据范围

数据范围 用于控制时间轴最终加载哪些记录。

使用建议：

如果只想展示当前项目的数据，可以在这里限制查询范围
如果只想展示某一类状态的数据，也可以结合数据范围做过滤

展示效果：

时间轴只会渲染数据范围内的记录

默认排序

默认排序 用于控制时间轴记录的先后顺序。

使用建议：

如果希望时间轴按时间从早到晚展示，建议按开始时间升序排序
如果希望最新事件优先展示，建议按时间降序排序

展示效果：

最终节点顺序会按排序结果渲染

注意：

时间轴本身不会替你自动决定业务排序逻辑
实际阅读顺序建议通过默认排序明确控制

点击节点弹窗

时间轴区块默认注册了节点点击事件。

事件名：

itemClick

当前内置流程：

popupSettings

默认行为：

点击节点时，通过 openView 打开当前记录的详情弹窗

展示效果：

用户点击节点后，可以直接查看该记录的详情

注意：

弹窗打开时会根据当前记录主键生成 filterByTk
默认关闭了路由跳转式导航，目的是保证再次点击时仍能正确触发弹窗流程

注意事项

横向时间轴是插件自定义布局，不是直接复用 Ant Design 的横向时间轴实现
标题图片字段 当前基于附件字段读取图片
节点字段 为字典字段时，节点颜色来自字典项颜色
节点字段 为附件字段时，节点会直接显示为图片节点
如果区块尚未配置数据源，配置态下会使用内置假数据进行预览
如果横向时间轴内容过多，区块会出现横向滚动；区块高度不足时会出现纵向滚动
标题间距 和 时间间距 主要用于微调轴线附近的视觉偏移
默认排序 建议明确按时间字段配置，避免时间线阅读顺序不符合预期
标题图片字段 默认支持附件类字段接口，其他字段接口需要额外注册

// client/plugin.tsx  multipleEntryModesAttachment为想要注册的类型
const timelinePlugin = this.app.pm.get<any>('@youchaoyun/plugin-timeline');
timelinePlugin?.registerTimelineCoverFieldInterfaces?.(['multipleEntryModesAttachment']);

使用建议

记录较多、文字较长时，优先使用 竖向 布局
强调阶段推进感时，优先使用 横向 布局
需要表达状态差异时，优先将 节点字段 配置为字典字段
需要更强视觉识别时，可以使用附件字段作为节点图片或标题图片