TimelineJS3 JSON数据格式详解：构建时间轴的核心要素-优快云博客

TimelineJS3 JSON数据格式详解：构建时间轴的核心要素

TimelineJS3 TimelineJS v3: A Storytelling Timeline built in JavaScript. http://timeline.knightlab.com 项目地址: https://gitcode.com/gh_mirrors/ti/TimelineJS3

什么是TimelineJS3 JSON格式

TimelineJS3是一个强大的开源工具，用于创建可视化时间轴。虽然大多数用户可以通过电子表格来配置时间轴，但当你需要动态创建或更新时间轴时，理解其JSON数据格式就变得至关重要。JSON格式提供了更灵活的方式来定义时间轴的所有元素和属性。

基础结构

TimelineJS3的JSON数据由一个主对象构成，包含以下关键属性：

{
  "events": [],
  "title": {},
  "eras": [],
  "scale": "human"
}

主要属性说明

events (必需)
- 类型：数组
- 描述：包含所有时间轴事件的"slide"对象列表
- 每个slide代表时间轴上的一个事件点或时间段
title (可选)
- 类型：对象
- 描述：定义时间轴的标题幻灯片
- 结构与普通slide类似，但不需要日期
eras (可选)
- 类型：数组
- 描述：定义时间轴上特定时期的"era"对象列表
- 用于在导航组件中标记时间段
scale (可选)
- 类型：字符串
- 可选值：human(默认) 或 cosmological
- 说明：cosmological尺度用于处理非常久远或未来的日期(公元前271,821年之前或公元275,760年之后)

Slide对象详解

Slide对象是构建时间轴的基本单元，每个slide代表时间轴上的一个事件或时间段。

核心属性

| 属性名 | 是否必需 | 说明 | |--------|----------|------| | start_date | 是(标题slide除外) | 定义事件开始时间的date对象 | | end_date | 否 | 定义事件结束时间的date对象 | | text | 推荐 | 包含标题和描述的text对象 | | media | 否 | 关联的媒体资源对象 | | group | 否 | 用于分组相关事件 | | display_date | 否 | 覆盖默认日期显示格式 | | background | 否 | 定义slide背景(图片或颜色) | | autolink | 否 | 是否自动转换文本中的链接(默认true) | | unique_id | 否 | 唯一标识符，用于编程控制 |

示例Slide

{
  "start_date": {
    "year": 1969,
    "month": 7,
    "day": 20
  },
  "text": {
    "headline": "人类首次登月",
    "text": "尼尔·阿姆斯特朗成为第一个踏上月球表面的人类。"
  },
  "media": {
    "url": "https://example.com/moon-landing.jpg",
    "caption": "登月舱",
    "credit": "NASA"
  }
}

Era对象详解

Era对象用于在时间轴导航组件上标记特定时期，结构上类似于简化的slide对象。

核心属性

| 属性名 | 是否必需 | 说明 | |--------|----------|------| | start_date | 是 | 时期开始时间的date对象 | | end_date | 是 | 时期结束时间的date对象 | | text | 推荐 | 描述时期的text对象 |

示例Era

{
  "start_date": {
    "year": 1914
  },
  "end_date": {
    "year": 1918
  },
  "text": {
    "headline": "第一次世界大战"
  }
}

Date对象详解

Date对象用于精确指定时间点，支持从年到毫秒的不同精度。

核心属性

| 属性名 | 是否必需 | 说明 | |--------|----------|------| | year | 是 | 年份(公元前用负数) | | month | 否 | 1-12(1=一月) | | day | 否 | 1-31 | | hour | 否 | 0-23 | | minute | 否 | 0-59 | | second | 否 | 0-59 | | millisecond | 否 | 0-999 | | display_date | 否 | 自定义日期显示格式 | | format | 否 | 日期格式化字符串 |

日期示例

{
  "year": 1066,
  "month": 10,
  "day": 14,
  "display_date": "1066年10月14日"
}

Text对象详解

Text对象包含事件的标题和描述文本，支持HTML标记。

核心属性

| 属性名 | 是否必需 | 说明 | |--------|----------|------| | headline | 否 | 事件标题(支持HTML) | | text | 否 | 事件详细描述(支持HTML) |

Media对象详解

Media对象用于关联事件的多媒体内容，如图片、视频等。

核心属性

| 属性名 | 是否必需 | 说明 | |--------|----------|------| | url | 是 | 媒体资源URL | | caption | 否 | 媒体说明文字(支持HTML) | | credit | 否 | 媒体来源/版权信息 | | thumbnail | 否 | 缩略图URL | | alt | 否 | 图片替代文本 | | title | 否 | 图片标题属性 | | link | 否 | 媒体链接URL | | link_target | 否 | 链接打开方式(如"_blank") |

最佳实践建议

日期处理：
- 对于精确日期，提供尽可能多的字段(年、月、日)
- 使用display_date自定义日期显示格式
- 公元前年份使用负数(如-500表示公元前500年)
媒体优化：
- 为所有图片提供alt文本以提高可访问性
- 使用thumbnail属性自定义时间轴标记图标
- 考虑为媒体添加适当的版权信息
组织技巧：
- 使用group属性将相关事件分组显示
- 为重要事件添加unique_id以便编程控制
- 合理使用eras划分历史时期
性能考虑：
- 优化媒体文件大小
- 考虑使用CDN托管媒体资源
- 对于大型时间轴，考虑分页加载数据